GithubStar/AtomUI
1
0
Fork 0
mirror of https://github.com/AtomUI/AtomUI.git synced 2026-10-19 23:30:44 +08:00
Code Issues Packages Projects Releases Wiki Activity
Files
684d72c185fbf995bde491dee1f7a4da617d50ca
AtomUI/docs/Desktop.Controls/TreeView/TreeViewAPI.md
T

333 lines
12 KiB
Markdown
Raw Blame History

This file contains ambiguous Unicode characters
This file contains Unicode characters that might be confused with other characters. If you think that this is intentional, you can safely ignore this warning. Use the Escape button to reveal them.
# TreeView API 参考
## 命名空间
```csharp
namespace AtomUI.Desktop.Controls;
```
AXAML 命名空间前缀：`atom`（`xmlns:atom="https://atomui.net"`）
---
## 枚举类型
### TreeItemHoverMode
节点悬浮高亮模式。
| 值 | 说明 |
|---|---|
| `Default` | 仅高亮节点文字区域（默认） |
| `Block` | 高亮整个节点行（包含缩进区域） |
| `WholeLine` | 高亮整行（从容器左到右） |
### TreeFilterHighlightStrategy（Flags 枚举）
搜索过滤高亮策略，支持组合使用。
| 值 | 说明 |
|---|---|
| `HighlightedMatch` (0x01) | 高亮匹配文本 |
| `HighlightedWhole` (0x02) | 高亮整个匹配节点 |
| `BoldedMatch` (0x04) | 加粗匹配文本 |
| `ExpandPath` (0x08) | 自动展开匹配节点的祖先路径 |
| `HideUnMatched` (0x10) | 隐藏未匹配的节点 |
| `All` | 以上全部策略组合（默认值） |
### ItemToggleType（来自 `AtomUI.Controls`）
节点勾选控件类型。
| 值 | 说明 |
|---|---|
| `None` | 不显示勾选控件（默认） |
| `CheckBox` | 显示 CheckBox 复选框 |
| `Radio` | 显示 Radio 单选按钮 |
---
## TreeView 公共属性
### 核心属性
| 属性名 | 类型 | 默认值 | 说明 |
|---|---|---|---|
| `IsAutoExpandParent` | `bool` | `true` | 是否自动展开父节点 |
| `IsDraggable` | `bool` | `false` | 是否启用拖拽排序 |
| `IsShowIcon` | `bool` | `false` | 是否显示节点图标 |
| `IsShowLine` | `bool` | `false` | 是否显示节点间连接线 |
| `IsDefaultExpandAll` | `bool` | `false` | 是否默认展开所有节点 |
| `IsShowLeafIcon` | `bool` | `false` | 是否显示叶子节点图标 |
| `IsSwitcherRotation` | `bool` | `true` | 展开/折叠图标是否使用旋转动画（`false` 时使用替换图标） |
| `IsSelectable` | `bool` | `true` | 节点是否可选中 |
| `IsCheckStrictly` | `bool` | `false` | 是否严格模式（`true` 时关闭父子联动勾选） |
| `NodeHoverMode` | `TreeItemHoverMode` | `Default` | 节点悬浮高亮模式 |
| `ToggleType` | `ItemToggleType` | `None` | 节点勾选控件类型（None/CheckBox/Radio） |
| `IsMotionEnabled` | `bool` | 跟随全局 Token | 是否启用展开/折叠动画（共享属性） |
### 自定义图标属性
| 属性名 | 类型 | 默认值 | 说明 |
|---|---|---|---|
| `SwitcherExpandIcon` | `IconTemplate?` | `null` | 自定义展开图标模板 |
| `SwitcherCollapseIcon` | `IconTemplate?` | `null` | 自定义折叠图标模板 |
| `SwitcherRotationIcon` | `IconTemplate?` | `null` | 自定义旋转图标模板（`IsSwitcherRotation=True` 时生效） |
| `SwitcherLoadingIcon` | `IconTemplate?` | `null` | 自定义加载中图标模板 |
| `SwitcherLeafIcon` | `IconTemplate?` | `null` | 自定义叶子节点图标模板 |
### 默认路径属性
| 属性名 | 类型 | 默认值 | 说明 |
|---|---|---|---|
| `DefaultExpandedPaths` | `IList<TreeNodePath>?` | `null` | 默认展开的节点路径列表 |
| `DefaultSelectedPaths` | `IList<TreeNodePath>?` | `null` | 默认选中的节点路径列表 |
| `DefaultCheckedPaths` | `IList<TreeNodePath>?` | `null` | 默认勾选的节点路径列表 |
### 异步加载属性
| 属性名 | 类型 | 默认值 | 说明 |
|---|---|---|---|
| `DataLoader` | `ITreeItemNodeLoader?` | `null` | 异步数据加载器 |
### 搜索过滤属性
| 属性名 | 类型 | 默认值 | 说明 |
|---|---|---|---|
| `Filter` | `ITreeItemFilter?` | `DefaultTreeItemFilter` | 自定义过滤器 |
| `FilterValue` | `object?` | `null` | 过滤关键词 |
| `FilterHighlightStrategy` | `TreeFilterHighlightStrategy` | `All` | 过滤高亮策略 |
| `FilterResultCount` | `int` | `0` | 过滤匹配结果数量（只读） |
| `FilterHighlightForeground` | `IBrush?` | `null` | 过滤高亮前景色（默认使用 Token 中的 `FilterHighlightColor`） |
### 动画属性
| 属性名 | 类型 | 默认值 | 说明 |
|---|---|---|---|
| `OpenMotion` | `AbstractMotion?` | `ExpandMotion` | 展开动画 |
| `CloseMotion` | `AbstractMotion?` | `CollapseMotion` | 折叠动画 |
### 空数据指示器属性
| 属性名 | 类型 | 默认值 | 说明 |
|---|---|---|---|
| `EmptyIndicator` | `object?` | `null` | 空数据指示器内容 |
| `EmptyIndicatorTemplate` | `IDataTemplate?` | `null` | 空数据指示器模板 |
| `IsShowEmptyIndicator` | `bool` | `true` | 是否在无数据时显示空状态指示器 |
| `EmptyIndicatorPadding` | `Thickness` | `default` | 空数据指示器内边距 |
### 勾选相关属性
| 属性名 | 类型 | 默认值 | 说明 |
|---|---|---|---|
| `CheckedItems` | `IList` | `AvaloniaList<object>` | 已勾选项集合（可读写） |
### 继承自 Avalonia.Controls.TreeView 的常用属性
| 属性名 | 类型 | 默认值 | 说明 |
|---|---|---|---|
| `Items` | `ItemCollection` | — | 直接添加子节点 |
| `ItemsSource` | `IEnumerable?` | `null` | 数据绑定源 |
| `ItemTemplate` | `IDataTemplate?` | `null` | 项数据模板（推荐 `TreeDataTemplate`） |
| `SelectedItem` | `object?` | `null` | 当前选中项 |
| `SelectedItems` | `IList?` | — | 选中项集合（多选） |
| `SelectionMode` | `SelectionMode` | `Single` | 选择模式 |
---
## TreeView 公共方法
| 方法名 | 签名 | 说明 |
|---|---|---|
| `ExpandAll` | `void ExpandAll(bool? motionEnabled = null)` | 展开所有节点。可选参数指定是否启用动画 |
| `CollapseAll` | `void CollapseAll(bool? motionEnabled = null)` | 折叠所有节点。可选参数指定是否启用动画 |
| `CheckedSubTree` | `void CheckedSubTree(TreeViewItem viewItem)` | 勾选指定节点及其所有子节点 |
| `UnCheckedSubTree` | `void UnCheckedSubTree(TreeViewItem viewItem)` | 取消勾选指定节点及其所有子节点 |
| `FilterTreeNode` | `void FilterTreeNode()` | 手动触发树节点过滤 |
---
## TreeView 事件
| 事件名 | 类型 | 说明 |
|---|---|---|
| `CheckedItemsChanged` | `EventHandler<TreeViewCheckedItemsChangedEventArgs>` | 勾选项发生变化时触发 |
| `TreeItemLoaded` | `EventHandler<TreeViewItemLoadedEventArgs>` | 异步加载节点完成时触发 |
| `ItemExpanded` | `EventHandler<TreeItemExpandedEventArgs>` | 节点展开时触发 |
| `ItemCollapsed` | `EventHandler<TreeItemCollapsedEventArgs>` | 节点折叠时触发 |
| `ItemClicked` | `EventHandler<TreeItemClickedEventArgs>` | 节点被点击时触发 |
| `ItemContextMenuRequest` | `EventHandler<TreeItemContextMenuEventArgs>` | 节点右键菜单请求时触发 |
| `ItemDragStarted` | `EventHandler<TreeViewDragStartedEventArgs>` | 拖拽开始时触发 |
| `ItemDragCompleted` | `EventHandler<TreeViewDragCompletedEventArgs>` | 拖拽完成时触发 |
| `ItemDragEnter` | `EventHandler<TreeViewDragEnterEventArgs>` | 拖拽进入节点时触发 |
| `ItemDragLeave` | `EventHandler<TreeViewDragLeaveEventArgs>` | 拖拽离开节点时触发 |
| `ItemDragOver` | `EventHandler<TreeViewDragOverEventArgs>` | 拖拽经过节点时触发 |
| `ItemDropped` | `EventHandler<TreeViewDroppedEventArgs>` | 拖拽放下时触发 |
### 事件参数说明
**TreeViewCheckedItemsChangedEventArgs**：
| 属性 | 类型 | 说明 |
|---|---|---|
| `AddedItems` | `IList` | 新增的勾选项 |
| `RemovedItems` | `IList` | 移除的勾选项 |
**TreeViewDragStartedEventArgs / TreeViewDragCompletedEventArgs**：
| 属性 | 类型 | 说明 |
|---|---|---|
| `ViewItem` | `TreeViewItem` | 被拖拽的节点 |
**TreeViewDragEnterEventArgs / TreeViewDragLeaveEventArgs / TreeViewDragOverEventArgs**：
| 属性 | 类型 | 说明 |
|---|---|---|
| `DraggedViewItem` | `TreeViewItem` | 被拖拽的节点 |
| `DragOverViewItem` | `TreeViewItem` | 经过的目标节点 |
**TreeViewDroppedEventArgs**：
| 属性 | 类型 | 说明 |
|---|---|---|
| `DraggedViewItem` | `TreeViewItem` | 被拖拽的节点 |
| `DroppedItem` | `TreeViewItem?` | 放下目标节点 |
| `DropIndex` | `int` | 插入位置索引 |
**TreeItemExpandedEventArgs / TreeItemCollapsedEventArgs / TreeItemClickedEventArgs**：
| 属性 | 类型 | 说明 |
|---|---|---|
| `ViewItem` | `TreeViewItem` | 相关的节点 |
---
## TreeView 伪类
| 伪类 | 常量 | 触发条件 |
|---|---|---|
| `:draggable` | `StdPseudoClass.Draggable` | `IsDraggable == true` |
### 继承的标准伪类
| 伪类 | 触发条件 |
|---|---|
| `:pointerover` | 鼠标悬浮 |
| `:disabled` | `IsEnabled == false` |
| `:focus` | 获得焦点 |
---
## TreeViewItem 公共属性
| 属性名 | 类型 | 默认值 | 说明 |
|---|---|---|---|
| `Icon` | `PathIcon?` | `null` | 节点自定义图标 |
| `IsChecked` | `bool?` | `false` | 三态勾选状态（`true` / `false` / `null` 表示半选） |
| `IsLeaf` | `bool` | 自动推断 | 是否为叶子节点（只读，由子节点数和 DataLoader 决定） |
| `IsLoading` | `bool` | `false` | 是否处于异步加载中 |
| `Value` | `object?` | `null` | 节点绑定值 |
| `GroupName` | `string?` | `null` | Radio 模式下的分组名称 |
| `IsIndicatorEnabled` | `bool` | `true` | 是否启用勾选指示器（`false` 时节点不可勾选） |
| `ItemKey` | `EntityKey?` | `null` | 节点唯一标识键 |
### 继承自 Avalonia.Controls.TreeViewItem 的常用属性
| 属性名 | 类型 | 默认值 | 说明 |
|---|---|---|---|
| `Header` | `object?` | `null` | 节点标题内容 |
| `HeaderTemplate` | `IDataTemplate?` | `null` | 标题模板 |
| `IsExpanded` | `bool` | `false` | 是否展开 |
| `IsSelected` | `bool` | `false` | 是否选中 |
| `Items` | `ItemCollection` | — | 子节点集合 |
| `Level` | `int` | 自动计算 | 节点层级（只读） |
| `IsEnabled` | `bool` | `true` | 是否启用 |
---
## TreeViewItem 事件
| 事件名 | 类型 | 说明 |
|---|---|---|
| `Click` | `EventHandler<RoutedEventArgs>` | 节点被点击时触发（路由事件，冒泡） |
| `ContextMenuRequest` | `EventHandler<RoutedEventArgs>` | 右键菜单请求事件（路由事件，冒泡+隧道） |
---
## TreeViewItem 伪类
| 伪类 | 常量 | 触发条件 |
|---|---|---|
| `:toggle` | `TreeViewPseudoClass.NodeToggleTypeCheckBox` | `ToggleType == CheckBox` |
| `:radio` | `TreeViewPseudoClass.NodeToggleTypeRadio` | `ToggleType == Radio` |
| `:checked` | `StdPseudoClass.Checked` | `IsChecked == true` |
### 继承的标准伪类
| 伪类 | 触发条件 |
|---|---|
| `:selected` | `IsSelected == true` |
| `:expanded` | `IsExpanded == true` |
| `:pointerover` | 鼠标悬浮 |
| `:disabled` | `IsEnabled == false` |
---
## 关联数据类型
### TreeItemNode（record）
`ITreeItemNode` 的默认实现，推荐用于 `ItemsSource` 数据绑定。
| 属性名 | 类型 | 默认值 | 说明 |
|---|---|---|---|
| `Header` | `object?` | `null` | 节点标题 |
| `ItemKey` | `EntityKey?` | `null` | 节点唯一标识 |
| `Icon` | `PathIcon?` | `null` | 节点图标 |
| `IsEnabled` | `bool` | `true` | 是否启用 |
| `IsChecked` | `bool?` | `false` | 勾选状态 |
| `IsSelected` | `bool` | `false` | 选中状态 |
| `IsExpanded` | `bool` | `false` | 展开状态 |
| `IsIndicatorEnabled` | `bool` | `true` | 是否可勾选 |
| `GroupName` | `string?` | `null` | Radio 分组名 |
| `IsLeaf` | `bool` | `false` | 是否叶子节点 |
| `Value` | `object?` | `null` | 节点值 |
| `Children` | `IList<ITreeItemNode>` | `[]` | 子节点列表 |
| `ParentNode` | `ITreeNode<ITreeItemNode>?` | 自动设置 | 父节点引用（只读） |
### TreeNodePath
节点路径，用于 `DefaultExpandedPaths` / `DefaultSelectedPaths` / `DefaultCheckedPaths`。
```csharp
// 路径格式：使用 "/" 分隔的 ItemKey 值
var path = new TreeNodePath("0-0/0-0-0/0-0-0-1");
```
### TreeItemLoadResult
异步加载结果模型。
| 属性名 | 类型 | 默认值 | 说明 |
|---|---|---|---|
| `IsSuccess` | `bool` | `true` | 是否加载成功 |
| `StatusCode` | `RpcStatusCode` | `Unknown` | 状态码 |
| `UserFriendlyMessage` | `string?` | `null` | 用户友好的错误消息 |
| `Data` | `IReadOnlyList<ITreeItemNode>?` | `null` | 加载的子节点数据 |
---
## 实现的接口
### IMotionAwareControl
```csharp
public bool IsMotionEnabled { get; set; }
```
控制展开/折叠动画是否启用。
### IFormItemAware
可作为 `FormItem` 的子控件参与表单验证流程。选择模式为 `Multiple` 时，表单值为 `SelectedItems`；否则为 `SelectedItem`。
Reference in New Issue View Git Blame Copy Permalink