AtomUI/docs/Desktop.Controls/NavMenu/NavMenuToken.md

NavMenu Design Token

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

---

Token 资源访问方式

在 AXAML 中使用组件级 Token：

{atom:NavMenuTokenResource ItemColor}
{atom:NavMenuTokenResource ItemSelectedBg}
{atom:NavMenuTokenResource DarkMenuBg}

在 AXAML 中使用全局共享 Token：

{atom:SharedTokenResource ColorPrimary}
{atom:SharedTokenResource ControlHeight}
{atom:SharedTokenResource ColorText}

---

组件级 Token 一览

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

菜单项颜色 Token

Token 名	类型	来源	说明
ItemColor	Color	SharedToken.ColorText	菜单项文字颜色
ItemHoverColor	Color	SharedToken.ColorText	菜单项悬浮文字颜色
ItemSelectedColor	Color	SharedToken.ColorPrimary	菜单项选中文字颜色
ItemDisabledColor	Color	SharedToken.ColorTextDisabled	菜单项禁用文字颜色
HorizontalItemHoverColor	Color	SharedToken.ColorPrimary	水平菜单项悬浮文字颜色
HorizontalItemSelectedColor	Color	SharedToken.ColorPrimary	水平菜单项选中文字颜色
GroupTitleColor	Color	SharedToken.ColorTextDescription	分组标题文字颜色
KeyGestureColor	Color	SharedToken.ColorTextSecondary	快捷键文字颜色

菜单项背景 Token

Token 名	类型	来源	说明
ItemBg	Color	SharedToken.ColorTransparent	菜单项默认背景色（透明）
ItemHoverBg	Color	SharedToken.ColorBgTextHover	菜单项悬浮背景色
ItemActiveBg	Color	SharedToken.ColorFillContent	菜单项激活背景色
ItemSelectedBg	Color	SharedToken.ControlItemBgActive	菜单项选中背景色
SubMenuItemBg	Color	SharedToken.ColorFillAlter	子菜单项背景色
HorizontalItemSelectedBg	Color	Colors.Transparent	水平菜单项选中背景色
HorizontalItemHoverBg	Color	Colors.Transparent	水平菜单项悬浮背景色

危险菜单项 Token

Token 名	类型	来源	说明
DangerItemColor	Color	SharedToken.ColorError	危险菜单项文字颜色
DangerItemHoverColor	Color	SharedToken.ColorError	危险菜单项悬浮文字颜色
DangerItemSelectedColor	Color	SharedToken.ColorError	危险菜单项选中文字颜色
DangerItemActiveBg	Color	SharedToken.ColorError	危险菜单项激活背景色
DangerItemSelectedBg	Color	SharedToken.ColorError	危险菜单项选中背景色

圆角 Token

Token 名	类型	来源	说明
ItemBorderRadius	CornerRadius	SharedToken.BorderRadiusLG	菜单项圆角
SubMenuItemBorderRadius	CornerRadius	SharedToken.BorderRadiusSM	子菜单项圆角
HorizontalItemBorderRadius	CornerRadius	new CornerRadius(0)	水平菜单项圆角（无圆角）

尺寸与间距 Token

Token 名	类型	来源	说明
ItemHeight	double	SharedToken.ControlHeight	菜单项高度
ItemContentMargin	Thickness	SharedToken.UniformlyMarginXXS	菜单项内容外间距
ItemContentPadding	Thickness	基于 SharedToken.UniformlyPadding	菜单项内容内间距
ItemMargin	Thickness	(0, 0, SharedToken.UniformlyMarginXS, 0)	菜单项内部元素边距
HorizontalItemMargin	Thickness	(SharedToken.UniformlyPadding, 0)	水平菜单项外间距
InlineItemIndentUnit	double	ItemHeight / 2	内联菜单项缩进单位
VerticalItemsPanelSpacing	double	SharedToken.UniformlyMarginXXS	垂直面板元素间距
VerticalChildItemsMargin	Thickness	(0, SharedToken.UniformlyMarginXXS, 0, 0)	垂直面板子项外间距
VerticalMenuContentPadding	Thickness	SharedToken.PaddingXXS	垂直面板内容内间距

图标 Token

Token 名	类型	来源	说明
IconSize	double	SharedToken.FontSize	菜单项图标尺寸
IconMargin	Thickness	基于 SharedToken.ControlHeightSM - FontSize	图标与文字间距
ItemIconSize	double	SharedToken.IconSize	菜单项图标展示尺寸
CollapsedIconSize	double	SharedToken.FontSizeLG	收起时图标尺寸

字体 Token

Token 名	类型	来源	说明
GroupTitleFontSize	double	SharedToken.FontSize	分组标题字体大小
GroupTitleLineHeight	double	SharedToken.ControlHeight	分组标题行高

水平菜单 Token

