mirror of
https://github.com/AtomUI/AtomUI.git
synced 2026-10-19 15:20:25 +08:00
chinboy
247 lines
9.2 KiB
Markdown
247 lines
9.2 KiB
Markdown
# TreeSelect API 参考
|
||
|
||
## 命名空间
|
||
|
||
```csharp
|
||
namespace AtomUI.Desktop.Controls;
|
||
```
|
||
|
||
AXAML 命名空间前缀：`atom`（`xmlns:atom="https://atomui.net"`）
|
||
|
||
---
|
||
|
||
## 枚举类型
|
||
|
||
### TreeSelectCheckedStrategy
|
||
|
||
勾选策略枚举（`[Flags]`），控制勾选模式下选中项的展示策略。
|
||
|
||
| 值 | 说明 |
|
||
|---|---|
|
||
| `ShowParent` (`0x1`) | 当所有子节点都被勾选时，仅展示父节点 |
|
||
| `ShowChild` (`0x2`) | 仅展示被勾选的叶子节点 |
|
||
| `All` (`ShowParent \| ShowChild`) | 展示所有被勾选的节点（默认值） |
|
||
|
||
### InputControlStyleVariant（来自 `AtomUI.Controls`）
|
||
|
||
输入控件样式变体枚举。
|
||
|
||
| 值 | 说明 |
|
||
|---|---|
|
||
| `Outline` | 带边框样式（默认） |
|
||
| `Filled` | 填充背景样式 |
|
||
| `Borderless` | 无边框样式 |
|
||
| `Underlined` | 下划线样式 |
|
||
|
||
### InputControlStatus（来自 `AtomUI.Controls`）
|
||
|
||
输入控件状态枚举。
|
||
|
||
| 值 | 说明 |
|
||
|---|---|
|
||
| `Default` | 默认状态 |
|
||
| `Error` | 错误状态（红色边框） |
|
||
| `Warning` | 警告状态（橙色边框） |
|
||
|
||
### SelectPopupPlacement
|
||
|
||
弹窗位置枚举。
|
||
|
||
| 值 | 说明 |
|
||
|---|---|
|
||
| `BottomEdgeAlignedLeft` | 底部左对齐（默认） |
|
||
| `BottomEdgeAlignedRight` | 底部右对齐 |
|
||
| `TopEdgeAlignedLeft` | 顶部左对齐 |
|
||
| `TopEdgeAlignedRight` | 顶部右对齐 |
|
||
|
||
### SizeType（来自 `AtomUI.Controls`）
|
||
|
||
尺寸类型枚举。
|
||
|
||
| 值 | 说明 |
|
||
|---|---|
|
||
| `Small` | 小号 |
|
||
| `Middle` | 中号（默认） |
|
||
| `Large` | 大号 |
|
||
|
||
### TreeFilterHighlightStrategy（来自 `AtomUI.Controls`）
|
||
|
||
树筛选高亮策略枚举（`[Flags]`）。
|
||
|
||
| 值 | 说明 |
|
||
|---|---|
|
||
| `HighlightedWhole` | 高亮匹配项整行 |
|
||
| `BoldedMatch` | 加粗匹配文字 |
|
||
| `ExpandPath` | 展开匹配项的路径 |
|
||
| `HideUnMatched` | 隐藏不匹配的节点 |
|
||
|
||
---
|
||
|
||
## 公共属性（TreeSelect 自有）
|
||
|
||
| 属性名 | 类型 | 默认值 | 说明 |
|
||
|---|---|---|---|
|
||
| `ShowCheckedStrategy` | `TreeSelectCheckedStrategy` | `All` | 勾选模式下，控制选中项在选择框中的展示策略 |
|
||
| `AutoScrollToSelectedItem` | `bool` | `true` | 打开下拉时是否自动滚动到选中项 |
|
||
| `IsShowIcon` | `bool` | `false` | 是否显示节点图标 |
|
||
| `IsShowLeafIcon` | `bool` | `false` | 是否显示叶子节点图标 |
|
||
| `IsShowLine` | `bool` | `false` | 是否在 TreeView 中显示连接线 |
|
||
| `IsTreeCheckable` | `bool` | `false` | 是否启用 Checkbox 勾选模式（设为 `true` 会自动将 `IsMultiple` 设为 `true`） |
|
||
| `IsMultiple` | `bool` | `false` | 是否启用多选模式 |
|
||
| `IsDefaultExpandAll` | `bool` | `false` | 是否默认展开所有节点 |
|
||
| `IsShowTreeLine` | `bool` | `false` | 是否显示树形连接线 |
|
||
| `IsSwitcherRotation` | `bool` | `false` | 展开/折叠按钮是否使用旋转动画（而非切换图标） |
|
||
| `IsTreeCheckStrictly` | `bool` | `false` | 严格勾选模式，父子节点勾选互不关联 |
|
||
| `TreeDefaultExpandedPaths` | `IList<TreeNodePath>?` | `null` | 默认展开的节点路径列表 |
|
||
| `ItemsSource` | `IEnumerable<ITreeItemNode>?` | `null` | 树形数据源 |
|
||
| `ItemTemplate` | `IDataTemplate?` | 内置 `TreeDataTemplate` | 自定义节点渲染模板 |
|
||
| `DataLoader` | `ITreeItemNodeLoader?` | `null` | 异步加载器，用于按需加载子节点 |
|
||
| `Filter` | `ITreeItemFilter?` | `DefaultTreeItemFilter` | 搜索筛选器 |
|
||
| `FilterHighlightStrategy` | `TreeFilterHighlightStrategy` | `HighlightedWhole \| BoldedMatch \| ExpandPath \| HideUnMatched` | 筛选高亮策略 |
|
||
| `FilterHighlightForeground` | `IBrush?` | `ColorPrimary` | 筛选匹配文字高亮颜色 |
|
||
| `SelectedItem` | `ITreeItemNode?` | `null` | 当前选中项（单选模式） |
|
||
| `SelectedItems` | `IList<ITreeItemNode>?` | `null` | 当前选中项列表（多选/勾选模式） |
|
||
| `Items` | `ItemCollection` | 空集合 | 直接操作的树节点集合（`[Content]` 属性） |
|
||
|
||
---
|
||
|
||
## 继承自 AbstractSelect 的公共属性
|
||
|
||
| 属性名 | 类型 | 默认值 | 说明 |
|
||
|---|---|---|---|
|
||
| `IsAllowClear` | `bool` | `false` | 是否显示清除按钮 |
|
||
| `IsAutoClearSearchValue` | `bool` | `false` | 选中后是否自动清空搜索框 |
|
||
| `IsDefaultOpen` | `bool` | `false` | 是否默认展开下拉弹窗 |
|
||
| `IsDropDownOpen` | `bool` | `false` | 下拉弹窗是否打开 |
|
||
| `PlaceholderText` | `string?` | `null` | 未选择时的占位提示文本 |
|
||
| `PlaceholderForeground` | `IBrush?` | `ColorTextPlaceholder` | 占位文本颜色 |
|
||
| `IsPopupMatchSelectWidth` | `bool` | `true` | 弹窗宽度是否匹配选择框宽度 |
|
||
| `IsFilterEnabled` | `bool` | `false` | 是否启用搜索筛选 |
|
||
| `DisplayPageSize` | `int` | `10` | 弹窗中可见的选项数量（影响弹窗最大高度） |
|
||
| `MaxCount` | `int` | `int.MaxValue` | 最大可选数量（多选模式） |
|
||
| `IsShowMaxCountIndicator` | `bool` | `false` | 是否显示已选/最大数量指示器 |
|
||
| `MaxTagCount` | `int?` | `null` | 多选模式下最大显示的 Tag 数量 |
|
||
| `IsResponsiveTagMode` | `bool` | `false` | 是否启用响应式 Tag 模式 |
|
||
| `MaxTagPlaceholder` | `string?` | `null` | 响应式模式下 Tag 被隐藏后显示的替代文本 |
|
||
| `LeftAddOn` | `object?` | `null` | 左侧附加内容（AddOn 区域） |
|
||
| `LeftAddOnTemplate` | `IDataTemplate?` | `null` | 左侧附加内容模板 |
|
||
| `RightAddOn` | `object?` | `null` | 右侧附加内容 |
|
||
| `RightAddOnTemplate` | `IDataTemplate?` | `null` | 右侧附加内容模板 |
|
||
| `ContentLeftAddOn` | `object?` | `null` | 内容区域左侧附加内容（前缀） |
|
||
| `ContentLeftAddOnTemplate` | `IDataTemplate?` | `null` | 内容区域左侧附加内容模板 |
|
||
| `ContentRightAddOn` | `object?` | `null` | 内容区域右侧附加内容 |
|
||
| `ContentRightAddOnTemplate` | `IDataTemplate?` | `null` | 内容区域右侧附加内容模板 |
|
||
| `StyleVariant` | `InputControlStyleVariant` | `Outline` | 样式变体（Outline / Filled / Borderless / Underlined） |
|
||
| `Status` | `InputControlStatus` | `Default` | 验证状态（Default / Error / Warning） |
|
||
| `Placement` | `SelectPopupPlacement` | `BottomEdgeAlignedLeft` | 弹窗弹出位置 |
|
||
| `FilterValue` | `object?` | `null` | 当前搜索筛选值 |
|
||
| `ClearIcon` | `PathIcon?` | `null` | 自定义清除按钮图标 |
|
||
| `SuffixIcon` | `PathIcon?` | `DownOutlined` | 下拉箭头图标 |
|
||
| `SuffixLoadingIcon` | `PathIcon?` | `LoadingOutlined（旋转）` | 加载状态图标 |
|
||
| `IsMotionEnabled` | `bool` | 跟随全局 Token | 是否启用弹窗展开/收起动画 |
|
||
| `SizeType` | `SizeType` | `SizeType.Middle` | 控件尺寸 |
|
||
| `EmptyIndicator` | `object?` | `null` | 空状态指示器内容 |
|
||
| `EmptyIndicatorTemplate` | `IDataTemplate?` | `null` | 空状态指示器模板 |
|
||
| `IsShowEmptyIndicator` | `bool` | `true` | 是否显示空状态指示器 |
|
||
| `EmptyIndicatorPadding` | `Thickness` | `default` | 空状态指示器内边距 |
|
||
| `IsLoading` | `bool` | `false` | 是否处于加载状态（只读） |
|
||
|
||
---
|
||
|
||
## 公共方法
|
||
|
||
| 方法名 | 返回类型 | 说明 |
|
||
|---|---|---|
|
||
| `Clear()` | `void` | 清空所有选中项（同时清空 `SelectedItem` 和 `SelectedItems`） |
|
||
|
||
---
|
||
|
||
## 事件
|
||
|
||
| 事件名 | 类型 | 说明 |
|
||
|---|---|---|
|
||
| `DropDownOpening` | `EventHandler<CancelEventArgs>` | 下拉弹窗即将打开时触发，可通过 `Cancel = true` 阻止打开 |
|
||
| `DropDownOpened` | `EventHandler` | 下拉弹窗已打开后触发 |
|
||
| `DropDownClosing` | `EventHandler<CancelEventArgs>` | 下拉弹窗即将关闭时触发，可通过 `Cancel = true` 阻止关闭 |
|
||
| `DropDownClosed` | `EventHandler` | 下拉弹窗已关闭后触发 |
|
||
|
||
---
|
||
|
||
## 伪类（Pseudo-Classes）
|
||
|
||
TreeSelect 支持以下伪类，可在样式选择器中使用：
|
||
|
||
### Select 共享伪类
|
||
|
||
| 伪类 | 常量 | 触发条件 |
|
||
|---|---|---|
|
||
| `:dropdownopen` | `SelectPseudoClass.DropdownOpen` | 下拉弹窗处于打开状态 |
|
||
|
||
### 从 AddOnDecoratedBox 继承的样式变体伪类
|
||
|
||
| 伪类 | 触发条件 |
|
||
|---|---|
|
||
| `:outline` | `StyleVariant == Outline` |
|
||
| `:filled` | `StyleVariant == Filled` |
|
||
| `:borderless` | `StyleVariant == Borderless` |
|
||
|
||
### 标准伪类
|
||
|
||
| 伪类 | 触发条件 |
|
||
|---|---|
|
||
| `:pressed` | 控件被按下（鼠标按住未释放） |
|
||
| `:disabled` | `IsEnabled == false` |
|
||
| `:focus-within` | 控件或其子控件获得焦点 |
|
||
| `:error` | `Status == Error` |
|
||
| `:warning` | `Status == Warning` |
|
||
|
||
---
|
||
|
||
## 实现的接口
|
||
|
||
### IMotionAwareControl
|
||
|
||
```csharp
|
||
public bool IsMotionEnabled { get; set; }
|
||
```
|
||
|
||
控制弹窗展开/收起动画是否启用。
|
||
|
||
### ISizeTypeAware
|
||
|
||
```csharp
|
||
public SizeType SizeType { get; set; }
|
||
```
|
||
|
||
支持 `Small` / `Middle` / `Large` 三种尺寸。
|
||
|
||
### IInputControlStatusAware
|
||
|
||
```csharp
|
||
public InputControlStatus Status { get; set; }
|
||
```
|
||
|
||
支持 `Default` / `Error` / `Warning` 三种验证状态。
|
||
|
||
### IInputControlStyleVariantAware
|
||
|
||
```csharp
|
||
public InputControlStyleVariant StyleVariant { get; set; }
|
||
```
|
||
|
||
支持 `Outline` / `Filled` / `Borderless` / `Underlined` 四种样式变体。
|
||
|
||
### ICompactSpaceAware
|
||
|
||
在 `Space.Compact` 容器中使用时自动调整圆角和边框。
|
||
|
||
### IFormItemAware
|
||
|
||
可作为 `FormItem` 的子控件参与表单验证流程。TreeSelect 实现了 `SetFormValue` / `GetFormValue` / `ClearFormValue`：
|
||
- 单选模式：表单值为 `ITreeItemNode?`
|
||
- 多选模式：表单值为 `IList<ITreeItemNode>?`
|
||
|
||
### IFormItemFeedbackAware
|
||
|
||
支持表单验证反馈控件展示（如错误/警告图标）。
|