AtomUI/docs/Desktop.Controls/Tooltip/TooltipToken.md

Tooltip Design Token

ToolTip 控件使用 ToolTipToken（Token ID: "ToolTip"）作为组件级 Design Token，所有视觉属性均从全局 SharedToken 派生，不硬编码任何具体值。

---

Token 资源访问方式

在 AXAML 中使用组件级 Token：

{atom:ToolTipTokenResource ToolTipBackground}
{atom:ToolTipTokenResource ToolTipColor}
{atom:ToolTipTokenResource ToolTipMaxWidth}
{atom:ToolTipTokenResource ToolTipPadding}

在 AXAML 中使用全局共享 Token：

{atom:SharedTokenResource ColorBgSpotlight}
{atom:SharedTokenResource ColorTextLightSolid}
{atom:SharedTokenResource FontSize}
{atom:SharedTokenResource ControlHeight}
{atom:SharedTokenResource EnableMotion}

---

组件级 Token 一览

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

尺寸与布局 Token

Token 名	类型	来源	说明
ToolTipMaxWidth	double	固定值 250	ToolTip 的最大宽度（像素），超过此宽度文本自动换行
ToolTipPadding	Thickness	基于 SharedToken.UniformlyPaddingSM 计算	ToolTip 内容区域的内间距。水平 = UniformlyPaddingSM，垂直 = UniformlyPaddingSM / 2 + 2

颜色 Token

Token 名	类型	来源	说明
ToolTipColor	Color	SharedToken.ColorTextLightSolid	ToolTip 默认前景色（文字颜色），通常为白色
ToolTipBackground	Color	SharedToken.ColorBgSpotlight	ToolTip 默认背景色，通常为深灰/黑色半透明

圆角 Token

Token 名	类型	来源	说明
BorderRadiusOuter	CornerRadius	基于 SharedToken.BorderRadiusSM 计算，最小值 4	ToolTip 气泡框的外圆角。每个角的值取 max(原值, 4)，确保始终有足够的圆角

阴影 Token

Token 名	类型	来源	说明
ToolTipShadows	BoxShadows	SharedToken.BoxShadowsSecondary	ToolTip 气泡框的内置阴影效果，使用全局二级阴影

动画 Token

Token 名	类型	来源	说明
ToolTipMotionDuration	TimeSpan	SharedToken.MotionDurationMid	ToolTip 弹出/关闭动画的持续时间

---

主题中使用的全局 SharedToken

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

Token 资源键	使用位置	说明
FontSize	ArrowDecoratedBox 字体	ToolTip 内容文字的字号
ControlHeight	ArrowDecoratedBox 最小高度	ToolTip 气泡框的最小高度
EnableMotion	IsMotionEnabled 属性	全局动画开关，控制 ToolTip 是否使用弹出/关闭动画
MarginToAnchor	MarginToAnchor 属性	全局弹出层边距（从 PopupHostToken 获取）
ColorBgSpotlight	ToolTipBackground 来源	深色聚焦背景色，作为 ToolTip 默认背景
ColorTextLightSolid	ToolTipColor 来源	浅色实心文字色，作为 ToolTip 默认前景
UniformlyPaddingSM	ToolTipPadding 来源	统一小号内间距，作为 ToolTip 内间距的计算基准
BoxShadowsSecondary	ToolTipShadows 来源	二级阴影效果
MotionDurationMid	ToolTipMotionDuration 来源	中等动画时长

---

Token 对外观的具体影响

颜色映射

模式	背景色	文字色	箭头颜色
默认	ToolTipBackground（ColorBgSpotlight，深灰/黑色）	ToolTipColor（ColorTextLightSolid，白色）	与背景色一致
预设颜色（PresetColor）	对应调色板主色	ToolTipColor（白色）	与背景色一致
自定义颜色（Color）	用户指定色	ToolTipColor（白色）	与背景色一致

说明：背景色通过 TemplateBinding Background 传递给 ArrowDecoratedBox，箭头颜色自动跟随背景色变化。当设置 PresetColor 或 Color 时，ToolTip 会更新 Background 属性，覆盖默认的 ToolTipBackground Token 值。

尺寸映射

属性	Token 来源	默认值（近似）	说明
最大宽度	ToolTipMaxWidth	250px	超过此宽度文本自动换行
最小高度	SharedToken.ControlHeight	32px	确保 ToolTip 不会太扁
内间距	ToolTipPadding	约 8px 6px	内容与气泡框边缘的间距
圆角	BorderRadiusOuter	至少 4px	气泡框的圆角半径

阴影映射

属性	Token 来源	说明
阴影	ToolTipShadows	使用 BoxShadowsSecondary，提供轻微的阴影效果使 ToolTip 与背景分离

动画映射

属性	Token 来源	说明
弹出动画时长	ToolTipMotionDuration	使用 MotionDurationMid（约 200ms），控制淡入淡出速度
动画开关	SharedToken.EnableMotion	全局控制是否使用动画。设为 false 时 ToolTip 立即显示/隐藏

---

深色模式行为

ToolTipToken.CalculateTokenValues(bool isDarkMode) 在深色模式和浅色模式下的行为：

Token	浅色模式	深色模式
ToolTipBackground	ColorBgSpotlight（深色背景）	ColorBgSpotlight（深色背景）
ToolTipColor	ColorTextLightSolid（白色文字）	ColorTextLightSolid（白色文字）
ToolTipShadows	BoxShadowsSecondary	BoxShadowsSecondary

注意：ToolTip 在浅色和深色模式下的默认外观非常相似（都是深色背景 + 白色文字），这是因为 Ant Design 的设计规范就是如此——ToolTip 始终使用高对比度的深色气泡，以确保在任何主题下都具有良好的可读性。

---

Token 注册

ToolTip 控件在构造函数中注册 Token 作用域：

public ToolTip()
{
    this.RegisterTokenResourceScope(ToolTipToken.ScopeProvider);
}

ToolTipToken 的 Token 类定义：

[ControlDesignToken]
internal class ToolTipToken : AbstractControlDesignToken
{
    public const string ID = "ToolTip";
    public static readonly ControlTokenResourceScopeProvider ScopeProvider = new(ID);

    // Token 属性...

    protected override Type GetTokenKindType() => typeof(ToolTipTokenKind);
}