feat(TreeView): support keyboard shortcut (#4345)

* refactor: 增加 EnableKeyboardArrowUpDown 参数

* refactor: 增加 js 回调

* feat: 增加客户端脚本逻辑

* feat: 实现上移下移逻辑

* feat: 增加 Enter 支持

* perf: 性能优化

* refactor: 精简代码提高可读性

* chore: bump version 8.9.4-beta02

* doc: 代码格式化

* refactor: 精简代码

* test: 更新单元测试

* doc: 增加示例

* doc: 更新本地化文档

Author: ArgoZhang

src/BootstrapBlazor.Server/Components/Components/CustomerSelectDialog.razor.cs

@@ -12,9 +12,9 @@ public partial class CustomerSelectDialog
     private IEnumerable<SelectedItem>? Items2;
     private readonly IEnumerable<SelectedItem> Items3 = new SelectedItem[]
     {
-            new SelectedItem ("", "请选择 ..."),
-            new SelectedItem ("Beijing", "北京"),
-            new SelectedItem ("Shanghai", "上海")
+        new("", "请选择 ..."),
+        new("Beijing", "北京"),
+        new("Shanghai", "上海")
     };
 
     /// <summary>
@@ -29,21 +29,21 @@ private async Task OnCascadeBindSelectClick(SelectedItem item)
         {
             Items2 = new SelectedItem[]
             {
-                    new SelectedItem("1","朝阳区"),
-                    new SelectedItem("2","海淀区"),
+                new("1","朝阳区"),
+                new("2","海淀区"),
             };
         }
         else if (item.Value == "Shanghai")
         {
             Items2 = new SelectedItem[]
             {
-                    new SelectedItem("1","静安区"),
-                    new SelectedItem("2","黄浦区"),
+                new("1","静安区"),
+                new("2","黄浦区"),
             };
         }
         else
         {
-            Items2 = Enumerable.Empty<SelectedItem>();
+            Items2 = [];
         }
         StateHasChanged();
     }

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

@@ -190,6 +190,13 @@
               MaxSelectedCount="2" OnMaxSelectedCountExceed="OnMaxSelectedCountExceed"></TreeView>
 </DemoBlock>
 
+<DemoBlock Title="@Localizer["TreeViewEnableKeyboardArrowUpDownTitle"]"
+           Introduction="@Localizer["TreeViewEnableKeyboardArrowUpDownIntro"]"
+           Name="Normal">
+    <section ignore>@_selectedValue</section>
+    <TreeView TItem="TreeFoo" Items="@KeyboardItems" OnTreeItemClick="@OnTreeItemKeyboardClick" EnableKeyboardArrowUpDown="true" />
+</DemoBlock>
+
 <AttributeTable Items="@GetAttributes()"></AttributeTable>
 
 <AttributeTable Items="@GetTreeItemAttributes()" Title="@Localizer["TreeViewsAttribute"]"></AttributeTable>

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

@@ -44,6 +44,8 @@ public sealed partial class TreeViews
 
     private List<TreeViewItem<TreeFoo>> CheckedItems2 { get; set; } = TreeFoo.GetTreeItems();
 
+    private List<TreeViewItem<TreeFoo>> KeyboardItems { get; set; } = TreeFoo.GetTreeItems();
+
     private List<SelectedItem> SelectedItems { get; set; } = TreeFoo.GetItems().Select(x => new SelectedItem(x.Id, x.Text)).ToList();
 
     private TreeView<TreeFoo>? SetActiveTreeView { get; set; }
@@ -54,12 +56,21 @@ public sealed partial class TreeViews
 
     private Foo Model => Foo.Generate(LocalizerFoo);
 
+    private string? _selectedValue;
+
     private Task OnTreeItemClick(TreeViewItem<TreeFoo> item)
     {
         Logger1.Log($"TreeItem: {item.Text} clicked");
         return Task.CompletedTask;
     }
 