Token 名	类型	来源	说明
MenuHorizontalHeight	double	SharedToken.ControlHeightLG * 1.15	水平菜单整体高度
HorizontalLineHeight	double	SharedToken.ControlHeightLG * 1.15	水平菜单行高
ActiveBarScaleX	double	1.0	选中指示条宽度比例
ActiveBarHeight	double	SharedToken.LineWidthBold	选中指示条高度

Popup Token

Token 名	类型	来源	说明
MenuPopupBg	Color	SharedToken.ColorBgElevated	Popup 背景色
MenuPopupContentPadding	Thickness	基于 SharedToken.UniformlyPaddingXXS	Popup 内容内间距
MenuPopupMinWidth	double	160	Popup 最小宽度
MenuPopupMaxWidth	double	800	Popup 最大宽度
MenuPopupMaxHeight	double	ItemHeight * 30	Popup 最大高度
TopLevelItemPopupMarginToAnchor	double	SharedToken.UniformlyMarginXS	顶层菜单项 Popup 边距
MenuSubMenuBg	Color	SharedToken.ColorBgElevated	子菜单背景色
MenuArrowSize	double	SharedToken.FontSize / 7 * 5	菜单箭头尺寸

其他 Token

Token 名	类型	来源	说明
CollapsedWidth	double	SharedToken.ControlHeight * 2	收起后菜单宽度

---

暗色主题 Token

暗色主题使用一套完全独立的 Token，当 IsDarkStyle=True 时生效：

Token 名	类型	来源	说明
DarkMenuBg	Color	#001529	暗色菜单背景色
DarkMenuPopupBg	Color	#001529	暗色 Popup 背景色
DarkItemColor	Color	基于 ColorTextLightSolid 65% 透明度	暗色菜单项文字颜色
DarkItemBg	Color	Colors.Transparent	暗色菜单项背景色
DarkSubMenuItemBg	Color	#000c17	暗色子菜单项背景色
DarkItemSelectedColor	Color	SharedToken.ColorTextLightSolid	暗色选中文字颜色
DarkItemSelectedBg	Color	SharedToken.ColorPrimary	暗色选中背景色
DarkItemHoverBg	Color	Colors.Transparent	暗色悬浮背景色
DarkItemHoverColor	Color	SharedToken.ColorTextLightSolid	暗色悬浮文字颜色
DarkItemDisabledColor	Color	基于 ColorTextLightSolid 25% 透明度	暗色禁用文字颜色
DarkGroupTitleColor	Color	基于 ColorTextLightSolid 65% 透明度	暗色分组标题颜色
DarkDangerItemColor	Color	SharedToken.ColorError	暗色危险菜单项文字颜色
DarkDangerItemHoverColor	Color	SharedToken.ColorErrorHover	暗色危险菜单项悬浮颜色
DarkDangerItemSelectedColor	Color	SharedToken.ColorTextLightSolid	暗色危险菜单项选中颜色
DarkDangerItemSelectedBg	Color	SharedToken.ColorError	暗色危险菜单项选中背景
DarkDangerItemActiveBg	Color	SharedToken.ColorError	暗色危险菜单项激活背景

---

主题中使用的全局 SharedToken

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

Token 资源键	使用场景
ColorPrimary / ColorPrimaryHover / ColorPrimaryActive	选中项、悬浮项主色调
ColorText / ColorTextDescription / ColorTextDisabled	文字颜色系列
ColorTextLightSolid	亮色文字（用于暗色主题推导）
ColorTextSecondary	次要文字（快捷键颜色）
ColorBgTextHover	文本悬浮背景色
ColorBgElevated	弹出层背景色
ColorBgContainer	容器背景色
ColorFillContent / ColorFillAlter	填充颜色
ColorTransparent	透明色
ColorError / ColorErrorHover	错误/危险色系
ControlHeight / ControlHeightSM / ControlHeightLG	控件高度
ControlItemBgActive	活跃项背景色
BorderRadius / BorderRadiusSM / BorderRadiusLG	圆角系列
FontSize / FontSizeLG	字体大小
IconSize / IconSizeSM	全局图标尺寸
LineWidthBold	粗线宽度（指示条高度）
EnableMotion	全局动画开关

---

Token 对外观的具体影响

亮色主题下菜单项状态与 Token 映射

状态	文字色	背景色
正常	ItemColor	ItemBg（透明）
悬浮	ItemHoverColor	ItemHoverBg
激活	—	ItemActiveBg
选中	ItemSelectedColor	ItemSelectedBg
禁用	ItemDisabledColor	—

暗色主题下菜单项状态与 Token 映射

状态	文字色	背景色
正常	DarkItemColor	DarkItemBg（透明）
悬浮	DarkItemHoverColor	DarkItemHoverBg
选中	DarkItemSelectedColor	DarkItemSelectedBg
禁用	DarkItemDisabledColor	—

水平模式特殊 Token

水平模式下，选中项不使用背景色高亮，而是通过底部指示条（ActiveBarHeight × ActiveBarScaleX）标识选中状态。选中文字使用 HorizontalItemSelectedColor，悬浮文字使用 HorizontalItemHoverColor。