feat(TreeView): improve AutoCheckParent logic (#8188)

* refactor: 脚本增加保护逻辑

* doc: 更新文档注释

* feat: 更新切换 AutoCheck 参数逻辑

* test: 更新单元测试

* chore: bump version 10.7.4-beta01

* chore: bump version 10.8.0

Author: ArgoZhang

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

@@ -5745,8 +5745,8 @@
     "TreeViewAccordionModelTitle": "Accordion mode",
     "TreeViewCheckboxAddButtonText": "Add",
     "TreeViewCheckboxButtonText": "Refresh",
-    "TreeViewCheckboxCheckBoxDisplayText1": "Automatically select child nodes",
-    "TreeViewCheckboxCheckBoxDisplayText2": "Automatically select parent node",
+    "TreeViewCheckboxCheckBoxDisplayText1": "Automatically update child nodes state",
+    "TreeViewCheckboxCheckBoxDisplayText2": "Automatically update parent node state (checked/indeterminate)",
     "TreeViewCheckboxIntro": "Suitable for use when you need to select a level",
     "TreeViewCheckboxTips1": "By setting the <code>OnTreeItemChecked</code> property to monitor the event when the tree control node is checked, when the check box in front of the tree control node is selected, the following log displays the data of the selected node",
     "TreeViewCheckboxTips2": "The <code>Tree</code> component will keep the status of each node when loading data. The <b>Refresh</b> button will update the data source <code>Items</code> and reinitialize the component. When you click the <code>Append Node</code> button, only the data inside the data source will be changed without reassigning values, so the status of each node will remain unchanged.",

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

@@ -5745,8 +5745,8 @@
     "TreeViewAccordionModelTitle": "手风琴模式",
     "TreeViewCheckboxAddButtonText": "追加节点",
     "TreeViewCheckboxButtonText": "刷新",
-    "TreeViewCheckboxCheckBoxDisplayText1": "自动选中子节点",
-    "TreeViewCheckboxCheckBoxDisplayText2": "自动选中父节点",
+    "TreeViewCheckboxCheckBoxDisplayText1": "自动更新子节点状态",
+    "TreeViewCheckboxCheckBoxDisplayText2": "自动更新父节点状态（全选/半选）",
     "TreeViewCheckboxIntro": "适用于需要选择层级时使用",
     "TreeViewCheckboxTips1": "通过设置 <code>OnTreeItemChecked</code> 属性监控树形控件节点被勾选时的事件，选中树形控件节点前复选框时下面日志显示选中节点的数据",
     "TreeViewCheckboxTips2": "<code>Tree</code> 组件数据加载内部将会保持各个节点状态，<b>刷新</b> 按钮将更新数据源 <code>Items</code>，组件重新初始化，点击 <code>追加节点</code> 按钮时，仅更改数据源内部数据未重新赋值，所以各个节点状态保持不变",

src/BootstrapBlazor/BootstrapBlazor.csproj

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

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

@@ -311,15 +311,15 @@ public partial class TreeView<TItem> : IModelEqualityComparer<TItem>
     public Func<TItem, string?, Task<bool>>? OnUpdateCallbackAsync { get; set; }
 
     /// <summary>
-    /// <para lang="zh">获得/设置 节点状态变化时是否自动更新子节点，默认为 false</para>
-    /// <para lang="en">Gets or sets whether to automatically update child nodes when the node state changes. Default is false</para>
+    /// <para lang="zh">获得/设置 节点状态变化时是否自动更新子节点状态 子节点状态与本节点保持一致，默认为 false</para>
+    /// <para lang="en">Gets or sets whether to automatically update child nodes state when the node state changes. Child nodes keep the same state as this node. Default is false</para>
     /// </summary>
     [Parameter]
     public bool AutoCheckChildren { get; set; }
 
     /// <summary>
-    /// <para lang="zh">获得/设置 节点状态变化时是否自动更新父节点，默认为 false</para>
-    /// <para lang="en">Gets or sets whether to automatically update parent nodes when the node state changes. Default is false</para>
+    /// <para lang="zh">获得/设置 节点状态变化时是否自动更新父节点状态 父节点状态由子节点状态派生 全部选中时为选中 全部未选中时为未选中 否则为半选，默认为 false。由 true 更改为 false 时 半选节点将重置为未选中</para>
+    /// <para lang="en">Gets or sets whether to automatically update parent nodes state when the node state changes. Parent state is derived from children: checked when all children are checked, unchecked when none are checked, otherwise indeterminate. Default is false. When changed from true to false, indeterminate nodes are reset to unchecked</para>
     /// </summary>
     [Parameter]
     public bool AutoCheckParent { get; set; }
@@ -358,6 +358,10 @@ public partial class TreeView<TItem> : IModelEqualityComparer<TItem>
     private bool _shouldRender = true;
     private bool _init;
     private bool _scrollIntoView = false;
+    private List<TreeViewItem<TItem>>? _lastItems;
+    private bool _lastShowCheckbox;
+    private bool _lastAutoCheckParent;
+    private bool _lastAutoCheckChildren;
 
     /// <summary>
     /// <inheritdoc/>
@@ -403,9 +407,16 @@ protected override async Task OnParametersSetAsync()
                 _rows = null;
             }
 
