mirror of
https://github.com/AtomUI/AtomUI.git
synced 2026-10-29 07:16:33 +08:00
127 lines
5.3 KiB
Markdown
127 lines
5.3 KiB
Markdown
# TimePicker Design Token
|
||
|
||
TimePicker 控件使用 `TimePickerToken`（Token ID: `"TimePicker"`）作为组件级 Design Token，所有视觉属性均从全局 `SharedToken` 派生，不硬编码任何具体值。
|
||
|
||
---
|
||
|
||
## Token 资源访问方式
|
||
|
||
在 AXAML 中使用组件级 Token：
|
||
|
||
```xml
|
||
{atom:TimePickerTokenResource ItemHeight}
|
||
{atom:TimePickerTokenResource ItemWidth}
|
||
{atom:TimePickerTokenResource ItemPadding}
|
||
```
|
||
|
||
在 AXAML 中使用全局共享 Token：
|
||
|
||
```xml
|
||
{atom:SharedTokenResource ColorPrimary}
|
||
{atom:SharedTokenResource ControlHeight}
|
||
{atom:SharedTokenResource BorderThickness}
|
||
```
|
||
|
||
---
|
||
|
||
## 组件级 Token 一览
|
||
|
||
以下是 `TimePickerToken` 定义的全部组件级 Token，按功能分组说明。
|
||
|
||
### 面板项尺寸 Token
|
||
|
||
| Token 名 | 类型 | 来源 | 说明 |
|
||
|---|---|---|---|
|
||
| `ItemHeight` | `double` | `SharedToken.ControlHeight - 4` | 时间选择项的高度 |
|
||
| `ItemWidth` | `double` | 固定 `40` | 时间选择项的宽度（时/分/秒列） |
|
||
| `PeriodHostWidth` | `double` | 固定 `50` | AM/PM 选择列的宽度（12小时制时可见） |
|
||
|
||
### 间距 Token
|
||
|
||
| Token 名 | 类型 | 来源 | 说明 |
|
||
|---|---|---|---|
|
||
| `ItemPadding` | `Thickness` | `(0, SharedToken.UniformlyPaddingXXS)` | 时间选择项的内间距（上下） |
|
||
| `ButtonsMargin` | `Thickness` | `(0, SharedToken.UniformlyMarginXS, 0, 0)` | 按钮区域对上的外边距 |
|
||
| `HeaderMargin` | `Thickness` | `(0, 0, 0, 3)` | 头部文本区域的外边距 |
|
||
|
||
### 范围选择器 Token
|
||
|
||
| Token 名 | 类型 | 来源 | 说明 |
|
||
|---|---|---|---|
|
||
| `RangePickerArrowMargin` | `Thickness` | `(SharedToken.UniformlyMarginXS, 0)` | 范围选择箭头（→）的左右外间距 |
|
||
| `RangePickerIndicatorThickness` | `double` | `SharedToken.LineWidthFocus` | 范围选中指示器（下划线）的厚度 |
|
||
|
||
---
|
||
|
||
## 主题中使用的全局 SharedToken
|
||
|
||
除组件级 Token 外，TimePicker 的 ControlTheme 还直接引用了以下全局 `SharedToken`：
|
||
|
||
| Token 资源键 | 使用场景 |
|
||
|---|---|
|
||
| `BorderThickness` | 面板边框厚度 |
|
||
| `ColorBorderSecondary` | 面板内按钮区域上方的分隔线颜色 |
|
||
| `ControlHeight` / `ControlHeightSM` / `ControlHeightLG` | 控件高度（中/小/大） |
|
||
| `BorderRadius` / `BorderRadiusSM` / `BorderRadiusLG` | 圆角半径（中/小/大） |
|
||
| `ColorPrimary` / `ColorPrimaryHover` / `ColorPrimaryActive` | 主色调及其交互态（焦点边框、选中高亮） |
|
||
| `ColorError` / `ColorWarning` | 错误/警告色（Status 状态反馈） |
|
||
| `ColorText` / `ColorTextSecondary` / `ColorTextDisabled` | 文本色系 |
|
||
| `ColorBgContainer` / `ColorBgContainerDisabled` | 容器背景色 |
|
||
| `ColorBorder` | 边框颜色 |
|
||
| `ColorFocusBorder` | 焦点边框颜色 |
|
||
| `LineWidth` | 分隔线宽度 |
|
||
| `LineWidthFocus` | 焦点指示器宽度 |
|
||
| `UniformlyPaddingXXS` | 极小统一间距 |
|
||
| `UniformlyMarginXS` | 小号统一外边距 |
|
||
| `EnableMotion` | 全局动画开关 |
|
||
| `FontSize` | 字体大小 |
|
||
|
||
---
|
||
|
||
## Token 对外观的具体影响
|
||
|
||
### 面板尺寸
|
||
|
||
`ItemHeight` 和 `ItemWidth` 共同决定了弹出面板中每个时间单元格的大小。面板总高度由 `ItemHeight × SelectorRowCount`（默认 7 行）计算得出。`PeriodHostWidth` 仅在 12 小时制（`ClockIdentifier == HourClock12`）时影响 AM/PM 列的宽度。
|
||
|
||
### 按钮区域
|
||
|
||
`ButtonsMargin` 控制面板底部按钮区域与上方时间滚轮之间的间距。按钮区域的可见性由 `IsNeedConfirm` 和 `IsShowNow` 属性共同决定：
|
||
|
||
| IsNeedConfirm | IsShowNow | 按钮区域可见性 | 显示的按钮 |
|
||
|---|---|---|---|
|
||
| `false` | `true` | ✅ 可见 | 仅"此刻"按钮（居中） |
|
||
| `false` | `false` | ❌ 隐藏 | 无 |
|
||
| `true` | `true` | ✅ 可见 | "此刻"按钮（左对齐）+ "确定"按钮（右对齐） |
|
||
| `true` | `false` | ✅ 可见 | 仅"确定"按钮 |
|
||
|
||
### 范围选择器
|
||
|
||
`RangePickerArrowMargin` 控制起始/结束输入框之间箭头图标的左右间距。`RangePickerIndicatorThickness` 控制激活输入框下方彩色指示线的粗细。
|
||
|
||
### 样式变体与 Token 映射
|
||
|
||
| 样式变体 | 正常态 | 悬浮态 | 焦点态 | 禁用态 |
|
||
|---|---|---|---|---|
|
||
| **Outline** | `ColorBorder` 边框 + `ColorBgContainer` 背景 | `ColorPrimaryHover` 边框 | `ColorPrimary` 边框 | `ColorBgContainerDisabled` 背景 |
|
||
| **Filled** | 无边框 + `ColorFillTertiary` 背景 | `ColorFillSecondary` 背景 | `ColorPrimary` 边框 | `ColorBgContainerDisabled` 背景 |
|
||
| **Borderless** | 无边框 + 透明背景 | 轻微背景色变化 | `ColorPrimary` 底部边框 | `ColorTextDisabled` 文本 |
|
||
|
||
### 验证状态与 Token 映射
|
||
|
||
| 验证状态 | 边框颜色 | 焦点边框 | 图标颜色 |
|
||
|---|---|---|---|
|
||
| `Default` | `ColorBorder` | `ColorPrimary` | `ColorTextSecondary` |
|
||
| `Warning` | `ColorWarning` | `ColorWarning` | `ColorWarning` |
|
||
| `Error` | `ColorError` | `ColorError` | `ColorError` |
|
||
|
||
### 尺寸与 Token 映射
|
||
|
||
| 尺寸 | 高度 | 字号 | 圆角 |
|
||
|---|---|---|---|
|
||
| `Large` | `ControlHeightLG` | `FontSizeLG` | `BorderRadiusLG` |
|
||
| `Middle` | `ControlHeight` | `FontSize` | `BorderRadius` |
|
||
| `Small` | `ControlHeightSM` | `FontSize` | `BorderRadiusSM` |
|
||
|
||
> 注意：TimePicker 的输入框主题继承自 `InfoPickerInputTheme`，因此输入框相关的 Token（背景色、边框色、文本色等）由 `InfoPickerInputToken` 提供。`TimePickerToken` 仅定义弹出面板内部的额外 Token。
|