mirror of
https://github.com/AtomUI/AtomUI.git
synced 2026-10-23 17:59:22 +08:00
chinboy
127 lines
4.7 KiB
Markdown
127 lines
4.7 KiB
Markdown
# ListView Design Token
|
||
|
||
ListView 控件使用 `ListViewToken`（Token ID: `"ListView"`）作为组件级 Design Token，所有视觉属性均从全局 `SharedToken` 派生，不硬编码任何具体值。
|
||
|
||
---
|
||
|
||
## Token 资源访问方式
|
||
|
||
在 AXAML 中使用组件级 Token：
|
||
|
||
```xml
|
||
{atom:ListViewTokenResource ContentPadding}
|
||
{atom:ListViewTokenResource ItemColor}
|
||
{atom:ListViewTokenResource ItemPadding}
|
||
```
|
||
|
||
在 AXAML 中使用全局共享 Token：
|
||
|
||
```xml
|
||
{atom:SharedTokenResource ColorPrimary}
|
||
{atom:SharedTokenResource ControlHeight}
|
||
{atom:SharedTokenResource BorderThickness}
|
||
```
|
||
|
||
---
|
||
|
||
## 组件级 Token 一览
|
||
|
||
以下是 `ListViewToken` 定义的全部组件级 Token，按功能分组说明。
|
||
|
||
### 颜色 Token
|
||
|
||
| Token 名 | 类型 | 来源 | 说明 |
|
||
|---|---|---|---|
|
||
| `ItemColor` | `Color` | `SharedToken.ColorTextSecondary` | 列表项文字颜色 |
|
||
| `ItemHoverColor` | `Color` | `SharedToken.ColorTextSecondary` | 列表项文字悬浮颜色 |
|
||
| `ItemSelectedColor` | `Color` | `SharedToken.ColorText` | 列表项文字选中颜色 |
|
||
| `ItemDisabledColor` | `Color` | `SharedToken.ColorTextDisabled` | 列表项文字禁用颜色 |
|
||
| `GroupHeaderColor` | `Color` | `SharedToken.ColorTextDescription` | 分组标题颜色 |
|
||
|
||
### 背景色 Token
|
||
|
||
| Token 名 | 类型 | 来源 | 说明 |
|
||
|---|---|---|---|
|
||
| `ItemBgColor` | `Color` | `SharedToken.ColorTransparent` | 列表项背景色（默认透明） |
|
||
| `ItemHoverBgColor` | `Color` | `SharedToken.ColorBgTextHover` | 列表项悬浮态背景色 |
|
||
| `ItemSelectedBgColor` | `Color` | `SharedToken.ControlItemBgActive` | 列表项选中态背景色 |
|
||
|
||
### 内间距 Token
|
||
|
||
| Token 名 | 类型 | 来源 | 说明 |
|
||
|---|---|---|---|
|
||
| `ContentPadding` | `Thickness` | `SharedToken.UniformlyPaddingXXS / 2` | ListView 容器内边距 |
|
||
| `ItemPaddingSM` | `Thickness` | `SharedToken.UniformlyPaddingXS, 0` | 小号列表项内间距 |
|
||
| `ItemPadding` | `Thickness` | `SharedToken.UniformlyPaddingSM, 0` | 中号列表项内间距 |
|
||
| `ItemPaddingLG` | `Thickness` | `SharedToken.UniformlyPadding, 0` | 大号列表项内间距 |
|
||
|
||
### 间距 Token
|
||
|
||
| Token 名 | 类型 | 来源 | 说明 |
|
||
|---|---|---|---|
|
||
| `ItemMargin` | `Thickness` | `0, 0.5` | 列表项之间的外边距 |
|
||
| `PaginationMargin` | `Thickness` | `0, SharedToken.UniformlyMarginXS` | 分页器的外边距 |
|
||
| `SelectedIndicatorMargin` | `Thickness` | `SharedToken.UniformlyMarginXXS, 0, 0, 0` | 选中指示器的外边距 |
|
||
|
||
---
|
||
|
||
## 主题中使用的全局 SharedToken
|
||
|
||
除组件级 Token 外，ListView 的 ControlTheme 还直接引用了以下全局 `SharedToken`：
|
||
|
||
### ListView 主题引用
|
||
|
||
| Token 资源键 | 使用场景 |
|
||
|---|---|
|
||
| `ColorBorder` | ListView 默认边框颜色 |
|
||
| `BorderThickness` | ListView 默认边框粗细 |
|
||
| `EnableMotion` | 全局动画开关 |
|
||
| `BorderRadiusLG` | 大号 ListView 圆角半径 |
|
||
| `BorderRadius` | 中号 ListView 圆角半径 |
|
||
| `BorderRadiusSM` | 小号 ListView 圆角半径 |
|
||
| `PaddingXL` | 大号空状态指示器内边距 |
|
||
| `Padding` | 中号/小号空状态指示器内边距 |
|
||
|
||
### ListViewItem 主题引用
|
||
|
||
| Token 资源键 | 使用场景 |
|
||
|---|---|
|
||
| `ColorPrimary` | 选中指示器图标颜色 |
|
||
| `IconSize` | 选中指示器图标尺寸 |
|
||
| `ColorTextDisabled` | 禁用态文本颜色 |
|
||
| `BorderRadius` / `BorderRadiusSM` / `BorderRadiusXS` | 列表项圆角（大/中/小） |
|
||
| `ControlHeightLG` / `ControlHeight` / `ControlHeightSM` | 列表项最小高度（大/中/小） |
|
||
| `FontSize` / `FontSizeSM` | 分组标题字号（大号 / 中小号） |
|
||
|
||
---
|
||
|
||
## Token 对外观的具体影响
|
||
|
||
### 列表项状态与 Token 映射
|
||
|
||
| 状态 | 文字颜色 | 背景色 |
|
||
|---|---|---|
|
||
| **正常** | `ItemColor` | `ItemBgColor`（透明） |
|
||
| **悬浮** | `ItemHoverColor` | `ItemHoverBgColor`（或 `ItemHoverBg` 属性覆盖） |
|
||
| **选中** | `ItemSelectedColor` | `ItemSelectedBgColor`（或 `ItemSelectedBg` 属性覆盖） |
|
||
| **禁用** | `ColorTextDisabled` | — |
|
||
| **分组标题** | `GroupHeaderColor` | `ItemBgColor`（透明） |
|
||
|
||
> **注意**：悬浮和选中背景色有两层机制——默认由 Token 控制，但可通过 `ItemHoverBg` / `ItemSelectedBg` 属性在实例级别覆盖。属性值优先级高于 Token。
|
||
|
||
### 尺寸与 Token 映射
|
||
|
||
| 尺寸 | 最小高度 | 内间距 | 圆角 |
|
||
|---|---|---|---|
|
||
| `Large` | `ControlHeightLG` | `ItemPaddingLG` | `BorderRadius` |
|
||
| `Middle` | `ControlHeight` | `ItemPadding` | `BorderRadiusSM` |
|
||
| `Small` | `ControlHeightSM` | `ItemPaddingSM` | `BorderRadiusXS` |
|
||
|
||
### ListView 容器尺寸映射
|
||
|
||
| 尺寸 | 圆角 | 空状态内边距 |
|
||
|---|---|---|
|
||
| `Large` | `BorderRadiusLG` | `PaddingXL` |
|
||
| `Middle` | `BorderRadius` | `Padding` |
|
||
| `Small` | `BorderRadiusSM` | `Padding` |
|