AtomUI/docs/Desktop.Controls/Menu/MenuToken.md at d29cfa2154dbf5a0934bb93accff235becae1fc8

GithubStar/AtomUI

Fork 0

mirror of https://github.com/AtomUI/AtomUI.git synced 2026-10-19 23:30:44 +08:00

Files

T

chinboy 3ae85f5633 docs(Menu): add comprehensive design, API, styling, token and usage documentation

2026-04-13 15:24:35 +08:00

9.8 KiB

Raw Blame History

Menu 使用 MenuToken（Token ID: "Menu"）作为组件级 Design Token。所有视觉属性均从全局 SharedToken 派生，不使用硬编码值。

📖 Token 源码位置：src/AtomUI.Desktop.Controls/Menu/MenuToken.cs

Token 资源访问方式

AXAML 中访问

<!-- 组件级 Token（Menu 专属） -->
{atom:MenuTokenResource ItemColor}
{atom:MenuTokenResource ItemHoverBg}
{atom:MenuTokenResource MenuPopupBgColor}

<!-- 全局共享 Token -->
{atom:SharedTokenResource ColorPrimary}
{atom:SharedTokenResource ColorBgElevated}

Token 类定义

[ControlDesignToken]
internal class MenuToken : AbstractControlDesignToken
{
    public const string ID = "Menu";
    public static readonly ControlTokenResourceScopeProvider ScopeProvider = new(ID);
    // ...
}

完整 Token 属性列表

弹窗相关

Token 属性	类型	派生自 SharedToken	说明
`MenuPopupContentPadding`	`Thickness`	`UniformlyPaddingXXS`, `BorderRadiusLG`	菜单弹窗内容内间距
`MenuPopupMinWidth`	`double`	固定值 `120`	菜单弹窗最小宽度
`MenuPopupMaxWidth`	`double`	固定值 `800`	菜单弹窗最大宽度
`MenuPopupBgColor`	`Color`	`ColorBgElevated`	菜单弹窗背景色

菜单项基础

Token 属性	类型	派生自 SharedToken	说明
`ItemColor`	`Color`	`ColorText`	菜单项文字颜色
`ItemHoverColor`	`Color`	同 `ItemColor`	菜单项悬浮文字颜色
`ItemDisabledColor`	`Color`	`ColorTextDisabled`	菜单项禁用文字颜色
`ItemBg`	`Color`	`ColorBgElevated`	菜单项背景色
`ItemHoverBg`	`Color`	`ColorBgTextHover`	菜单项悬浮背景色
`ItemHeight`	`double`	`ControlHeight`	菜单项高度
`ItemBorderRadius`	`CornerRadius`	`BorderRadius`	菜单项圆角
`ItemPaddingInline`	`Thickness`	`UniformlyPadding`, `UniformlyPaddingXXS`	菜单项横向内间距
`ItemMargin`	`Thickness`	`UniformlyMarginXXS`	菜单项间距（右边距）

图标

Token 属性	类型	派生自 SharedToken	说明
`ItemIconSize`	`double`	`IconSize`	图标尺寸
`ItemIconMarginInlineEnd`	`double`	`ControlHeight - FontSize`	图标与文字间距

快捷键

Token 属性	类型	派生自 SharedToken	说明
`KeyGestureColor`	`Color`	`ColorTextQuaternary`	快捷键提示文字颜色

危险菜单项

Token 属性	类型	派生自 SharedToken	说明
`DangerItemColor`	`Color`	`ColorError`	危险菜单项文字颜色
`DangerItemHoverColor`	`Color`	`ColorError`	危险菜单项悬浮文字颜色

顶层菜单项（TopLevel）

Token 属性	类型	派生自 SharedToken	说明
`TopLevelItemColor`	`Color`	`ColorText`	顶层菜单项文字颜色
`TopLevelItemSelectedColor`	`Color`	`ColorTextSecondary`	顶层菜单项选中文字颜色
`TopLevelItemHoverColor`	`Color`	`ColorTextSecondary`	顶层菜单项悬浮文字颜色
`TopLevelItemBg`	`Color`	`ColorBgContainer`	顶层菜单项背景色
`TopLevelItemSelectedBg`	`Color`	`ColorBgTextHover`	顶层菜单项选中背景色
`TopLevelItemHoverBg`	`Color`	`ColorBgTextHover`	顶层菜单项悬浮背景色

