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

{
  "schemaVersion": 1,
  "sourceKind": "authored-spec",
  "provenance": "authored-in-repo",
  "specFile": "spec/移动端规格.md",
  "confidence": "high",
  "specSection": "16 · 通知栏 NoticeBar",
  "slug": "mobile-noticebar",
  "name": "通知栏 NoticeBar",
  "semanticTypeCandidates": [
    "notice",
    "banner",
    "marquee"
  ],
  "variantDimensions": [
    {
      "name": "tone",
      "values": [
        "default",
        "success",
        "warning",
        "danger"
      ]
    },
    {
      "name": "scrollable",
      "values": [
        "false",
        "true"
      ]
    },
    {
      "name": "closable",
      "values": [
        "false",
        "true"
      ]
    }
  ],
  "representativeVariants": [
    {
      "tone": "default",
      "scrollable": "false",
      "closable": "false",
      "label": "基础通告"
    },
    {
      "tone": "warning",
      "scrollable": "false",
      "closable": "true",
      "label": "可关闭提醒"
    },
    {
      "tone": "default",
      "scrollable": "true",
      "closable": "false",
      "label": "跑马灯长通告"
    },
    {
      "tone": "success",
      "scrollable": "false",
      "closable": "false",
      "label": "成功语气"
    }
  ],
  "anatomy": {
    "noticebar": "根容器",
    "noticebar__icon": "左侧喇叭图标",
    "noticebar__text": "通告文字（可滚动）",
    "noticebar__close": "可选关闭按钮"
  },
  "structurePatterns": {
    "tone": "default / success / warning / danger",
    "scrollable": "false / true（文字超宽时是否跑马灯）",
    "closable": "false / true"
  },
  "usageHints": [
    "在页面顶部或内容区之间横向滚动展示一条通告（如「系统维护通知」）",
    "关闭按钮热区不小于 24×24（用负外边距扩展）",
    "跑马灯在 prefers-reduced-motion: reduce 下停止滚动并改为换行显示（无障碍硬要求）",
    "关闭动作只触发一次事件，是否移除由宿主决定",
    "容器 role=\"status\"（读屏会朗读一次通告）",
    "跑马灯不得用 aria-live（滚动内容反复朗读会干扰）"
  ],
  "doNotInvent": [
    "多条通告的排队 / 轮播",
    "滚动速度的可配置项"
  ],
  "unknowns": [
    "通告文字的最大长度",
    "是否支持富文本"
  ],
  "interaction": [
    "关闭按钮热区不小于 24×24（用负外边距扩展）",
    "跑马灯在 prefers-reduced-motion: reduce 下停止滚动并改为换行显示（无障碍硬要求）",
    "关闭动作只触发一次事件，是否移除由宿主决定"
  ],
  "accessibility": [
    "容器 role=\"status\"（读屏会朗读一次通告）",
    "关闭按钮为原生 button 并带 aria-label",
    "跑马灯不得用 aria-live（滚动内容反复朗读会干扰）"
  ],
  "api": {
    "source": "implementation",
    "note": "props / events / slots 为 6 端实现的公共接口（说明文字取自规格对应小节）。字段名与各端源码逐名核对：node tools/verify-mobile-docs.mjs",
    "requiredNote": "「必传」按严格定义：实现里**没有默认值**时才为 Y（本门禁逐条核对 props 与各端源码的默认值，防止契约与实现脱节）。",
    "props": [
      {
        "name": "tone",
        "type": "'default' | 'success' | 'warning' | 'danger'",
        "default": "'default'",
        "desc": "变体 tone：四种语气（浅底 + 同族深字）（规格 §16.3）",
        "required": false
      },
      {
        "name": "scrollable",
        "type": "boolean",
        "default": "false",
        "desc": "变体 scrollable：文字超宽时是否跑马灯（规格 §16.3）",
        "required": false
      },
      {
        "name": "closable",
        "type": "boolean",
        "default": "false",
        "desc": "变体 closable：是否显示关闭按钮（规格 §16.3）",
        "required": false
      },
      {
        "name": "text",
        "type": "string",
        "default": "''",
        "desc": "通告文字（规格 §16.2 text）",
        "required": false
      }
    ],
    "events": [
      {
        "name": "close",
        "params": "—",
        "desc": "点击关闭按钮时触发；是否移除这条通告由宿主决定（规格 §16.5）"
      }
    ],
    "slots": [
      {
        "name": "default",
        "desc": "通告内容（与 text 二选一；text 优先）"
      }
    ]
  },
  "variantClasses": {
    "tone": {
      "default": [
        ".kole-m-noticebar--default"
      ],
      "success": [
        ".kole-m-noticebar--success"
      ],
      "warning": [
        ".kole-m-noticebar--warning"
      ],
      "danger": [
        ".kole-m-noticebar--danger"
      ]
    },
    "scrollable": {
      "false": [],
      "true": [
        ".kole-m-noticebar--scrollable"
      ]
    },
    "closable": {
      "false": [],
      "true": [
        ".kole-m-noticebar__close"
      ]
    }
  },
  "demos": [
    {
      "id": "basic",
      "group": "01 组件类型",
      "title": "基础通告",
      "desc": "品牌浅底 + 同族深字；容器带 role=status，读屏会朗读一次。",
      "variant": "tone=default"
    },
    {
      "id": "closable",
      "group": "01 组件类型",
      "title": "可关闭",
      "desc": "关闭按钮是原生 button、24×24 热区，aria-label 带上通告内容以便区分。",
      "variant": "closable=true"
    },
    {
      "id": "scrollable",
      "group": "01 组件类型",
      "title": "跑马灯",
      "desc": "文案超宽时横向循环滚动；系统开启「减少动态效果」时停止滚动并改为换行。",
      "variant": "scrollable=true"
    },
    {
      "id": "tone",
      "group": "02 组件状态",
      "title": "语义语气",
      "desc": "成功与失败语气用同族浅底，颜色之外还有图标区分，不只靠色相。",
      "variant": "tone=success|danger"
    }
  ],
  "related": [
    {
      "slug": "mobile-toast",
      "why": "一次性结果反馈用轻提示；需要常驻在页面里的通告才用通知栏"
    },
    {
      "slug": "mobile-tag",
      "why": "很短的状态词用标签；整句通告用通知栏"
    },
    {
      "slug": "mobile-divider",
      "why": "通知栏与内容区之间靠浅底与留白分隔，不必再插分割线"
    }
  ]
}