-            if (ShowCheckbox && (AutoCheckParent || AutoCheckChildren))
+            // 仅在数据源引用或级联勾选相关参数变化时重算勾选状态 普通重渲染不重算 防止覆盖用户显式设置的节点状态
+            if (ShowCheckbox && (AutoCheckParent || AutoCheckChildren) && IsCheckedParameterChanged())
             {
-                _treeNodeStateCache.IsChecked(Items);
+                _treeNodeStateCache.IsChecked(Items, AutoCheckParent);
+            }
+
+            // 关闭 AutoCheckParent 后半选状态失去派生来源 将半选节点重置为未选中
+            if (ShowCheckbox && _lastAutoCheckParent && !AutoCheckParent)
+            {
+                ResetIndeterminateNodes();
             }
 
             if (_activeItem != null)
@@ -421,6 +432,28 @@ protected override async Task OnParametersSetAsync()
                 _scrollIntoView = true;
             }
         }
+
+        _lastItems = Items;
+        _lastShowCheckbox = ShowCheckbox;
+        _lastAutoCheckParent = AutoCheckParent;
+        _lastAutoCheckChildren = AutoCheckChildren;
+    }
+
+    private bool IsCheckedParameterChanged() => !ReferenceEquals(_lastItems, Items)
+        || _lastShowCheckbox != ShowCheckbox
+        || _lastAutoCheckParent != AutoCheckParent
+        || _lastAutoCheckChildren != AutoCheckChildren;
+
+    private void ResetIndeterminateNodes()
+    {
+        foreach (var node in Items.GetAllItems())
+        {
+            if (node.CheckedState == CheckboxState.Indeterminate)
+            {
+                node.CheckedState = CheckboxState.UnChecked;
+                _treeNodeStateCache.ToggleCheck(node);
+            }
+        }
     }
 
     /// <summary>
@@ -527,13 +560,24 @@ public Task<List<CheckboxState>> GetParentsState(List<int> items)
         var rows = Rows;
         var result = items.Select(i =>
         {
-            var item = rows[i];
+            // 客户端回调期间数据源可能已更新 索引越界或无子节点时不重算 返回值数量与请求保持一一对应
+            var item = i >= 0 && i < rows.Count ? rows[i] : null;
+            if (item == null)
+            {
+                return CheckboxState.UnChecked;
+            }
+            if (item.Items.Count == 0)
+            {
+                return item.CheckedState;
+            }
+
             var checkedState = item.Items[0].CheckedState;
             if (item.Items.Any(s => s.CheckedState != checkedState))
             {
                 checkedState = CheckboxState.Indeterminate;
             }
             item.CheckedState = checkedState;
+            _treeNodeStateCache.ToggleCheck(item);
             return checkedState;
         }).ToList();
         return Task.FromResult(result);
@@ -763,6 +807,9 @@ private async Task OnToggleNodeAsync(TreeViewItem<TItem> node)
         // 手风琴效果逻辑
         node.IsExpand = !node.IsExpand;
 
+        // 展开节点无子项时将触发懒加载 新增子节点后需要同步级联勾选状态
+        var lazyLoad = node.IsExpand && node.HasChildren && node.Items.Count == 0;
+
         if (IsAccordion && !IsVirtualize)
         {
             await _treeNodeStateCache.ToggleNodeAsync(node, GetChildrenRowAsync);
@@ -788,18 +835,17 @@ private async Task OnToggleNodeAsync(TreeViewItem<TItem> node)
             _rows = null;
         }
 