顶层菜单项 — 圆角（按尺寸）

Token 属性	类型	派生自 SharedToken	说明
`TopLevelItemBorderRadiusSM`	`CornerRadius`	`BorderRadiusSM`	小号圆角
`TopLevelItemBorderRadius`	`CornerRadius`	`BorderRadius`	中号圆角
`TopLevelItemBorderRadiusLG`	`CornerRadius`	`BorderRadiusLG`	大号圆角

顶层菜单项 — 内间距（按尺寸）

Token 属性	类型	派生自 SharedToken	说明
`TopLevelItemPaddingSM`	`Thickness`	`PaddingContentHorizontalXS × 0.7`, `ControlHeightSM`	小号内间距
`TopLevelItemPadding`	`Thickness`	`PaddingContentHorizontalXS`, `ControlHeight`	中号内间距
`TopLevelItemPaddingLG`	`Thickness`	`PaddingContentHorizontalSM`, `ControlHeightLG`	大号内间距

顶层菜单项 — 字体（按尺寸）

Token 属性	类型	默认值	说明
`TopLevelItemFontSizeSM`	`double`	`SharedToken.FontSize`	小号字体大小
`TopLevelItemFontSize`	`double`	`SharedToken.FontSize`	中号字体大小
`TopLevelItemFontSizeLG`	`double`	`SharedToken.FontSizeLG`	大号字体大小
`TopLevelItemLineHeightSM`	`double`	自动计算	小号行高
`TopLevelItemLineHeight`	`double`	自动计算	中号行高
`TopLevelItemLineHeightLG`	`double`	自动计算	大号行高

行高计算公式：CalculatorUtils.CalculateLineHeight(fontSize) × fontSize

顶层弹出菜单

Token 属性	类型	派生自 SharedToken	说明
`TopLevelItemPopupMarginToAnchor`	`double`	`UniformlyMarginXXS`	顶层弹出菜单距离锚点的间距

分隔线

Token 属性	类型	派生自 SharedToken	说明
`SeparatorItemHeight`	`double`	`LineWidth × 5`	分隔线总高度（含上下间距）

上下文菜单偏移

Token 属性	类型	派生自 SharedToken	说明
`ContextMenuOffsetX`	`double`	`SpacingXXS`	上下文菜单水平偏移
`ContextMenuOffsetY`	`double`	`SpacingXXS`	上下文菜单垂直偏移

其他

Token 属性	类型	说明
`MenuTearOffHeight`	`double`	分离菜单项高度（`ItemHeight × 1.2`，暂未使用）

Token 在主题中的使用示例

MenuItemTheme.axaml 中的 Token 引用

<!-- 菜单项基础样式 -->
<Setter Property="Foreground" Value="{atom:MenuTokenResource ItemColor}" />
<Setter Property="Padding" Value="{atom:MenuTokenResource ItemPaddingInline}" />
<Setter Property="Background" Value="{atom:MenuTokenResource ItemBg}" />
<Setter Property="CornerRadius" Value="{atom:MenuTokenResource ItemBorderRadius}" />
<Setter Property="Height" Value="{atom:MenuTokenResource ItemHeight}" />

<!-- 悬浮状态 -->
<Style Selector="^:pointerover">
    <Setter Property="Foreground" Value="{atom:MenuTokenResource ItemHoverColor}" />
    <Setter Property="Background" Value="{atom:MenuTokenResource ItemHoverBg}" />
</Style>

<!-- 禁用状态 -->
<Style Selector="^:disabled">
    <Setter Property="Foreground" Value="{atom:MenuTokenResource ItemDisabledColor}" />
</Style>

