feat(TreeView): scripts to implement drag and drop function (#6380)

* feat:DraggableTree

* fix:修正格式错误

* 添加TreeView拖拽功能测试

* Enhance TreeView drag-and-drop and add comprehensive tests

Improved TreeView drag-and-drop logic to handle moving nodes without parents and updated node removal accordingly. Added and expanded unit tests to cover moving nodes as last child, first child, and as siblings below, ensuring correct parent/child relationships and node ordering. Also added clarifying comments in TreeViewRow for drag-and-drop preview UI.

* Add draggable TreeView demo with drop restrictions

Introduced a new demo block showcasing draggable TreeView nodes, including logic to restrict certain drag-and-drop operations. Added localized strings for the new demo in both English and Chinese. Updated the backend to provide a sample data set and drop event handler enforcing the restrictions.

* Refactor TreeView drag-and-drop and improve tests

Refactored TreeView and TreeViewRow to require OnItemDrop and remove null checks, simplifying drag-and-drop logic. Updated tests to cover cases where OnItemDrop is not set and to verify drag-and-drop visual feedback.

* refactor: 代码格式化

* refactor: 代码规范化

* refactor: 提高可读性

* refactor: 代码格式化

* refactor: 代码重构调整位置

* refactor: 更改参数名称为 AllowDrag

* revert: 重构 Row 对拖动支持

* refactor: 移除预留占位节点

* revert: 撤销更改

* revert: 撤销更改

* revert: 撤销 TreeDropType 类型

* doc: 更新文档

* test: 撤销单元测试更改

* refactor: 移除命名空间

* revert: 撤销 AllowDrag 参数

* revert: 撤销 AllowDrag 参数

* style: 调整样式

* style: 整理样式

* feat: JS 实现客户端拖动动画样式

* style: 精简样式

* feat: 增加 TriggerDragEnd 逻辑

* feat: JavaScript 实现拖动逻辑

* feat: 实现 OnDragItemEndAsync 逻辑

* doc: 更新示例

* feat: 增加重置客户端 DOM 逻辑

* doc: 更新示例

* doc: 撤销示例注释

* doc: 增加注释

* test: 更新单元测试

* fix: 增加逻辑保护

* doc: 更新文档

* chore: bump version 9.8.1-beta03

---------

Co-Authored-By: Symin <[email protected]>
Co-authored-by: Argo Zhang <[email protected]>

Author: syminomega

src/BootstrapBlazor.Server/Components/Samples/TreeViews.razor

@@ -52,6 +52,14 @@
     <ConsoleLogger @ref="Logger2"></ConsoleLogger>
 </DemoBlock>
 
+<DemoBlock Title="@Localizer["TreeViewDraggableTitle"]"
+           Introduction="@Localizer["TreeViewDraggableIntro"]"
+           Name="TreeDraggable">
+    <section ignore>@((MarkupString)Localizer["TreeViewDraggableDescription"].Value)</section>
+    <TreeView Items="@DraggableItems" AllowDrag="true" OnDragItemEndAsync="OnDragItemEndAsync">
+    </TreeView>
+</DemoBlock>
+
 <DemoBlock Title="@Localizer["TreeViewTreeDisableTitle"]"
            Introduction="@Localizer["TreeViewTreeDisableIntro"]"
            Name="TreeDisable">

src/BootstrapBlazor.Server/Components/Samples/TreeViews.razor.cs

@@ -3,6 +3,8 @@
 // See the LICENSE file in the project root for more information.
 // Maintainer: Argo Zhang([email protected]) Website: https://www.blazor.zone
 
+using DocumentFormat.OpenXml.Spreadsheet;
+
 namespace BootstrapBlazor.Server.Components.Samples;
 
 /// <summary>
@@ -33,6 +35,8 @@ public sealed partial class TreeViews
 
     private bool AutoCheckParent { get; set; }
 
+    private List<TreeViewItem<TreeFoo>> DraggableItems { get; set; } = [];
+
     private List<TreeViewItem<TreeFoo>> DisabledItems { get; } = GetDisabledItems();
 
     private List<TreeViewItem<TreeFoo>>? AccordionItems { get; } = TreeFoo.GetAccordionItems();
@@ -77,12 +81,61 @@ public sealed partial class TreeViews
 
     private string? _selectedValue;
 
+    /// <summary>
+    /// <inheritdoc/>
+    /// </summary>
+    protected override void OnInitialized()
+    {
+        base.OnInitialized();
+
+        var items = GetDraggableItems();
+        DraggableItems = TreeFoo.CascadingTree(items);
+        DraggableItems[0].IsExpand = true;
+        if (DraggableItems.Count > 1)
+        {
+            DraggableItems[1].IsExpand = true;
+        }
+        if (DraggableItems.Count > 2)
+        {
+            DraggableItems[2].IsExpand = true;
+        }
+    }
+
     private Task OnTreeItemClick(TreeViewItem<TreeFoo> item)
     {
         Logger1.Log($"TreeItem: {item.Text} clicked");
         return Task.CompletedTask;
     }
 
+    private Task OnDragItemEndAsync(TreeViewDragContext<TreeFoo> context)
+    {
+        // 本例是使用静态数据模拟数据库操作的，实战中应该是更新节点的父级 Id 可能还需要更改排序字段等信息，然后重构 TreeView 数据源即可
+        // 根据 context 处理原始数据
+        var items = GetDraggableItems();
+        var source = items.Find(i => i.Id == context.Source.Value.Id);
+        if (source != null)
+        {
+            var target = items.Find(i => i.Id == context.Target.Value.Id);
+            if (target != null)
+            {
+                source.ParentId = context.IsChildren ? target.Id : target.ParentId;
+            }
+        }
+        DraggableItems = TreeFoo.CascadingTree(items);
+        DraggableItems[0].IsExpand = true;
+        if (DraggableItems.Count > 1)
+        {
+            DraggableItems[1].IsExpand = true;
+        }
+        if (DraggableItems.Count > 2)
+        {
+            DraggableItems[2].IsExpand = true;
+        }
+
+        StateHasChanged();
+        return Task.CompletedTask;
+    }
+
     private Task OnTreeItemKeyboardClick(TreeViewItem<TreeFoo> item)
     {
         _selectedValue = item.Value.Text;
@@ -122,6 +175,28 @@ private Task OnTreeItemChecked(List<TreeViewItem<TreeFoo>> items)
         return Task.CompletedTask;
     }
 
+    private static List<TreeFoo>? _dragItems = null;
+    private static List<TreeFoo> GetDraggableItems()
+    {
+        _dragItems ??=
+        [
+            new() { Text = "Item A", Id = "1", Icon = "fa-solid fa-font-awesome" },
+            new() { Text = "Item D", Id = "4", ParentId = "1", Icon = "fa-solid fa-font-awesome" },
+            new() { Text = "Item E", Id = "5", ParentId = "1", Icon = "fa-solid fa-font-awesome" },
+
+            new() { Text = "Item B (Drop inside blocked)", Id = "2", Icon = "fa-solid fa-font-awesome" },
+            new() { Text = "Item F", Id = "6", ParentId = "2", Icon = "fa-solid fa-font-awesome" },
+            new() { Text = "Item G (Can not move out)", Id = "9", ParentId = "2", Icon = "fa-solid fa-font-awesome" },
+
+            new() { Text = "Item C", Id = "3", Icon = "fa-solid fa-font-awesome" },
+            new() { Text = "Item H", Id = "7", ParentId = "3", Icon = "fa-solid fa-font-awesome" },
+            new() { Text = "Item I", Id = "8", ParentId = "3", Icon = "fa-solid fa-font-awesome" },
+
+
+        ];
+        return _dragItems;
+    }
+
     private static List<TreeViewItem<TreeFoo>> GetDisabledItems()
     {
         var ret = TreeFoo.GetTreeItems();

src/BootstrapBlazor.Server/Locales/en-US.json

@@ -676,6 +676,9 @@
     "TreeViewCheckboxCheckBoxDisplayText2": "Automatically select parent node",
     "TreeViewCheckboxButtonText": "Refresh",
     "TreeViewCheckboxAddButtonText": "Add",
+    "TreeViewDraggableTitle": "Draggable nodes",
+    "TreeViewDraggableIntro": "Allows nodes to be dragged and dropped in the tree control",
+    "TreeViewDraggableDescription": "By setting the <code>AllowDrag</code> property, you can drag and drop nodes in the tree control. Use the <code>OnDragItemEndAsync</code> callback delegate to handle the drop event.",
     "TreeViewTreeDisableTitle": "Disabled state",
     "TreeViewTreeDisableIntro": "Some nodes of the Tree can be set to disabled state",
     "TreeViewTreeDisableDescription": "By setting the <code>Disabled</code> property of the data source <code>TreeViewItem</code> object, you can control whether this node can be checked or not. When set to <code>false</code>, it will not affect the node expansion. /shrink function",

src/BootstrapBlazor.Server/Locales/zh-CN.json

@@ -676,6 +676,9 @@
     "TreeViewCheckboxCheckBoxDisplayText2": "自动选中父节点",
     "TreeViewCheckboxButtonText": "刷新",
     "TreeViewCheckboxAddButtonText": "追加节点",
+    "TreeViewDraggableTitle": "可拖拽节点",
+    "TreeViewDraggableIntro": "使树中的节点可以进行跨层级拖拽操作",
+    "TreeViewDraggableDescription": "通过设置 <code>AllowDrag</code> 属性开启节点拖拽功能，使用 <code>OnDragItemEndAsync</code> 回调委托方法响应拖拽节点放置事件",
     "TreeViewTreeDisableTitle": "禁用状态",
     "TreeViewTreeDisableIntro": "可将 Tree 的某些节点设置为禁用状态",
     "TreeViewTreeDisableDescription": "通过设置数据源 <code>TreeViewItem</code> 对象的 <code>Disabled</code> 属性，来控制此节点是否可以进行勾选动作，设置为 <code>false</code> 时不影响节点展开/收缩功能",

src/BootstrapBlazor/BootstrapBlazor.csproj

@@ -1,7 +1,7 @@
 <Project Sdk="Microsoft.NET.Sdk.Razor">
 
   <PropertyGroup>
-    <Version>9.8.1-beta02</Version>
+    <Version>9.8.1-beta03</Version>
   </PropertyGroup>
 
   <ItemGroup>

src/BootstrapBlazor/Components/TreeView/TreeView.razor.cs

@@ -256,20 +256,6 @@ public partial class TreeView<TItem> : IModelEqualityComparer<TItem>
     [Parameter]
     public Func<TItem, string?, Task<bool>>? OnUpdateCallbackAsync { get; set; }
 
-    [NotNull]
-    private string? NotSetOnTreeExpandErrorMessage { get; set; }
-
-    [Inject]
-    [NotNull]
-    private IStringLocalizer<TreeView<TItem>>? Localizer { get; set; }
-
-    [Inject]
-    [NotNull]
-    private IIconTheme? IconTheme { get; set; }
-
-    [NotNull]
-    private TreeNodeCache<TreeViewItem<TItem>, TItem>? _treeNodeStateCache = null;
-
     /// <summary>
     /// Gets or sets whether to automatically update child nodes when the node state changes. Default is false.
     /// </summary>
@@ -282,12 +268,36 @@ public partial class TreeView<TItem> : IModelEqualityComparer<TItem>
     [Parameter]
     public bool AutoCheckParent { get; set; }
 
-    private string? _searchText;
+    /// <summary>
+    /// Gets or sets a value indicating whether drag-and-drop operations are allowed. Default is false
+    /// </summary>
+    [Parameter]
+    public bool AllowDrag { get; set; }
+
+    /// <summary>
+    /// 获得/设置 拖动标签页结束回调方法
+    /// </summary>
+    [Parameter]
+    public Func<TreeViewDragContext<TItem>, Task>? OnDragItemEndAsync { get; set; }
+
+    [Inject]
+    [NotNull]
+    private IStringLocalizer<TreeView<TItem>>? Localizer { get; set; }
+
+    [Inject]
+    [NotNull]
+    private IIconTheme? IconTheme { get; set; }
 
     private string? EnableKeyboardString => EnableKeyboard ? "true" : null;
 
-    private bool _shouldRender = true;
+    [NotNull]
+    private string? NotSetOnTreeExpandErrorMessage { get; set; }
 
+    [NotNull]
+    private TreeNodeCache<TreeViewItem<TItem>, TItem>? _treeNodeStateCache = null;
+
+    private string? _searchText;
+    private bool _shouldRender = true;
     private bool _init;
 
     /// <summary>
@@ -368,6 +378,11 @@ protected override async Task OnAfterRenderAsync(bool firstRender)
             _keyboardArrowUpDownTrigger = false;
             await InvokeVoidAsync("scroll", Id, ScrollIntoViewOptions);
         }
+
+        if(!firstRender && AllowDrag)
+        {
+            await InvokeVoidAsync("resetTreeViewRow", Id);
+        }
     }
 
     /// <summary>
