feat(TreeView): add ScrollIntoViewOptions parameter (#4349)

* fix: 增强脚本防止报错

* perf: 优化性能

* refactor: 增加父级节点跳转逻辑

* feat: 增加选中节点自动居中功能

* feat: 增加 ScrollIntoViewOptions 配置

* test: 更新单元测试

Author: ArgoZhang

src/BootstrapBlazor/Components/Drawer/Drawer.razor.js

@@ -61,7 +61,11 @@ const initDrag = el => {
 }
 
 export function init(id) {
-    const el = document.getElementById(id)
+    const el = document.getElementById(id);
+    if (el === null) {
+        return;
+    }
+
     const dw = {
         el,
         body: document.querySelector('body')

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

@@ -251,6 +251,12 @@ public partial class TreeView<TItem> : IModelEqualityComparer<TItem>
     [Parameter]
     public bool EnableKeyboardArrowUpDown { get; set; }
 
+    /// <summary>
+    /// 获得/设置 是否键盘上下键操作当前选中节点与视窗关系配置 默认 null 使用 { behavior: "smooth", block: "center", inline: "nearest" }
+    /// </summary>
+    [Parameter]
+    public ScrollIntoViewOptions? ScrollIntoViewOptions { get; set; }
+
     [CascadingParameter]
     private ContextMenuZone? ContextMenuZone { get; set; }
 
@@ -354,12 +360,30 @@ protected override async Task OnParametersSetAsync()
         }
     }
 
+    /// <summary>
+    /// <inheritdoc/>
+    /// </summary>
+    /// <param name="firstRender"></param>
+    /// <returns></returns>
+    protected override async Task OnAfterRenderAsync(bool firstRender)
+    {
+        await base.OnAfterRenderAsync(firstRender);
+
+        if (_keyboardArrowUpDownTrigger)
+        {
+            _keyboardArrowUpDownTrigger = false;
+            await InvokeVoidAsync("scroll", Id, ScrollIntoViewOptions ?? new() { Behavior = ScrollIntoViewBehavior.Smooth, Block = ScrollIntoViewBlock.Center, Inline = ScrollIntoViewInline.Nearest });
+        }
+    }
+
     /// <summary>
     /// <inheritdoc/>
     /// </summary>
     /// <returns></returns>
     protected override Task InvokeInitAsync() => InvokeVoidAsync("init", Id, Interop, nameof(TriggerKeyDown));
 
+    private bool _keyboardArrowUpDownTrigger;
+
     /// <summary>
     /// 客户端用户键盘操作处理方法 由 JavaScript 调用
     /// </summary>
@@ -372,8 +396,8 @@ public async ValueTask TriggerKeyDown(string key)
         // 如果兄弟节点没有时，找到父亲节点
         if (ActiveItem != null)
         {
+            _keyboardArrowUpDownTrigger = true;
             await ActiveTreeViewItem(key, ActiveItem);
-            StateHasChanged();
         }
     }
 
@@ -437,6 +461,10 @@ private async Task ActiveParentTreeViewItem(TreeViewItem<TItem> item)
         {
             await OnClick(items[index]);
         }
+        else if (item.Parent != null)
+        {
+            await ActiveParentTreeViewItem(item.Parent);
+        }
     }
 
     private async Task<bool> OnBeforeStateChangedCallback(TreeViewItem<TItem> item, CheckboxState state)

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

@@ -41,6 +41,17 @@ export function init(id, invoke, method) {
     });
 }
 
