UI Design System
build dev
资产库 / 组件 / 导航组件 / NavigationMenu

NavigationMenu

提供顶部、底部或全局导航。中文惯用名：导航。设计文档原名：Navigation。
稳定本期新增已接入

元信息

字段值
规范 IDcomponent.navigation-menu
名称NavigationMenu
二级分类导航（navigation）
用途提供顶部、底部或全局导航
描述中文惯用名：导航。设计文档原名：Navigation。

预览

静态结构：Base UI NavigationMenu（data-slot="navigation-menu"）→ NavigationMenuList；含 children 的项渲染为触发器（data-slot="navigation-menu-trigger"，右侧 ChevronDown 展开时旋转 180°，打开态 data-open 带主色底）与下拉面板（data-slot="navigation-menu-content"，宽 w-64 的格子列表：每项为 navigation-menu-link = 图标 + 标题 + 描述行）；仅含 href 的项渲染为直链链接（复用 trigger 样式并改回横向 flex-row，与下拉面板内的纵向链接布局区分）。本条目 dsl 取自预览 NavigationPreview（产品 / 文档 / 关于）。

DSL 结构

DslNode
{
  "type": "NavigationMenu",
  "props": {
    "items": [
      {
        "label": "产品",
        "children": [
          {
            "label": "动态页面",
            "href": "#",
            "description": "DSL 驱动的页面运行时",
            "icon": "grid"
          },
          {
            "label": "资产库",
            "href": "#",
            "description": "组件与区块资产目录",
            "icon": "package"
          }
        ]
      },
      {
        "label": "文档",
        "href": "#",
        "icon": "file-text"
      },
      {
        "label": "关于",
        "href": "#"
      }
    ]
  }
}

何时用

何时使用

  • 站点级顶部导航：一级导航项 + 带说明的下拉面板（产品 / 方案 / 文档 / 关于）。
  • 需要在导航层级展示富信息：子项带标题 + 描述 + 图标的下拉面板。
  • 公开站点或门户的全局导航（相比 Menu 更「链接化」，无选中态语义）。

何时不用

  • 应用内带选中态的功能菜单（Sider / Header 内）：使用 Menu（含角标、分组、可折叠目录）。
  • 临时操作集合：使用 DropdownMenu。
  • 同层内容视图切换：使用 Tabs。

变体

变体视觉形态适用场景
下拉面板项触发器 + 面板：图标 + 标题 + 描述一级入口下需要说明多个子能力
直链项无下拉，点击直接跳转文档、关于等单页入口
带图标项图标 + 文案（触发器与直链均支持）提升一级导航的可识别度

API 属性

属性类型默认值说明
itemsNavigationMenuItemData[][]导航项（可含表达式）：{ label, href?, icon?, children? }；含 children 渲染为下拉面板，否则为直链
className / stylestring / CSSProperties—通用：根节点 class 合并 / 内联样式

使用规范

  • 一级项控制在 4 ~ 7 个，超出说明信息架构需要收拢。
  • 子项必须写 description：下拉面板的说明行是该组件相对普通菜单的价值所在。
  • 含 children 的项不再给 href（避免「既能点开面板又能跳转」的双重语义）；需要落地页时把落地页作为面板首项。
  • 一级文案用名词（「产品」「文档」），子项文案描述具体能力。
  • 站点导航不放业务状态（角标 / 选中态），状态型菜单交给 Menu。

正例

  • ✓ 站点顶栏：产品（下拉：动态页面 / 资产库）+ 文档 + 关于。
  • ✓ 门户导航：下拉面板内每项带一句话描述，帮助用户选择入口。

反例

  • ✕ 用 NavigationMenu 替代应用内带选中态的 Menu（缺少角标 / 分组 / 折叠能力）。
  • ✕ 把操作命令（导出、删除）放进导航子项（应使用 DropdownMenu）。

Design Token 映射

不适用：组件 tokenRefs 为空：样式 Token 数据尚未接入，三层映射（Primitive → Semantic → Component）待样式 Token 接入后回填。