<!-- 图标 -->
<Style Selector="^ /template/ atom|IconPresenter#ItemIconPresenter">
    <Setter Property="Width" Value="{atom:MenuTokenResource ItemIconSize}" />
    <Setter Property="Height" Value="{atom:MenuTokenResource ItemIconSize}" />
    <Setter Property="IconBrush" Value="{atom:MenuTokenResource ItemColor}" />
</Style>

<!-- 快捷键文字 -->
<Style Selector="^ /template/ atom|TextBlock#InputGestureText">
    <Setter Property="Foreground" Value="{atom:MenuTokenResource KeyGestureColor}" />
</Style>

TopLevelMenuItemTheme.axaml 中的 Token 引用

<!-- 悬浮状态 -->
<Style Selector="^:pointerover">
    <Setter Property="Background" Value="{atom:MenuTokenResource TopLevelItemHoverBg}" />
    <Setter Property="Foreground" Value="{atom:MenuTokenResource TopLevelItemHoverColor}" />
</Style>

<!-- 尺寸变体 -->
<Style Selector="^[SizeType=Large]">
    <Setter Property="CornerRadius" Value="{atom:MenuTokenResource TopLevelItemBorderRadiusLG}" />
    <Setter Property="Padding" Value="{atom:MenuTokenResource TopLevelItemPaddingLG}" />
    <Setter Property="FontSize" Value="{atom:MenuTokenResource TopLevelItemFontSizeLG}" />
</Style>

ContextMenuTheme.axaml 中的 Token 引用

<Setter Property="HorizontalOffset" Value="{atom:MenuTokenResource ContextMenuOffsetX}" />
<Setter Property="VerticalOffset" Value="{atom:MenuTokenResource ContextMenuOffsetY}" />
<Setter Property="Padding" Value="{atom:MenuTokenResource MenuPopupContentPadding}" />
<Setter Property="Background" Value="{atom:MenuTokenResource MenuPopupBgColor}" />
<Setter Property="MinWidth" Value="{atom:MenuTokenResource MenuPopupMinWidth}" />
<Setter Property="MaxWidth" Value="{atom:MenuTokenResource MenuPopupMaxWidth}" />
<Setter Property="ItemHeight" Value="{atom:MenuTokenResource ItemHeight}" />

Token 派生链总结

SharedToken (DesignToken)
├── ColorText           → ItemColor, TopLevelItemColor
├── ColorTextSecondary  → TopLevelItemSelectedColor, TopLevelItemHoverColor
├── ColorTextQuaternary → KeyGestureColor
├── ColorTextDisabled   → ItemDisabledColor
├── ColorError          → DangerItemColor, DangerItemHoverColor
├── ColorBgElevated     → ItemBg, MenuPopupBgColor
├── ColorBgTextHover    → ItemHoverBg, TopLevelItemHoverBg, TopLevelItemSelectedBg
├── ColorBgContainer    → TopLevelItemBg
├── ControlHeight       → ItemHeight
├── BorderRadius        → ItemBorderRadius, TopLevelItemBorderRadius
├── BorderRadiusSM      → TopLevelItemBorderRadiusSM
├── BorderRadiusLG      → TopLevelItemBorderRadiusLG
├── IconSize            → ItemIconSize
├── FontSize            → TopLevelItemFontSize, TopLevelItemFontSizeSM
├── FontSizeLG          → TopLevelItemFontSizeLG
├── LineWidth           → SeparatorItemHeight (× 5)
├── UniformlyPadding    → ItemPaddingInline (水平)
├── UniformlyPaddingXXS → ItemPaddingInline (垂直), MenuPopupContentPadding
├── UniformlyMarginXXS  → ItemMargin, TopLevelItemPopupMarginToAnchor
├── SpacingXXS          → ContextMenuOffsetX, ContextMenuOffsetY
├── PaddingContentHorizontalXS → TopLevelItemPadding, TopLevelItemPaddingSM
└── PaddingContentHorizontalSM → TopLevelItemPaddingLG

9.8 KiB Raw Blame History Unescape Escape

Menu Design Token