+export function scroll(id, options) {
+    const tree = Data.get(id)
+    if (tree) {
+        const { el } = tree;
+        const item = el.querySelector(".active .tree-node");
+        if (item) {
+            item.scrollIntoView(options);
+        }
+    }
+}
+
 export function dispose(id) {
     const tree = Data.get(id)
     Data.remove(id);

src/BootstrapBlazor/Options/ScrollIntoViewOptions.cs

@@ -0,0 +1,104 @@
+// Copyright (c) Argo Zhang ([email protected]). All rights reserved.
+// Licensed under the Apache License, Version 2.0. See License.txt in the project root for license information.
+// Website: https://www.blazor.zone or https://argozhang.github.io/
+
+using BootstrapBlazor.Core.Converter;
+
+namespace BootstrapBlazor.Components;
+
+/// <summary>
+/// ScrollIntoViewOptions 配置类
+/// </summary>
+public class ScrollIntoViewOptions
+{
+    /// <summary>
+    /// 获得/设置 滚动条宽度 默认 5px
+    /// </summary>
+    public ScrollIntoViewBehavior Behavior { get; set; }
+
+    /// <summary>
+    /// 获得/设置 滚动条鼠标悬浮宽度 默认 5px
+    /// </summary>
+    public ScrollIntoViewBlock Block { get; set; }
+
+    /// <summary>
+    /// 获得/设置 滚动条鼠标悬浮宽度 默认 5px
+    /// </summary>
+    public ScrollIntoViewInline Inline { get; set; }
+}
+
+/// <summary>
+/// Determines whether scrolling is instant or animates smoothly. This option is a string which must take one of the following values
+/// </summary>
+[JsonEnumConverter(true)]
+public enum ScrollIntoViewBehavior
+{
+    /// <summary>
+    /// scrolling should animate smoothly
+    /// </summary>
+    Smooth,
+
+    /// <summary>
+    /// scrolling should happen instantly in a single jump
+    /// </summary>
+    Instant,
+
+    /// <summary>
+    /// scroll behavior is determined by the computed value of scroll-behavior
+    /// </summary>
+    Auto
+}
+
+/// <summary>
+/// Defines vertical alignment
+/// </summary>
+[JsonEnumConverter(true)]
+public enum ScrollIntoViewBlock
+{
+    /// <summary>
+    /// Start
+    /// </summary>
+    Start,
+
+    /// <summary>
+    /// Center
+    /// </summary>
+    Center,
+
+    /// <summary>
+    /// End
+    /// </summary>
+    End,
+
+    /// <summary>
+    /// Nearest
+    /// </summary>
+    Nearest
+}
+
+/// <summary>
+/// Defines horizontal alignment
+/// </summary>
+[JsonEnumConverter(true)]
+public enum ScrollIntoViewInline
+{
+    /// <summary>
+    /// Start
+    /// </summary>
+    Start,
+
+    /// <summary>
+    /// Center
+    /// </summary>
+    Center,
+
+    /// <summary>
+    /// End
+    /// </summary>
+    End,
+
+    /// <summary>
+    /// Nearest
+    /// </summary>
+    Nearest
+}

test/UnitTest/Components/TreeViewTest.cs

@@ -876,43 +876,70 @@ public async Task Esc_Ok()
     [Fact]
     public async Task KeyBoard_Ok()
     {
-        var items = TreeFoo.GetTreeItems();
+        List<TreeFoo> data =
+        [
+            new() { Text = "1010", Id = "1010" },
+            new() { Text = "1020", Id = "1020" },
+            new() { Text = "1030", Id = "1030" },
+
+            new() { Text = "1020-01", Id = "1020-01", ParentId = "1020" },
+            new() { Text = "1020-02", Id = "1020-02", ParentId = "1020" },
+
+            new() { Text = "1020-02-01", Id = "1020-02-01", ParentId = "1020-02" },
+            new() { Text = "1020-02-02", Id = "1020-02-02", ParentId = "1020-02" },
+
+            new() { Text = "1020-02-02-01", Id = "1020-02-02-01", ParentId = "1020-02-02" },
+            new() { Text = "1020-02-02-02", Id = "1020-02-02-02", ParentId = "1020-02-02" }
+        ];
+
+        var items = TreeFoo.CascadingTree(data);
         items[0].IsActive = true;
         items[1].IsExpand = true;
         items[1].Items[1].IsExpand = true;
         items[1].Items[1].Items[1].IsExpand = true;
+
+        var activeItemText = "1010";
         var cut = Context.RenderComponent<TreeView<TreeFoo>>(pb =>
         {
             pb.Add(a => a.EnableKeyboardArrowUpDown, true);
             pb.Add(a => a.Items, items);
+            pb.Add(a => a.OnTreeItemClick, new Func<TreeViewItem<TreeFoo>, Task>(treeViewItem =>
+            {
+                activeItemText = treeViewItem.Text;
+                return Task.CompletedTask;
+            }));
         });
         await cut.InvokeAsync(() => cut.Instance.TriggerKeyDown("ArrowDown"));
         await cut.InvokeAsync(() => cut.Instance.TriggerKeyDown("ArrowDown"));
         await cut.InvokeAsync(() => cut.Instance.TriggerKeyDown("ArrowDown"));
+
         await cut.InvokeAsync(() => cut.Instance.TriggerKeyDown("ArrowDown"));
         await cut.InvokeAsync(() => cut.Instance.TriggerKeyDown("ArrowDown"));
         await cut.InvokeAsync(() => cut.Instance.TriggerKeyDown("ArrowDown"));
+
         await cut.InvokeAsync(() => cut.Instance.TriggerKeyDown("ArrowDown"));
         await cut.InvokeAsync(() => cut.Instance.TriggerKeyDown("ArrowDown"));
         await cut.InvokeAsync(() => cut.Instance.TriggerKeyDown("ArrowDown"));
+
         await cut.InvokeAsync(() => cut.Instance.TriggerKeyDown("ArrowDown"));
         await cut.InvokeAsync(() => cut.Instance.TriggerKeyDown("ArrowDown"));
-        await cut.InvokeAsync(() => cut.Instance.TriggerKeyDown("ArrowDown"));
-
+        Assert.Equal("1030", activeItemText);
 
-
-        await cut.InvokeAsync(() => cut.Instance.TriggerKeyDown("ArrowUp"));
         await cut.InvokeAsync(() => cut.Instance.TriggerKeyDown("ArrowUp"));
         await cut.InvokeAsync(() => cut.Instance.TriggerKeyDown("ArrowUp"));
         await cut.InvokeAsync(() => cut.Instance.TriggerKeyDown("ArrowUp"));
+
         await cut.InvokeAsync(() => cut.Instance.TriggerKeyDown("ArrowUp"));
         await cut.InvokeAsync(() => cut.Instance.TriggerKeyDown("ArrowUp"));
         await cut.InvokeAsync(() => cut.Instance.TriggerKeyDown("ArrowUp"));
+
         await cut.InvokeAsync(() => cut.Instance.TriggerKeyDown("ArrowUp"));
         await cut.InvokeAsync(() => cut.Instance.TriggerKeyDown("ArrowUp"));
         await cut.InvokeAsync(() => cut.Instance.TriggerKeyDown("ArrowUp"));
+
         await cut.InvokeAsync(() => cut.Instance.TriggerKeyDown("ArrowUp"));
         await cut.InvokeAsync(() => cut.Instance.TriggerKeyDown("ArrowUp"));
+        Assert.Equal("1010", activeItemText);
     }
 
     class MockTree<TItem> : TreeView<TItem> where TItem : class

test/UnitTest/Options/ScrollIntoViewOptionsTest.cs

@@ -0,0 +1,23 @@
+// Copyright (c) Argo Zhang ([email protected]). All rights reserved.
+// Licensed under the Apache License, Version 2.0. See License.txt in the project root for license information.
+// Website: https://www.blazor.zone or https://argozhang.github.io/
+
+using System.Text.Json;
+
+namespace UnitTest.Options;
+
+public class ScrollIntoViewOptionsTest
+{
+    [Fact]
+    public void Options_Ok()
+    {
+        var options = new ScrollIntoViewOptions()
+        {
+            Behavior = ScrollIntoViewBehavior.Auto,
+            Block = ScrollIntoViewBlock.Center,
+            Inline = ScrollIntoViewInline.End
+        };
+        var json = JsonSerializer.Serialize(options, new JsonSerializerOptions(JsonSerializerDefaults.Web));
+        Assert.Equal("{\"behavior\":\"auto\",\"block\":\"center\",\"inline\":\"end\"}", json);
+    }
+}