mirror of
https://github.com/AtomUI/AtomUI.git
synced 2026-10-24 02:09:37 +08:00
chinboy
282 lines
9.1 KiB
Markdown
282 lines
9.1 KiB
Markdown
# AutoComplete 自定义样式指南
|
||
|
||
AutoComplete 的视觉表现通过 `ControlTheme` + Design Token 系统控制。以下介绍几种常见的自定义方式。
|
||
|
||
---
|
||
|
||
## 1. 使用属性直接控制
|
||
|
||
最简单的方式是通过 AutoComplete 的公共属性来控制外观：
|
||
|
||
```xml
|
||
<!-- 不同样式变体 -->
|
||
<atom:AutoComplete StyleVariant="Outline" PlaceholderText="Outline" Width="200" />
|
||
<atom:AutoComplete StyleVariant="Filled" PlaceholderText="Filled" Width="200" />
|
||
<atom:AutoComplete StyleVariant="Borderless" PlaceholderText="Borderless" Width="200" />
|
||
<atom:AutoComplete StyleVariant="Underlined" PlaceholderText="Underlined" Width="200" />
|
||
|
||
<!-- 不同尺寸 -->
|
||
<atom:AutoComplete SizeType="Large" PlaceholderText="Large" Width="200" />
|
||
<atom:AutoComplete SizeType="Middle" PlaceholderText="Middle" Width="200" />
|
||
<atom:AutoComplete SizeType="Small" PlaceholderText="Small" Width="200" />
|
||
|
||
<!-- 验证状态 -->
|
||
<atom:AutoComplete Status="Error" Width="200" />
|
||
<atom:AutoComplete Status="Warning" Width="200" />
|
||
|
||
<!-- 允许清除 + 自定义清除图标 -->
|
||
<atom:AutoComplete IsAllowClear="True" Width="200" />
|
||
<atom:AutoComplete IsAllowClear="True"
|
||
ClearIcon="{antdicons:AntDesignIconProvider CloseSquareFilled}"
|
||
Width="200" />
|
||
|
||
<!-- 搜索型 -->
|
||
<atom:AutoCompleteSearchEdit SizeType="Large" SearchButtonStyle="Primary"
|
||
PlaceholderText="input here" Width="300" />
|
||
|
||
<!-- 多行文本型 -->
|
||
<atom:AutoCompleteTextArea Lines="5" IsAllowClear="True"
|
||
PlaceholderText="input here" Width="300" />
|
||
```
|
||
|
||
> 📖 完整示例参考：`controlgallery/AtomUIGallery/ShowCases/Views/DataEntry/AutoCompleteShowCase.axaml`
|
||
|
||
---
|
||
|
||
## 2. 通过 Style 覆盖样式
|
||
|
||
可以在 AXAML 中使用 `Style` 对 AutoComplete 进行全局或局部样式覆盖：
|
||
|
||
### 全局统一宽度
|
||
|
||
```xml
|
||
<Window.Styles>
|
||
<Style Selector="atom|AutoComplete">
|
||
<Setter Property="Width" Value="250" />
|
||
<Setter Property="Margin" Value="0 5" />
|
||
</Style>
|
||
</Window.Styles>
|
||
```
|
||
|
||
### 按变体定制样式
|
||
|
||
```xml
|
||
<Style Selector="atom|AutoComplete[StyleVariant=Filled]">
|
||
<Setter Property="Margin" Value="0 8" />
|
||
</Style>
|
||
```
|
||
|
||
### 按验证状态定制样式
|
||
|
||
```xml
|
||
<!-- Error 状态时增加粗体 -->
|
||
<Style Selector="atom|AutoComplete[Status=Error]">
|
||
<Setter Property="FontWeight" Value="Bold" />
|
||
</Style>
|
||
```
|
||
|
||
### 使用伪类选择器
|
||
|
||
```xml
|
||
<!-- 候选列表打开时的自定义样式 -->
|
||
<Style Selector="atom|AutoComplete:candidateopen">
|
||
<Setter Property="Opacity" Value="0.95" />
|
||
</Style>
|
||
|
||
<!-- 禁用状态 -->
|
||
<Style Selector="atom|AutoComplete:disabled">
|
||
<Setter Property="Opacity" Value="0.5" />
|
||
</Style>
|
||
```
|
||
|
||
---
|
||
|
||
## 3. 自定义候选项模板
|
||
|
||
通过 `OptionTemplate` 属性自定义候选项的渲染方式：
|
||
|
||
### 简单文本模板（默认）
|
||
|
||
默认模板已内置，展示 `Header` 文本：
|
||
|
||
```xml
|
||
<atom:AutoComplete>
|
||
<atom:AutoComplete.OptionTemplate>
|
||
<DataTemplate x:DataType="atom:IAutoCompleteOption">
|
||
<TextBlock Text="{Binding Header}" TextTrimming="CharacterEllipsis" />
|
||
</DataTemplate>
|
||
</atom:AutoComplete.OptionTemplate>
|
||
</atom:AutoComplete>
|
||
```
|
||
|
||
### 多列信息模板
|
||
|
||
```xml
|
||
<atom:AutoCompleteSearchEdit Width="300" SizeType="Large" SearchButtonStyle="Primary">
|
||
<atom:AutoCompleteSearchEdit.OptionTemplate>
|
||
<DataTemplate x:DataType="viewModels:CustomAutoCompleteOption">
|
||
<DockPanel LastChildFill="True">
|
||
<TextBlock Text="results"
|
||
DockPanel.Dock="Right"
|
||
Margin="5 0 0 0" />
|
||
<TextBlock Text="{Binding ResultCount}"
|
||
DockPanel.Dock="Right" />
|
||
<TextBlock Text="{Binding Header}"
|
||
TextTrimming="CharacterEllipsis" />
|
||
</DockPanel>
|
||
</DataTemplate>
|
||
</atom:AutoCompleteSearchEdit.OptionTemplate>
|
||
</atom:AutoCompleteSearchEdit>
|
||
```
|
||
|
||
> 📖 参考：`controlgallery/AtomUIGallery/ShowCases/Views/DataEntry/AutoCompleteShowCase.axaml` 中 "Lookup-Patterns" 示例。
|
||
|
||
---
|
||
|
||
## 4. 通过 ControlTheme 完全替换主题
|
||
|
||
如果需要彻底替换 AutoComplete 的模板和样式，可以定义自定义 `ControlTheme`：
|
||
|
||
```xml
|
||
<ControlTheme x:Key="MyCustomAutoComplete" TargetType="atom:AutoComplete">
|
||
<Setter Property="Template">
|
||
<ControlTemplate>
|
||
<Panel>
|
||
<!-- 自定义输入框 -->
|
||
<atom:AutoCompleteLineEditBox Name="PART_TextBox"
|
||
PlaceholderText="{TemplateBinding PlaceholderText}"
|
||
SizeType="{TemplateBinding SizeType}" />
|
||
<!-- 自定义弹出层 -->
|
||
<atom:Popup Name="PART_Popup"
|
||
Placement="{TemplateBinding PopupPlacement}">
|
||
<Border>
|
||
<atom:CandidateList Name="PART_CandidateList"
|
||
SelectionMode="Single"
|
||
ItemTemplate="{TemplateBinding OptionTemplate}" />
|
||
</Border>
|
||
</atom:Popup>
|
||
</Panel>
|
||
</ControlTemplate>
|
||
</Setter>
|
||
</ControlTheme>
|
||
|
||
<!-- 使用 -->
|
||
<atom:AutoComplete Theme="{StaticResource MyCustomAutoComplete}" />
|
||
```
|
||
|
||
> ⚠️ 注意：完全替换 ControlTheme 需要确保模板中包含 `PART_TextBox`、`PART_Popup`、`PART_CandidateList` 三个必需部件，否则控件行为将不正常。
|
||
|
||
---
|
||
|
||
## 5. 自定义过滤模式
|
||
|
||
### 在 AXAML 中使用内置过滤器
|
||
|
||
```xml
|
||
<!-- 包含匹配（不区分大小写） -->
|
||
<atom:AutoComplete Filter="{atom:ValueFilterProvider Contains}" />
|
||
|
||
<!-- 前缀匹配（区分大小写） -->
|
||
<atom:AutoComplete Filter="{atom:ValueFilterProvider StartsWithCaseSensitive}" />
|
||
|
||
<!-- 完全匹配 -->
|
||
<atom:AutoComplete Filter="{atom:ValueFilterProvider Equals}" />
|
||
```
|
||
|
||
> 📖 参考：`controlgallery/AtomUIGallery/ShowCases/Views/DataEntry/AutoCompleteShowCase.axaml` 中 "Non-case-sensitive AutoComplete" 示例。
|
||
|
||
### 在代码中实现自定义过滤器
|
||
|
||
```csharp
|
||
public class PinyinFilter : IValueFilter
|
||
{
|
||
public ValueFilterMode Mode => ValueFilterMode.Custom;
|
||
|
||
public bool Filter(object? value, object? filterValue)
|
||
{
|
||
// 自定义拼音匹配逻辑
|
||
var text = value?.ToString() ?? "";
|
||
var keyword = filterValue?.ToString() ?? "";
|
||
return PinyinHelper.Contains(text, keyword);
|
||
}
|
||
}
|
||
|
||
// 使用
|
||
autoComplete.Filter = new PinyinFilter();
|
||
```
|
||
|
||
---
|
||
|
||
## 6. 控制动画行为
|
||
|
||
```xml
|
||
<!-- 禁用过渡动画（弹出/关闭不再有动画效果） -->
|
||
<atom:AutoComplete IsMotionEnabled="False" PlaceholderText="No Animation" Width="200" />
|
||
```
|
||
|
||
---
|
||
|
||
## 样式选择器速查
|
||
|
||
> 说明：Avalonia 样式选择器中使用 `atom|AutoComplete` 语法引用 `atom` XML 命名空间下的 `AutoComplete` 类型，其中 `|` 是命名空间分隔符。
|
||
|
||
### 按控件类型选择
|
||
|
||
| 选择器 | 说明 |
|
||
|---|---|
|
||
| `atom\|AutoComplete` | 匹配标准自动补全（内嵌 LineEdit） |
|
||
| `atom\|AutoCompleteSearchEdit` | 匹配搜索型自动补全（内嵌 SearchEdit） |
|
||
| `atom\|AutoCompleteTextArea` | 匹配多行文本自动补全（内嵌 TextArea） |
|
||
| `atom\|AbstractAutoComplete` | 匹配所有 AutoComplete 变体的基类（使用 `:is` 选择器） |
|
||
|
||
### 按样式变体选择
|
||
|
||
| 选择器 | 说明 |
|
||
|---|---|
|
||
| `atom\|AutoComplete[StyleVariant=Outline]` | 匹配默认带边框样式 |
|
||
| `atom\|AutoComplete[StyleVariant=Filled]` | 匹配填充背景样式 |
|
||
| `atom\|AutoComplete[StyleVariant=Borderless]` | 匹配无边框样式 |
|
||
| `atom\|AutoComplete[StyleVariant=Underlined]` | 匹配下划线样式 |
|
||
|
||
### 按尺寸选择
|
||
|
||
| 选择器 | 说明 |
|
||
|---|---|
|
||
| `atom\|AutoComplete[SizeType=Large]` | 匹配大号自动补全 |
|
||
| `atom\|AutoComplete[SizeType=Middle]` | 匹配中号自动补全（默认） |
|
||
| `atom\|AutoComplete[SizeType=Small]` | 匹配小号自动补全 |
|
||
|
||
### 按验证状态选择
|
||
|
||
| 选择器 | 说明 |
|
||
|---|---|
|
||
| `atom\|AutoComplete[Status=Error]` | 匹配错误状态 |
|
||
| `atom\|AutoComplete[Status=Warning]` | 匹配警告状态 |
|
||
|
||
### 按伪类选择
|
||
|
||
| 选择器 | 说明 |
|
||
|---|---|
|
||
| `atom\|AutoComplete:candidateopen` | 匹配候选列表打开状态 |
|
||
| `atom\|AutoComplete:pointerover` | 匹配鼠标悬浮状态 |
|
||
| `atom\|AutoComplete:disabled` | 匹配禁用状态 |
|
||
| `atom\|AutoComplete:focus` | 匹配获得焦点状态 |
|
||
| `atom\|AutoComplete:focus-visible` | 匹配通过键盘获得焦点的状态 |
|
||
|
||
### 按属性选择
|
||
|
||
| 选择器 | 说明 |
|
||
|---|---|
|
||
| `atom\|AutoComplete[IsAllowClear=True]` | 匹配启用清除按钮的实例 |
|
||
| `atom\|AutoComplete[IsPopupMatchSelectWidth=True]` | 匹配弹出层等宽模式（默认） |
|
||
| `atom\|AutoComplete[IsPopupMatchSelectWidth=False]` | 匹配弹出层非等宽模式 |
|
||
|
||
### 组合选择器示例
|
||
|
||
| 选择器 | 说明 |
|
||
|---|---|
|
||
| `atom\|AutoComplete[Status=Error]:not(:disabled)` | 非禁用状态的错误态自动补全 |
|
||
| `atom\|AutoComplete[SizeType=Large]:candidateopen` | 大号且候选列表打开的自动补全 |
|
||
| `atom\|AutoComplete /template/ atom\|Popup#PART_Popup` | 访问模板内的弹出层部件 |
|
||
| `atom\|AutoComplete /template/ Border#PopupFrame` | 访问模板内的弹出层框架 Border |
|