@@ -380,7 +395,13 @@ protected override async Task OnAfterRenderAsync(bool firstRender)
     /// <inheritdoc/>
     /// </summary>
     /// <returns></returns>
-    protected override Task InvokeInitAsync() => InvokeVoidAsync("init", Id, new { Invoke = Interop, Method = nameof(TriggerKeyDown) });
+    protected override Task InvokeInitAsync() => InvokeVoidAsync("init", Id, new
+    {
+        Invoke = Interop,
+        Method = nameof(TriggerKeyDown),
+        AllowDrag,
+        TriggerDragEnd = nameof(TriggerDragEnd)
+    });
 
     private bool _keyboardArrowUpDownTrigger;
 
@@ -408,6 +429,30 @@ public async ValueTask TriggerKeyDown(string key)
         }
     }
 
+    /// <summary>
+    /// Triggers the end of a drag-and-drop operation within the tree view.
+    /// </summary>
+    /// <remarks>This method is invoked via JavaScript interop to signal the completion of a drag-and-drop
+    /// action. If a handler is assigned to <see cref="OnDragItemEndAsync"/>, it will be invoked with the drag
+    /// context.</remarks>
+    /// <param name="originIndex">The zero-based index of the item being dragged from its original position.</param>
+    /// <param name="currentIndex">The zero-based index of the item's current position after the drag operation.</param>
+    /// <param name="isChildren">A value indicating whether the drag operation involves child items.</param>
+    /// <returns></returns>
+    [JSInvokable]
+    public async ValueTask TriggerDragEnd(int originIndex, int currentIndex, bool isChildren)
+    {
+        if (OnDragItemEndAsync != null)
+        {
+            var context = new TreeViewDragContext<TItem>(
+                source: Rows[originIndex],
+                target: Rows[currentIndex],
+                children: isChildren
+            );
+            await OnDragItemEndAsync(context);
+        }
+    }
+
     /// <summary>
     /// Client-side method to query the state of the specified row checkbox, called by JavaScript
     /// </summary>