AtomUI/docs/Desktop.Controls/Skeleton/SkeletonToken.md

Skeleton Design Token

Skeleton 控件族使用 SkeletonToken（Token ID: "Skeleton"）作为组件级 Design Token，所有视觉属性均从全局 SharedToken 派生，不硬编码任何具体值。所有 Skeleton 系列控件共享同一套 Token。

---

Token 资源访问方式

在 AXAML 中使用组件级 Token：

{atom:SkeletonTokenResource GradientFromColor}
{atom:SkeletonTokenResource TitleHeight}
{atom:SkeletonTokenResource BlockRadius}
{atom:SkeletonTokenResource ParagraphLineHeight}
{atom:SkeletonTokenResource ImageContainerSize}

在 AXAML 中使用全局共享 Token：

{atom:SharedTokenResource ControlHeight}
{atom:SharedTokenResource ControlHeightLG}
{atom:SharedTokenResource ControlHeightSM}
{atom:SharedTokenResource BorderRadius}
{atom:SharedTokenResource BorderRadiusSM}
{atom:SharedTokenResource BorderRadiusLG}

---

组件级 Token 一览

以下是 SkeletonToken 定义的全部组件级 Token，按功能分组说明。

颜色 Token

Token 名	类型	来源	说明
GradientFromColor	Color	SharedToken.ColorFillContent	骨架块的基底颜色（静态状态和渐变起点色）
GradientToColor	Color	SharedToken.ColorFill	渐变终点颜色（用于构建流光动画的渐变画刷）

流光动画 Token

Token 名	类型	来源	说明
LoadingBackgroundStart	IBrush	基于 GradientFromColor + GradientToColor 构建	流光动画起始帧画刷（LinearGradientBrush，起始位置为左）
LoadingBackgroundMiddle	IBrush	基于 GradientFromColor + GradientToColor 构建	流光动画中间帧画刷（渐变已扫过一半）
LoadingBackgroundEnd	IBrush	基于 GradientFromColor 构建	流光动画结束帧画刷（回到纯色状态）
LoadingMotionDuration	TimeSpan	固定 1.4s	流光动画一次循环的时长

尺寸 Token

Token 名	类型	来源	说明
TitleHeight	double	SharedToken.ControlHeight / 2	标题骨架行高度
ParagraphLineHeight	double	SharedToken.ControlHeight / 2	段落骨架单行高度
BlockRadius	CornerRadius	SharedToken.BorderRadiusSM	骨架块默认圆角（IsRound=False 时使用）
ParagraphLineRoundCornerRadius	CornerRadius	ParagraphLineHeight / 2	段落行胶囊形圆角（IsRound=True 时使用）

间距 Token

Token 名	类型	来源	说明
ParagraphMarginTop	Thickness	new Thickness(0, SharedToken.UniformlyMarginLG + SharedToken.UniformlyMarginXXS, 0, 0)	段落区域顶部间距（标题与段落之间的间隔）
AvatarMarginRight	Thickness	new Thickness(0, 0, SharedToken.UniformlyMargin, 0)	头像区域右侧间距（头像与内容区域之间的间隔）

图片骨架 Token

Token 名	类型	来源	说明
ImageSize	double	SharedToken.ControlHeight × 1.5	图片骨架内嵌图标的尺寸
ImageContainerSize	double	SharedToken.ControlHeight × 1.5 × 2	图片骨架容器的默认宽高
ImageContainerMaxSize	double	SharedToken.ControlHeight × 1.5 × 4	图片骨架容器的最大宽高

---

主题中使用的全局 SharedToken

除组件级 Token 外，Skeleton 的各 ControlTheme 还直接引用了以下全局 SharedToken：

Token 资源键	使用场景	说明
ControlHeight	中号高度	SkeletonElement（Middle）、SkeletonAvatar（Middle）的高度
ControlHeightLG	大号高度	SkeletonElement（Large）、SkeletonAvatar（Large）的高度
ControlHeightSM	小号高度	SkeletonElement（Small）、SkeletonAvatar（Small）的高度
ControlHeightXS	段落行间距	SkeletonParagraph 内部 StackPanel 的 Spacing
BorderRadius	中号圆角	SkeletonAvatar（Square + Middle）的圆角
BorderRadiusSM	小号圆角	SkeletonElement 默认圆角、SkeletonButton（Square）圆角、SkeletonImage 圆角
BorderRadiusLG	大号圆角	SkeletonAvatar（Square + Large）的圆角

---

Token 对外观的具体影响

颜色与动画

状态	视觉效果	相关 Token
静态（IsActive=False）	纯色灰色块	GradientFromColor → Background
流光动画（IsActive=True）	从左到右的渐变流光，三帧循环	LoadingBackgroundStart → LoadingBackgroundMiddle → LoadingBackgroundEnd，时长 LoadingMotionDuration

流光动画通过 Avalonia Animation + KeyFrame 实现，动画驱动 AnimationLayerFill 属性在三个 LinearGradientBrush 之间过渡：

帧 0（0%）: LoadingBackgroundStart  ── 渐变在最左侧
帧 1（80%）: LoadingBackgroundMiddle ── 渐变扫过右侧
帧 2（100%）: LoadingBackgroundEnd   ── 回到纯色

SizeType 与高度 Token 映射

SizeType	SkeletonElement/SkeletonButton/SkeletonInput 高度	SkeletonAvatar 宽高
Large	ControlHeightLG	ControlHeightLG
Middle	ControlHeight	ControlHeight
Small	ControlHeightSM	ControlHeightSM

IsRound 与圆角 Token 映射

IsRound	段落行圆角
false（默认）	BlockRadius（BorderRadiusSM）
true	ParagraphLineRoundCornerRadius（ParagraphLineHeight / 2，形成胶囊形）

组合骨架屏内间距

区域	相关 Token	效果
头像 → 内容	AvatarMarginRight	头像右侧留白
标题 → 段落	ParagraphMarginTop	段落区域顶部留白（仅 IsShowTitle=True 时生效）
段落行间	ControlHeightXS（共享 Token）	段落内行与行之间的间距

---

Token 值参考（默认主题）

以下是默认（Light）主题下各 Token 的典型计算值，实际值取决于全局 SharedToken 配置：

Token	默认值（约）	计算逻辑
GradientFromColor	rgba(0,0,0,0.06)	SharedToken.ColorFillContent
GradientToColor	rgba(0,0,0,0.15)	SharedToken.ColorFill
TitleHeight	16 px	ControlHeight / 2
ParagraphLineHeight	16 px	ControlHeight / 2
BlockRadius	4 px	SharedToken.BorderRadiusSM
ParagraphLineRoundCornerRadius	8 px	ParagraphLineHeight / 2
ParagraphMarginTop	0,28,0,0	UniformlyMarginLG + UniformlyMarginXXS
AvatarMarginRight	0,0,16,0	UniformlyMargin
LoadingMotionDuration	1.4s	固定值
ImageSize	48 px	ControlHeight × 1.5
ImageContainerSize	96 px	ImageSize × 2
ImageContainerMaxSize	192 px	ImageSize × 4
ControlHeight（共享）	32 px	全局控件高度
ControlHeightLG（共享）	40 px	全局大号控件高度
ControlHeightSM（共享）	24 px	全局小号控件高度
ControlHeightXS（共享）	16 px	全局超小号控件高度