syncfusion-maui-treeview

实现 Syncfusion® .NET MAUI TreeView

Syncfusion .NET MAUI TreeView（SfTreeView）是一款功能强大的数据导向控件，可用于显示组织结构图、文件系统、嵌套连接和多级数据等分层数据结构。它提供直观的展开／折叠功能、多种选择模式、拖放支持以及丰富的自定义选项。

何时使用此技能

在以下情况下使用此技能：

• 分层数据显示：组织结构、文件浏览器、分类树、嵌套菜单
• 交互式树导航：可展开／折叠节点、多级浏览
• 数据绑定场景：使用 ItemsSource 的绑定模式，或手动创建节点的非绑定模式
• 选择需求：树结构中的单选、多选或扩展选择
• 自定义树形 UI：模板化节点、自定义展开器、样式化树项
• 高级树形功能：拖放重新排序、筛选、排序、按需加载
• MVVM 应用：带命令、数据绑定和 ViewModel 模式的 TreeView

组件概述

主要功能：

• 采用优化的视图复用策略，提升性能
• 绑定和非绑定数据模式
• 支持键盘导航的多种选择模式
• 项和展开器模板
• 带动画的展开／折叠
• 拖放重新排列节点
• 支持筛选和排序
• 支持大型数据集按需加载
• 支持 MVVM 模式
• 支持 RTL（从右到左）
• 可自定义外观和样式

文档和导航指南

入门

📄 阅读： references/getting-started.md

阅读时机： 首次设置 TreeView、初始配置、基本实现

涵盖内容：

• 安装 Syncfusion.Maui.TreeView NuGet 包
• 在 MauiProgram.cs 中注册 Syncfusion 处理程序
• 创建基本的 TreeView 控件
• 首个可运行示例

数据绑定和填充

📄 阅读： references/data-binding.md

阅读时机： 使用数据填充 TreeView、选择绑定／非绑定模式、处理分层数据结构

涵盖内容：

• 绑定和非绑定模式对比
• 不使用数据源创建节点（使用 TreeViewNode 的非绑定模式）
• 使用 ItemsSource 进行数据绑定（绑定模式）
• 使用 HierarchyPropertyDescriptors 处理复杂层次结构
• 配置 ChildPropertyName

选择

📄 阅读： references/selection.md

阅读时机： 实现节点选择、处理选择事件、自定义选择外观

涵盖内容：

• 选择模式：Single、SingleDeselect、Multiple、Extended、None
• SelectedItem、CurrentItem 和 SelectedItems 属性
• SelectionChanging 和 SelectionChanged 事件
• 自定义 SelectionBackground 和 SelectionForeground
• 键盘导航（WinUI、MacCatalyst）

节点展开和折叠

📄 阅读： references/expand-collapse.md

阅读时机： 配置展开／折叠行为、处理展开事件、设置节点初始状态

涵盖内容：

• AutoExpandMode 选项（None、AllNodes、RootNodes、特定层级）
• ExpandActionTarget（Expander、Node）
• NodeExpanding 和 NodeCollapsing 事件
• 用于单个节点的 IsExpanded 属性
• 展开／折叠动画

数据操作

📄 阅读： references/filtering.md

阅读时机： 筛选树节点、实现搜索功能、根据条件显示／隐藏节点、对树节点排序、自定义排序逻辑、多级排序

涵盖内容：

• FilterMode（None、Contains、StartsWith、Equals、Custom）
• 筛选 API（FilterText、FilterPath、FilterPaths、AutoExpandOnFilter、FilteredItems）
• SortComparer 配置
• 对各层级的分层数据进行排序

样式和外观

📄 阅读： references/styling-appearance.md

阅读时机： 自定义视觉外观、调整间距和缩进、应用主题、自定义节点外观、创建自定义展开器、设计树项 UI

涵盖内容：

• 自定义项高度（ItemHeight 属性）
• 嵌套层级的缩进设置
• 液态玻璃效果样式
• 背景色和前景色
• 边框和内边距自定义
• 主题集成
• ItemTemplate、ExpanderTemplate 自定义，以及用于条件模板的模板选择器
• ItemTemplateContextType（Node 与 Data 绑定上下文）

复选框

📄 阅读： references/styling-appearance.md

阅读时机： 为树节点添加复选框功能、跟踪已选中项、自定义复选框行为和外观

涵盖内容：

• 复选框启用和状态管理
• CheckBoxMode 配置：
  • None
  • Individual
  • Recursive
• TreeViewNode.IsChecked 属性
• CheckedItems 集合绑定
• GetCheckedNodes API
• CheckBoxPosition 和 CheckBoxWidth 自定义
• CheckActionTarget 配置
• 父子节点复选框递归同步
• 绑定模式和非绑定模式下的复选框处理
• 使用 SfCheckBox 的自定义复选框模板
• 以编程方式操作复选框

MVVM 支持

📄 阅读： references/mvvm-support.md

阅读时机： 使用 MVVM 模式实现 TreeView、使用命令和数据绑定

涵盖内容：

• TreeView 的 ViewModel 设置
• INotifyPropertyChanged 实现
• 节点操作的命令绑定
• 数据绑定的 ItemsSource
• MVVM 中的选择绑定
• 事件到命令的模式

滚动和导航

📄 阅读： references/scrolling-navigation.md

阅读时机： 以编程方式滚动、将项滚动到可见区域、键盘导航

涵盖内容：

• BringIntoView 方法及其所有重载
• 滚动位置选项（Start、Center、End、MakeVisible）
• 滚动动画控制
• 水平滚动配置
• 滚动条可见性控制
• 键盘导航（方向键、Tab）
• 事件（Loaded、ItemTapped、ItemDoubleTapped、ItemRightTapped）

项高度自定义

📄 阅读： references/item-height-customization.md

阅读时机： 自定义节点高度、动态调整大小、基于内容测量尺寸

涵盖内容：

• 静态 ItemHeight 属性
• 用于设置各项高度的 QueryNodeSize 事件
• NodeSizeMode 属性（Dynamic 或 None）
• GetActualNodeHeight 方法
• 动态高度计算

高级功能

📄 阅读： references/advanced-features.md

阅读时机： 实现高级 TreeView 操作和事件、从右向左显示、启用节点重新排序、实现拖放功能、自定义拖动行为、实现子节点延迟加载、处理大型数据集、基于 API 的层次结构、为节点添加复选框、处理选中/未选中状态、递归复选框模式、显示空状态、自定义无数据 UI、基于模板的空视图

涵盖内容：

• 以编程方式使用 TreeViewNode
• 从右向左（RTL）
• 事件
• 拖放
• 按需加载
• 复选框、CheckBoxMode（Recursive、Cascade、None）、使用已选中项集合
• 在项状态为空时显示视图
• 用于模板化空视图的 EmptyViewTemplate

故障排除

📄 阅读： references/troubleshooting.md

阅读时机： 调试问题、解决错误、排查优化问题

涵盖内容：

• 常见 TreeView 问题及解决方案
• 性能故障排除
• 数据绑定问题
• 选择功能无法正常工作
• 模板渲染问题