-        if (ShowCheckbox)
+        // 仅在懒加载新增子节点后同步级联勾选状态 普通展开/折叠不重算 防止覆盖用户显式设置的节点状态
+        if (ShowCheckbox && lazyLoad && node.Items.Count > 0)
         {
             if (AutoCheckChildren)
             {
+                // 新增子节点继承本节点勾选状态
                 node.SetChildrenCheck(_treeNodeStateCache);
             }
             if (AutoCheckParent)
             {
-                node.SetParentCheck(_treeNodeStateCache);
-            }
-            if (!AutoCheckChildren && AutoCheckParent && node.Items.Count > 0)
-            {
+                // 由新增子节点状态派生本节点及其祖先节点状态
                 node.Items[0].SetParentCheck(_treeNodeStateCache);
             }
         }

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

@@ -173,9 +173,12 @@ export function toggleLoading(id, index, state) {
 
 export function setChildrenState(id, index, state) {
     const el = document.getElementById(id);
+    if (el === null) {
+        return;
+    }
     const node = el.querySelector(`[data-bb-tree-view-index="${index}"]`);
-    const level = parseInt(node.style.getPropertyValue('--bb-tree-view-level'));
     if (node) {
+        const level = parseInt(node.style.getPropertyValue('--bb-tree-view-level'));
         let next = node.nextElementSibling;
         while (next) {
             const currentLevel = parseInt(next.style.getPropertyValue('--bb-tree-view-level'));
@@ -195,9 +198,12 @@ export function setChildrenState(id, index, state) {
 
 export async function setParentState(id, invoke, method, index) {
     const el = document.getElementById(id);
+    if (el === null) {
+        return;
+    }
     const node = el.querySelector(`[data-bb-tree-view-index="${index}"]`);
-    let level = parseInt(node.style.getPropertyValue('--bb-tree-view-level'));
     if (node) {
+        let level = parseInt(node.style.getPropertyValue('--bb-tree-view-level'));
         const parents = [];
         let prev = node.previousElementSibling;
         while (prev) {

src/BootstrapBlazor/Misc/TreeNodeCache.cs

@@ -78,9 +78,9 @@ public void ToggleCheck(TNode node)
     /// <para lang="en">Check whether current node is checked</para>
     /// </summary>
     /// <param name="node"></param>
-    private void IsChecked(TNode node)
+    /// <param name="autoCheckParent"><para lang="zh">是否由子节点状态派生本节点状态</para><para lang="en">Whether to derive the node state from its children</para></param>
+    private void IsChecked(TNode node, bool autoCheckParent)
     {
-        var nodes = node.Items.OfType<ICheckableNode<TItem>>().ToList();
         if (_checkedNodeCache.Contains(node.Value))
         {
             node.CheckedState = CheckboxState.Checked;
@@ -94,7 +94,11 @@ private void IsChecked(TNode node)
             node.CheckedState = CheckboxState.Indeterminate;
         }
 
-        CheckChildren(nodes, node);
+        if (autoCheckParent)
+        {
+            var nodes = node.Items.OfType<ICheckableNode<TItem>>().ToList();
+            CheckChildren(nodes, node);
+        }
     }
 
     private void CheckChildren(List<ICheckableNode<TItem>> nodes, TNode node)
@@ -129,27 +133,28 @@ private void CheckChildren(List<ICheckableNode<TItem>> nodes, TNode node)
     /// <para lang="en">Reset checked state</para>
     /// </summary>
     /// <param name="nodes"></param>
-    public void IsChecked(List<TNode> nodes)
+    /// <param name="autoCheckParent"><para lang="zh">是否由子节点状态派生父节点状态 默认 true</para><para lang="en">Whether to derive parent state from children. Default is true</para></param>
+    public void IsChecked(List<TNode> nodes, bool autoCheckParent = true)
     {
         if (nodes.Count != 0)
         {
-            ResetCheckNodes(nodes);
+            ResetCheckNodes(nodes, autoCheckParent);
         }
     }
 
-    private void ResetCheckNodes(List<TNode> items)
+    private void ResetCheckNodes(List<TNode> items, bool autoCheckParent)
     {
         // 恢复当前节点状态
         foreach (var node in items)
         {
             // 恢复子节点
             if (node.Items.Any())
             {
-                IsChecked(node.Items.OfType<TNode>().ToList());
+                IsChecked(node.Items.OfType<TNode>().ToList(), autoCheckParent);
             }
 
             // 设置本节点
-            IsChecked(node);
+            IsChecked(node, autoCheckParent);
         }
     }