aurora-admin/.design_library/kole-ui-mobile/components/navbar.json

{
  "schemaVersion": 1,
  "sourceKind": "authored-spec",
  "provenance": "authored-in-repo",
  "specFile": "spec/移动端规格.md",
  "specSection": "1 · 顶部导航栏 NavBar",
  "confidence": "high",
  "slug": "navbar",
  "name": "顶部导航栏 NavBar",
  "semanticTypeCandidates": [
    "navbar",
    "appbar",
    "header"
  ],
  "variantDimensions": [
    {
      "name": "titleAlign",
      "values": [
        "center",
        "left"
      ]
    },
    {
      "name": "elevated",
      "values": [
        "false",
        "true"
      ]
    }
  ],
  "representativeVariants": [
    {
      "titleAlign": "center",
      "elevated": "false",
      "label": "标题居中 · 常态"
    },
    {
      "titleAlign": "left",
      "elevated": "false",
      "label": "标题左对齐"
    },
    {
      "titleAlign": "center",
      "elevated": "true",
      "label": "滚动后投影"
    },
    {
      "titleAlign": "left",
      "elevated": "true",
      "label": "左对齐 + 操作禁用"
    }
  ],
  "anatomy": {
    "bar": "导航栏容器，固定于页面顶部，高度 44px + 顶部安全区",
    "back": "左侧返回入口，可为返回箭头或文字",
    "title": "中间标题，单行省略",
    "actions": "右侧操作区，可放 1~2 个图标按钮或一个文字按钮",
    "divider": "可选底部分隔线"
  },
  "structurePatterns": {
    "titleAlign": "center（标题居中，左侧仅图标）/ left（标题左对齐，紧跟返回）",
    "elevated": "false（无阴影）/ true（滚动后投影）"
  },
  "usageHints": [
    "页面顶部的标题栏，提供返回入口、页面标题与右侧操作区",
    "固定于页面顶部，高度 44px + 顶部安全区",
    "标题超长时单行省略，不换行、不撑开栏高",
    "返回入口与右侧操作的点击热区不小于 44×44，视觉图标可小于该尺寸",
    "顶部内边距包含安全区，横屏与刘海屏不遮挡内容",
    "滚动后出现分隔线或投影"
  ],
  "doNotInvent": [
    "多行标题的折叠规则",
    "返回行为的栈深度策略（是否回退到首页）"
  ],
  "unknowns": [
    "阴影出现的确切滚动阈值",
    "右侧操作超过 2 个时的收敛方式"
  ],
  "interaction": [
    "返回入口与右侧操作的点击热区不小于 44×44，视觉图标可小于该尺寸",
    "标题超长时单行省略，不换行、不撑开栏高",
    "顶部内边距包含安全区，横屏与刘海屏不遮挡内容",
    "滚动后出现分隔线或投影"
  ],
  "accessibility": [
    "容器语义 role=banner（页内使用时也可用 role=navigation 并配 aria-label）",
    "标题节点具备 aria-label 或可见文本",
    "图标按钮具备 aria-label"
  ],
  "api": {
    "source": "implementation",
    "note": "props / events / slots 为 6 端实现的公共接口（说明文字取自规格对应小节）。字段名与各端源码逐名核对：node tools/verify-mobile-docs.mjs",
    "props": [
      {
        "name": "title",
        "type": "string",
        "default": "''",
        "desc": "中间标题，单行省略（规格 §1.2）",
        "required": false
      },
      {
        "name": "titleAlign",
        "type": "'center' | 'left'",
        "default": "'center'",
        "desc": "变体 titleAlign：标题居中或紧跟返回（规格 §1.3）",
        "required": false
      },
      {
        "name": "elevated",
        "type": "boolean",
        "default": "false",
        "desc": "滚动后出现分隔线与投影（规格 §1.4）",
        "required": false
      },
      {
        "name": "backText",
        "type": "string",
        "default": "'‹'",
        "desc": "返回入口文案，可为箭头或文字（规格 §1.2）",
        "required": false
      }
    ],
    "events": [
      {
        "name": "back",
        "params": "—",
        "desc": "点击返回入口时触发"
      }
    ],
    "slots": [
      {
        "name": "actions",
        "desc": "右侧操作区，可放 1~2 个图标按钮或一个文字按钮（规格 §1.2）"
      }
    ],
    "requiredNote": "「必传」按严格定义：实现里**没有默认值**时才为 Y（本门禁逐条核对 props 与各端源码的默认值，防止契约与实现脱节）。"
  },
  "variantClasses": {
    "titleAlign": {
      "center": [
        ".kole-m-navbar--center"
      ],
      "left": [
        ".kole-m-navbar--left"
      ]
    },
    "elevated": {
      "false": [],
      "true": [
        ".is-elevated"
      ]
    }
  },
  "demos": [
    {
      "id": "center",
      "group": "01 组件类型",
      "title": "标题居中",
      "desc": "左侧仅返回图标、右侧单个操作；标题在剩余空间居中并单行省略。",
      "variant": "titleAlign=center"
    },
    {
      "id": "left",
      "group": "01 组件类型",
      "title": "标题左对齐",
      "desc": "标题紧跟返回入口，适合标题较长或需要强调层级关系的页面。",
      "variant": "titleAlign=left"
    },
    {
      "id": "elevated",
      "group": "02 组件状态",
      "title": "滚动后投影",
      "desc": "页面滚动后加上 is-elevated：出现分隔线与投影，把导航栏与内容分层。",
      "variant": "elevated=true"
    }
  ],
  "related": [
    {
      "slug": "tabbar",
      "why": "底部一级导航。顶栏负责「我在哪、怎么回」，标签栏负责切换主模块"
    },
    {
      "slug": "actionsheet",
      "why": "顶栏右侧操作超过 2 个时，收进「更多」再打开动作面板"
    }
  ]
}