mirror of
https://github.com/AtomUI/AtomUI.git
synced 2026-10-21 16:36:27 +08:00
chinboy
247 lines
7.9 KiB
Markdown
247 lines
7.9 KiB
Markdown
# TreeSelect 自定义样式指南
|
||
|
||
TreeSelect 的视觉表现通过 `ControlTheme` + Design Token 系统控制。以下介绍几种常见的自定义方式。
|
||
|
||
---
|
||
|
||
## 1. 使用属性直接控制
|
||
|
||
最简单的方式是通过 TreeSelect 的公共属性来控制外观：
|
||
|
||
```xml
|
||
<!-- 不同样式变体 -->
|
||
<atom:TreeSelect StyleVariant="Outline" PlaceholderText="Outline" />
|
||
<atom:TreeSelect StyleVariant="Filled" PlaceholderText="Filled" />
|
||
<atom:TreeSelect StyleVariant="Borderless" PlaceholderText="Borderless" />
|
||
<atom:TreeSelect StyleVariant="Underlined" PlaceholderText="Underlined" />
|
||
|
||
<!-- 不同状态 -->
|
||
<atom:TreeSelect Status="Error" PlaceholderText="Error" />
|
||
<atom:TreeSelect Status="Warning" PlaceholderText="Warning" />
|
||
|
||
<!-- 不同尺寸 -->
|
||
<atom:TreeSelect SizeType="Large" PlaceholderText="Large" />
|
||
<atom:TreeSelect SizeType="Middle" PlaceholderText="Middle" />
|
||
<atom:TreeSelect SizeType="Small" PlaceholderText="Small" />
|
||
|
||
<!-- 多选模式 -->
|
||
<atom:TreeSelect IsMultiple="True" PlaceholderText="Multiple" />
|
||
|
||
<!-- 勾选模式 -->
|
||
<atom:TreeSelect IsTreeCheckable="True" ShowCheckedStrategy="ShowParent" PlaceholderText="Checkable" />
|
||
|
||
<!-- 带前缀 AddOn -->
|
||
<atom:TreeSelect LeftAddOn="Prefix" PlaceholderText="With prefix" />
|
||
<atom:TreeSelect ContentLeftAddOn="Prefix" PlaceholderText="With content prefix" />
|
||
|
||
<!-- 显示树线 -->
|
||
<atom:TreeSelect IsShowLine="True" IsSwitcherRotation="False" PlaceholderText="With tree line" />
|
||
|
||
<!-- 搜索筛选 -->
|
||
<atom:TreeSelect IsFilterEnabled="True" IsAllowClear="True" PlaceholderText="Search..." />
|
||
|
||
<!-- 最大选择数量 -->
|
||
<atom:TreeSelect IsMultiple="True" MaxCount="3" IsShowMaxCountIndicator="True" PlaceholderText="Max 3" />
|
||
```
|
||
|
||
> 📖 完整示例参考：`controlgallery/AtomUIGallery/ShowCases/Views/DataEntry/TreeSelectShowCase.axaml`
|
||
|
||
---
|
||
|
||
## 2. 通过 Style 覆盖样式
|
||
|
||
可以在 AXAML 中使用 `Style` 对 TreeSelect 进行全局或局部样式覆盖：
|
||
|
||
### 全局统一宽度
|
||
|
||
```xml
|
||
<Window.Styles>
|
||
<Style Selector="atom|TreeSelect">
|
||
<Setter Property="HorizontalAlignment" Value="Stretch" />
|
||
</Style>
|
||
</Window.Styles>
|
||
```
|
||
|
||
### 按样式变体定制边框颜色
|
||
|
||
```xml
|
||
<Style Selector="atom|TreeSelect:outline:not(:disabled)">
|
||
<Style Selector="^ /template/ atom|TreeSelectAddOnDecoratedBox#PART_AddOnDecoratedBox">
|
||
<Setter Property="BorderBrush" Value="#722ed1" />
|
||
</Style>
|
||
</Style>
|
||
```
|
||
|
||
### 按状态定制
|
||
|
||
```xml
|
||
<!-- 错误状态下自定义文字颜色 -->
|
||
<Style Selector="atom|TreeSelect:error">
|
||
<Setter Property="Foreground" Value="Red" />
|
||
</Style>
|
||
|
||
<!-- 警告状态下自定义文字颜色 -->
|
||
<Style Selector="atom|TreeSelect:warning">
|
||
<Setter Property="Foreground" Value="Orange" />
|
||
</Style>
|
||
```
|
||
|
||
### 使用伪类选择器
|
||
|
||
```xml
|
||
<!-- 下拉打开时的自定义样式 -->
|
||
<Style Selector="atom|TreeSelect:dropdownopen">
|
||
<Setter Property="Opacity" Value="0.9" />
|
||
</Style>
|
||
|
||
<!-- 禁用状态的自定义样式 -->
|
||
<Style Selector="atom|TreeSelect:disabled">
|
||
<Setter Property="Foreground" Value="Gray" />
|
||
</Style>
|
||
```
|
||
|
||
### 按属性选择器
|
||
|
||
```xml
|
||
<!-- 所有多选模式的 TreeSelect 设置最小高度 -->
|
||
<Style Selector="atom|TreeSelect[IsMultiple=True]">
|
||
<Setter Property="MinHeight" Value="40" />
|
||
</Style>
|
||
|
||
<!-- 所有大号 TreeSelect 使用粗体 -->
|
||
<Style Selector="atom|TreeSelect[SizeType=Large]">
|
||
<Setter Property="FontWeight" Value="SemiBold" />
|
||
</Style>
|
||
```
|
||
|
||
---
|
||
|
||
## 3. 通过 ControlTheme 完全替换主题
|
||
|
||
如果需要彻底替换 TreeSelect 的模板和样式，可以定义自定义 `ControlTheme`：
|
||
|
||
```xml
|
||
<ControlTheme x:Key="MyCustomTreeSelect" TargetType="atom:TreeSelect">
|
||
<Setter Property="Template">
|
||
<ControlTemplate>
|
||
<!-- 自定义模板 -->
|
||
</ControlTemplate>
|
||
</Setter>
|
||
</ControlTheme>
|
||
|
||
<!-- 使用 -->
|
||
<atom:TreeSelect Theme="{StaticResource MyCustomTreeSelect}" />
|
||
```
|
||
|
||
> ⚠️ 注意：完全替换 ControlTheme 将丢失内置的弹窗管理、装饰框、筛选、树线等功能。建议优先使用 Style 覆盖。
|
||
|
||
---
|
||
|
||
## 4. 自定义弹窗弹出位置
|
||
|
||
通过 `Placement` 属性和 `IsPopupMatchSelectWidth` 属性控制弹窗行为：
|
||
|
||
```xml
|
||
<!-- 弹窗在上方弹出，不匹配控件宽度 -->
|
||
<atom:TreeSelect Placement="TopEdgeAlignedLeft"
|
||
IsPopupMatchSelectWidth="False"
|
||
PlaceholderText="Top left popup" />
|
||
|
||
<!-- 弹窗在下方右对齐弹出 -->
|
||
<atom:TreeSelect Placement="BottomEdgeAlignedRight"
|
||
PlaceholderText="Bottom right popup" />
|
||
```
|
||
|
||
> 📖 参考：`controlgallery/AtomUIGallery/ShowCases/Views/DataEntry/TreeSelectShowCase.axaml` 中 "Placement" 示例。
|
||
|
||
---
|
||
|
||
## 5. 自定义筛选高亮
|
||
|
||
通过 `FilterHighlightForeground` 和 `FilterHighlightStrategy` 控制搜索匹配的高亮效果：
|
||
|
||
```xml
|
||
<atom:TreeSelect IsFilterEnabled="True"
|
||
FilterHighlightForeground="Red" />
|
||
```
|
||
|
||
---
|
||
|
||
## 6. 控制动画行为
|
||
|
||
```xml
|
||
<!-- 禁用弹窗展开/收起动画 -->
|
||
<atom:TreeSelect IsMotionEnabled="False" PlaceholderText="No animation" />
|
||
```
|
||
|
||
---
|
||
|
||
## 样式选择器速查
|
||
|
||
> 说明：Avalonia 样式选择器中使用 `atom|TreeSelect` 语法引用 `atom` XML 命名空间下的 `TreeSelect` 类型，其中 `|` 是命名空间分隔符。
|
||
|
||
### 基础选择器
|
||
|
||
| 选择器 | 说明 |
|
||
|---|---|
|
||
| `atom\|TreeSelect` | 匹配所有 AtomUI TreeSelect 实例 |
|
||
| `atom\|TreeSelect:disabled` | 匹配禁用状态 |
|
||
| `atom\|TreeSelect:dropdownopen` | 匹配下拉弹窗打开状态 |
|
||
| `atom\|TreeSelect:pressed` | 匹配按下状态 |
|
||
| `atom\|TreeSelect:focus-within` | 匹配内部获得焦点的状态 |
|
||
|
||
### 按样式变体选择
|
||
|
||
| 选择器 | 说明 |
|
||
|---|---|
|
||
| `atom\|TreeSelect:outline` | 匹配 Outline 变体（带边框，默认） |
|
||
| `atom\|TreeSelect:filled` | 匹配 Filled 变体（填充背景） |
|
||
| `atom\|TreeSelect:borderless` | 匹配 Borderless 变体（无边框） |
|
||
|
||
### 按状态选择
|
||
|
||
| 选择器 | 说明 |
|
||
|---|---|
|
||
| `atom\|TreeSelect:error` | 匹配错误状态（`Status == Error`） |
|
||
| `atom\|TreeSelect:warning` | 匹配警告状态（`Status == Warning`） |
|
||
|
||
### 按尺寸选择
|
||
|
||
| 选择器 | 说明 |
|
||
|---|---|
|
||
| `atom\|TreeSelect[SizeType=Large]` | 匹配大号 TreeSelect |
|
||
| `atom\|TreeSelect[SizeType=Middle]` | 匹配中号 TreeSelect（默认） |
|
||
| `atom\|TreeSelect[SizeType=Small]` | 匹配小号 TreeSelect |
|
||
|
||
### 按属性选择
|
||
|
||
| 选择器 | 说明 |
|
||
|---|---|
|
||
| `atom\|TreeSelect[IsMultiple=True]` | 匹配多选模式 |
|
||
| `atom\|TreeSelect[IsMultiple=False]` | 匹配单选模式 |
|
||
| `atom\|TreeSelect[IsFilterEnabled=True]` | 匹配启用了搜索筛选的 TreeSelect |
|
||
| `atom\|TreeSelect[IsDropDownOpen=True]` | 匹配下拉弹窗打开状态（属性选择器写法） |
|
||
| `atom\|TreeSelect[StyleVariant=Filled]` | 按属性匹配 Filled 变体 |
|
||
| `atom\|TreeSelect[Status=Error]` | 按属性匹配错误状态 |
|
||
|
||
### 模板部件访问
|
||
|
||
| 选择器 | 说明 |
|
||
|---|---|
|
||
| `atom\|TreeSelect /template/ atom\|TreeSelectAddOnDecoratedBox#PART_AddOnDecoratedBox` | 访问装饰框部件 |
|
||
| `atom\|TreeSelect /template/ Border#PopupFrame` | 访问弹窗容器 Border |
|
||
| `atom\|TreeSelect /template/ ContentPresenter#SingleSelectResultPresenter` | 访问单选模式下的选中项展示器 |
|
||
| `atom\|TreeSelect /template/ atom\|SelectFilterTextBox#PART_SingleFilterInput` | 访问单选搜索输入框 |
|
||
| `atom\|TreeSelect /template/ atom\|SelectTagAwareTextBox#SelectedItemsBox` | 访问多选模式下的 Tag 容器 |
|
||
| `atom\|TreeSelect /template/ atom\|TreeSelectTreeView#PART_TreeView` | 访问内嵌 TreeView |
|
||
|
||
### 组合选择器示例
|
||
|
||
| 选择器 | 说明 |
|
||
|---|---|
|
||
| `atom\|TreeSelect[IsMultiple=False][IsFilterEnabled=False]` | 单选且未启用筛选的 TreeSelect |
|
||
| `atom\|TreeSelect[IsMultiple=False][IsFilterEnabled=True]:dropdownopen` | 单选筛选模式下弹窗打开时 |
|
||
| `atom\|TreeSelect[IsMultiple=True]:not(:disabled)` | 非禁用的多选 TreeSelect |
|
||
| `atom\|TreeSelect:error:outline` | Outline 变体 + 错误状态 |
|
||
| `atom\|TreeSelect:warning:filled` | Filled 变体 + 警告状态 |
|