+    private Task OnTreeItemKeyboardClick(TreeViewItem<TreeFoo> item)
+    {
+        _selectedValue = item.Value.Text;
+        StateHasChanged();
+        return Task.CompletedTask;
+    }
+
     private void OnRefresh()
     {
         CheckedItems = GetCheckedItems();

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

@@ -707,7 +707,9 @@
     "OnMaxSelectedCountExceedContent": "You can select at most {0} items",
     "TreeViewMaxSelectedCountTitle": "MaxSelectedCount",
     "TreeViewMaxSelectedCountIntro": "Control the maximum number of selectable items by setting the <code>MaxSelectedCount</code> property, and handle the logic through the <code>OnMaxSelectedCountExceed</code> callback",
-    "TreeViewMaxSelectedCountDesc": "When more than 2 nodes are selected, a <code>Toast</code> prompt bar will pop up"
+    "TreeViewMaxSelectedCountDesc": "When more than 2 nodes are selected, a <code>Toast</code> prompt bar will pop up",
+    "TreeViewEnableKeyboardArrowUpDownTitle": "Keyboard",
+    "TreeViewEnableKeyboardArrowUpDownIntro": "Support keyboard up and down arrow operations by setting <code>EnableKeyboardArrowUpDown=\"true\"</code>"
   },
   "BootstrapBlazor.Server.Components.Samples.Trees": {
     "TreeIntro": "<p>Obsolete，The <a href=\"treeviews\" alt=\"treeview\">TreeView</a> provides more functions",

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

@@ -707,7 +707,9 @@
     "OnMaxSelectedCountExceedContent": "最多只能选择 {0} 项",
     "TreeViewMaxSelectedCountTitle": "最大选择数量",
     "TreeViewMaxSelectedCountIntro": "通过设置 <code>MaxSelectedCount</code> 属性控制最大可选数量，通过 <code>OnMaxSelectedCountExceed</code> 回调处理逻辑",
-    "TreeViewMaxSelectedCountDesc": "选中节点超过 2 个时，弹出 <code>Toast</code> 提示栏"
+    "TreeViewMaxSelectedCountDesc": "选中节点超过 2 个时，弹出 <code>Toast</code> 提示栏",
+    "TreeViewEnableKeyboardArrowUpDownTitle": "键盘支持",
+    "TreeViewEnableKeyboardArrowUpDownIntro": "通过设置 <code>EnableKeyboardArrowUpDown=\"true\"</code> 支持键盘上下箭头操作"
   },
   "BootstrapBlazor.Server.Components.Samples.Trees": {
     "TreeIntro": "<p>本组件已弃用，请使用新组件 <a href=\"treeviews\" alt=\"treeview\">TreeView</a> 提供更多功能",

src/BootstrapBlazor/BootstrapBlazor.csproj

@@ -1,7 +1,7 @@
 <Project Sdk="Microsoft.NET.Sdk.Razor">
 
   <PropertyGroup>
-    <Version>8.9.4-beta01</Version>
+    <Version>8.9.4-beta02</Version>
   </PropertyGroup>
 
   <ItemGroup Condition="'$(TargetFramework)' == 'net5.0'">

src/BootstrapBlazor/Components/TreeView/TreeView.razor

@@ -1,7 +1,7 @@
 @namespace BootstrapBlazor.Components
 @typeparam TItem
 @inherits BootstrapModuleComponentBase
-@attribute [BootstrapModuleAutoLoader]
+@attribute [BootstrapModuleAutoLoader(JSObjectReference = true)]
 
 @if (Items == null)
 {
@@ -18,7 +18,7 @@
 }
 else
 {
-    <div @attributes="AdditionalAttributes" id="@Id" tabindex="0" class="@ClassString">
+    <div @attributes="AdditionalAttributes" id="@Id" tabindex="0" class="@ClassString" data-bb-keyboard-arrow-up-down="@EnableKeyboardArrowUpDownString">
         @if (ShowSearch)
         {
             @if (SearchTemplate == null)
@@ -37,7 +37,7 @@ else
                 @SearchTemplate
             }
         }
-        <ul class="tree-root scroll">
+        <ul class="tree-root scroll" tabindex="0">
             @foreach (var item in Items)
             {
                 @RenderTreeItem(item)
@@ -58,7 +58,7 @@ else
     private RenderFragment<TreeViewItem<TItem>> RenderTreeItem => item =>
     @<li class="@GetItemClassString(item)">
         <div class="tree-content" @oncontextmenu="e => OnContextMenu(e, item)" @oncontextmenu:preventDefault="IsPreventDefault" @ontouchstart="e => OnTouchStart(e, item)" @ontouchend="OnTouchEnd">
-            <DynamicElement TagName="i" class="@GetCaretClassString(item)" TriggerClick="TriggerNodeArrow(item)"  OnClick="() => OnToggleNodeAsync(item, true)"></DynamicElement>
+            <DynamicElement TagName="i" class="@GetCaretClassString(item)" TriggerClick="TriggerNodeArrow(item)" OnClick="() => OnToggleNodeAsync(item, true)"></DynamicElement>
             @if (ShowCheckbox)
             {
                 <Checkbox Value="@item.CheckedState" IsDisabled="GetItemDisabledState(item)" SkipValidate="true"

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

@@ -245,6 +245,12 @@ public partial class TreeView<TItem> : IModelEqualityComparer<TItem>
     [Parameter]
     public string? ExpandNodeIcon { get; set; }
 
+    /// <summary>
+    /// 获得/设置 是否开启键盘上下键操作 默认 false
+    /// </summary>
+    [Parameter]
+    public bool EnableKeyboardArrowUpDown { get; set; }
+
     [CascadingParameter]
     private ContextMenuZone? ContextMenuZone { get; set; }
 
@@ -283,6 +289,8 @@ public partial class TreeView<TItem> : IModelEqualityComparer<TItem>
 
     private string? _searchText;
 
+    private string? EnableKeyboardArrowUpDownString => EnableKeyboardArrowUpDown ? "true" : null;
+
     /// <summary>
     /// <inheritdoc/>
     /// </summary>
@@ -346,6 +354,91 @@ protected override async Task OnParametersSetAsync()
         }
     }
 
+    /// <summary>
+    /// <inheritdoc/>
+    /// </summary>
+    /// <returns></returns>
+    protected override Task InvokeInitAsync() => InvokeVoidAsync("init", Id, Interop, nameof(TriggerKeyDown));
+
+    /// <summary>
+    /// 客户端用户键盘操作处理方法 由 JavaScript 调用
+    /// </summary>
+    /// <param name="key"></param>
+    /// <returns></returns>
+    [JSInvokable]
+    public async ValueTask TriggerKeyDown(string key)
+    {
+        // 通过 ActiveItem 找到兄弟节点
+        // 如果兄弟节点没有时，找到父亲节点
+        if (ActiveItem != null)
+        {
+            await ActiveTreeViewItem(key, ActiveItem);
+            StateHasChanged();
+        }
+    }
+
+    private static bool IsExpand(TreeViewItem<TItem> item) => item.IsExpand && item.Items.Count > 0;
+
+    private List<TreeViewItem<TItem>> GetItems(TreeViewItem<TItem> item) => item.Parent?.Items ?? Items;
+
+    private async Task ActiveTreeViewItem(string key, TreeViewItem<TItem> item)
+    {
+        var items = GetItems(item);
+        var index = items.IndexOf(item);
+
+        if (key == "ArrowUp")
+        {
+            index--;
+            if (index >= 0)
+            {
+                var currentItem = items[index];
+                if (IsExpand(currentItem))
+                {
+                    await OnClick(currentItem.Items[^1]);
+                }
+                else
+                {
+                    await OnClick(currentItem);
+                }
+            }
+            else if (item.Parent != null)
+            {
+                await OnClick(item.Parent);
+            }
+        }
+        else if (key == "ArrowDown")
+        {
+            if (IsExpand(item))
+            {
+                await OnClick(item.Items[0]);
+            }
+            else
+            {
+                index++;
+                if (index < items.Count)
+                {
+                    await OnClick(items[index]);
+                }
+                else if (item.Parent != null)
+                {
+                    await ActiveParentTreeViewItem(item.Parent);
+                }
+            }
+        }
+    }
+
+    private async Task ActiveParentTreeViewItem(TreeViewItem<TItem> item)
+    {
+        var items = GetItems(item);
+        var index = items.IndexOf(item);
+
+        index++;
+        if (index < items.Count)
+        {
+            await OnClick(items[index]);
+        }
+    }
+
     private async Task<bool> OnBeforeStateChangedCallback(TreeViewItem<TItem> item, CheckboxState state)
     {
         var ret = true;
@@ -416,7 +509,7 @@ private async Task OnClick(TreeViewItem<TItem> item)
         if (ShowCheckbox && ClickToggleCheck)
         {
             item.CheckedState = ToggleCheckState(item.CheckedState);
-            await OnCheckStateChanged(item);
+            await OnCheckStateChanged(item, false);
         }
 
         StateHasChanged();

src/BootstrapBlazor/Components/TreeView/TreeView.razor.js

@@ -1,13 +1,13 @@
 import Data from "../../modules/data.js"
 import EventHandler from "../../modules/event-handler.js"
 
-export function init(id) {
+export function init(id, invoke, method) {
     const el = document.getElementById(id)
     if (el === null) {
         return
     }
 
-    const tree = {el}
+    const tree = { el };
     Data.set(id, tree)
 
     EventHandler.on(el, 'mouseenter', '.tree-content', e => {
@@ -20,7 +20,6 @@ export function init(id) {
         ele.classList.remove('hover')
     })
 
-    // 支持 Radio
     EventHandler.on(el, 'click', '.tree-node', e => {
         const node = e.delegateTarget
         const prev = node.previousElementSibling;
@@ -29,13 +28,28 @@ export function init(id) {
             radio.click();
         }
     })
+
+    EventHandler.on(el, 'keydown', '.tree-root', e => {
+        if (e.key === 'ArrowDown' || e.key === 'ArrowUp' || e.key === 'Enter') {
+            const v = el.getAttribute('data-bb-keyboard-arrow-up-down');
+            if (v === "true") {
+                e.preventDefault();
+
+                invoke.invokeMethodAsync(method, e.key);
+            }
+        }
+    });
 }
 
 export function dispose(id) {
     const tree = Data.get(id)
+    Data.remove(id);
+
     if (tree) {
-        EventHandler.off(tree.el, 'mouseenter')
-        EventHandler.off(tree.el, 'mouseleave')
-        EventHandler.off(tree.el, 'click', '.tree-node')
+        const { el } = tree;
+        EventHandler.off(el, 'mouseenter');
+        EventHandler.off(el, 'mouseleave');
+        EventHandler.off(el, 'click', '.tree-node');
+        EventHandler.off(el, 'keyup', '.tree-root');
     }
 }

src/BootstrapBlazor/Extensions/TreeItemExtensions.cs

@@ -41,5 +41,5 @@ public static class TreeItemExtensions
     /// <typeparam name="TItem"></typeparam>
     /// <param name="source"></param>
     /// <returns></returns>
-    public static IEnumerable<TreeViewItem<TItem>> GetAllSubItems<TItem>(this IEnumerable<TreeViewItem<TItem>> source) => source.SelectMany(i => i.Items.Any() ? i.Items.Concat(GetAllSubItems(i.Items)) : i.Items);
+    public static IEnumerable<TreeViewItem<TItem>> GetAllSubItems<TItem>(this IEnumerable<TreeViewItem<TItem>> source) => source.SelectMany(i => i.Items.Count > 0 ? i.Items.Concat(GetAllSubItems(i.Items)) : i.Items);
 }