mirror of
https://github.com/AtomUI/AtomUI.git
synced 2026-10-19 23:30:44 +08:00
chinboy
128 lines
5.4 KiB
Markdown
128 lines
5.4 KiB
Markdown
# AutoComplete Design Token
|
||
|
||
AutoComplete 控件使用 `AutoCompleteToken`（Token ID: `"AutoComplete"`）作为组件级 Design Token，所有视觉属性均从全局 `SharedToken` 派生，不硬编码任何具体值。
|
||
|
||
---
|
||
|
||
## Token 资源访问方式
|
||
|
||
在 AXAML 中使用组件级 Token：
|
||
|
||
```xml
|
||
{atom:AutoCompleteTokenResource OptionHeight}
|
||
{atom:AutoCompleteTokenResource PopupContentPadding}
|
||
{atom:AutoCompleteTokenResource MinPopupWidth}
|
||
{atom:AutoCompleteTokenResource MaxPopupWidth}
|
||
```
|
||
|
||
在 AXAML 中使用全局共享 Token：
|
||
|
||
```xml
|
||
{atom:SharedTokenResource ColorPrimary}
|
||
{atom:SharedTokenResource ControlHeight}
|
||
{atom:SharedTokenResource ColorBgElevated}
|
||
```
|
||
|
||
---
|
||
|
||
## 组件级 Token 一览
|
||
|
||
以下是 `AutoCompleteToken` 定义的全部组件级 Token。
|
||
|
||
### 弹出层 Token
|
||
|
||
| Token 名 | 类型 | 来源 | 说明 |
|
||
|---|---|---|---|
|
||
| `PopupContentPadding` | `Thickness` | `SharedToken.UniformlyPaddingXXS / 2` | 弹出层候选列表的内边距 |
|
||
| `OptionHeight` | `double` | `SharedToken.ControlHeight` | 每个候选选项的高度 |
|
||
| `MinPopupWidth` | `double` | 固定 `120` | 候选列表弹出层的最小宽度 |
|
||
| `MaxPopupWidth` | `double` | 固定 `200` | 在不跟随输入框宽度（`IsPopupMatchSelectWidth=False`）时的弹出层最大宽度 |
|
||
|
||
---
|
||
|
||
## 主题中使用的全局 SharedToken
|
||
|
||
AutoComplete 的 ControlTheme（`AbstractAutoCompleteTheme.axaml`）直接引用了以下全局 `SharedToken`：
|
||
|
||
| Token 资源键 | 使用场景 |
|
||
|---|---|
|
||
| `EnableMotion` | 全局动画开关，控制弹出/关闭动画是否启用 |
|
||
| `ColorTextPlaceholder` | 占位文本颜色 |
|
||
| `ColorBgElevated` | 弹出层背景色（浮层提升背景） |
|
||
|
||
### 弹出层样式 Token
|
||
|
||
弹出层框架引用了 `PopupHostToken` 中的全局 Token：
|
||
|
||
| Token 资源键 | 使用场景 |
|
||
|---|---|
|
||
| `PopupHostToken.MarginToAnchor` | 弹出层与锚点（输入框）之间的间距 |
|
||
| `PopupHostToken.BoxShadows` | 弹出层阴影效果 |
|
||
| `PopupHostToken.BorderRadius` | 弹出层圆角 |
|
||
|
||
### 内嵌输入框使用的 Token
|
||
|
||
AutoComplete 的输入框部分由内嵌的 `LineEdit`、`SearchEdit` 或 `TextArea` 控件渲染，这些控件各自拥有独立的 Token 系统。AutoComplete 通过 `TemplateBinding` 将以下属性透传给内嵌输入框：
|
||
|
||
| 透传属性 | 影响 |
|
||
|---|---|
|
||
| `SizeType` | 内嵌输入框的尺寸，决定高度、字号、圆角等 |
|
||
| `StyleVariant` | 内嵌输入框的样式变体（Outline / Filled / Borderless / Underlined） |
|
||
| `Status` | 验证状态视觉反馈（Error → 红色边框，Warning → 橙色边框） |
|
||
| `IsAllowClear` | 清除按钮显示 |
|
||
| `ClearIcon` | 自定义清除图标 |
|
||
| `PlaceholderText` | 占位文本 |
|
||
| `IsReadOnly` | 只读模式 |
|
||
| `IsMotionEnabled` | 动画开关 |
|
||
| `CaretIndex` | 光标位置双向绑定 |
|
||
|
||
因此，AutoComplete 的输入框外观实际由对应输入框控件的 Token（如 `LineEditToken`、`SearchEditToken`、`TextAreaToken`）控制，具体包括：
|
||
|
||
- **边框颜色**：正常态 / 悬浮态 / 焦点态 / 错误态 / 警告态
|
||
- **背景色**：各变体（Outline / Filled / Borderless / Underlined）的背景
|
||
- **字体大小**：根据 `SizeType` 由 `SharedToken.FontSize` / `FontSizeSM` / `FontSizeLG` 决定
|
||
- **圆角**：根据 `SizeType` 由 `SharedToken.BorderRadius` / `BorderRadiusSM` / `BorderRadiusLG` 决定
|
||
- **高度**：根据 `SizeType` 由 `SharedToken.ControlHeight` / `ControlHeightSM` / `ControlHeightLG` 决定
|
||
|
||
---
|
||
|
||
## Token 对外观的具体影响
|
||
|
||
### 弹出层外观
|
||
|
||
| 视觉特征 | Token 来源 | 说明 |
|
||
|---|---|---|
|
||
| 弹出层背景 | `SharedToken.ColorBgElevated` | 浮层使用提升背景色，通常比容器背景稍亮 |
|
||
| 弹出层圆角 | `PopupHostToken.BorderRadius` | 统一的弹出层圆角 |
|
||
| 弹出层阴影 | `PopupHostToken.BoxShadows` | 浮层投影效果 |
|
||
| 弹出层内边距 | `AutoCompleteToken.PopupContentPadding` | 候选列表与弹出层边框之间的间距 |
|
||
| 弹出层与输入框间距 | `PopupHostToken.MarginToAnchor` | 候选列表与输入框之间的垂直间距 |
|
||
| 弹出层最小宽度 | `AutoCompleteToken.MinPopupWidth` | 确保弹出层有最小可读宽度 |
|
||
| 弹出层最大宽度 | `AutoCompleteToken.MaxPopupWidth` | 非等宽模式下限制最大宽度 |
|
||
|
||
### 候选选项外观
|
||
|
||
| 视觉特征 | Token 来源 | 说明 |
|
||
|---|---|---|
|
||
| 选项高度 | `AutoCompleteToken.OptionHeight` = `SharedToken.ControlHeight` | 每个候选选项的行高 |
|
||
| 选项悬浮背景 | 由 `CandidateList` 控件的 Token 控制 | 鼠标悬浮时的高亮背景 |
|
||
| 选项选中背景 | 由 `CandidateList` 控件的 Token 控制 | 键盘选中时的高亮背景 |
|
||
|
||
### 尺寸与 Token 映射
|
||
|
||
候选列表的 `MaxPopupHeight` 由以下公式计算：
|
||
|
||
```
|
||
MaxPopupHeight = OptionHeight × DisplayCandidateCount + PopupContentPadding.Top + PopupContentPadding.Bottom
|
||
```
|
||
|
||
其中 `OptionHeight` 默认等于 `SharedToken.ControlHeight`，`DisplayCandidateCount` 默认为 `10`。
|
||
|
||
| 尺寸 | 输入框高度 | 选项高度 | 可见候选数 | 弹出层最大高度 |
|
||
|---|---|---|---|---|
|
||
| `Large` | `ControlHeightLG` | `ControlHeight` | 10（默认） | 约 `ControlHeight × 10 + padding` |
|
||
| `Middle` | `ControlHeight` | `ControlHeight` | 10（默认） | 约 `ControlHeight × 10 + padding` |
|
||
| `Small` | `ControlHeightSM` | `ControlHeight` | 10（默认） | 约 `ControlHeight × 10 + padding` |
|
||
|
||
> 注意：`SizeType` 仅影响内嵌输入框的尺寸，候选选项的高度始终为 `ControlHeight`，不随 `SizeType` 变化。
|