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

{
  "schemaVersion": 1,
  "sourceKind": "authored-spec",
  "provenance": "authored-in-repo",
  "specFile": "spec/移动端规格.md",
  "specSection": "42 · 消息通知 Message",
  "confidence": "high",
  "slug": "mobile-message",
  "name": "消息通知 Message",
  "semanticTypeCandidates": [
    "message",
    "notification",
    "banner"
  ],
  "variantDimensions": [
    {
      "name": "tone",
      "values": [
        "info",
        "success",
        "warning",
        "error"
      ]
    },
    {
      "name": "closable",
      "values": [
        "false",
        "true"
      ]
    }
  ],
  "representativeVariants": [
    {
      "tone": "info",
      "closable": "false",
      "label": "信息（默认形态）"
    },
    {
      "tone": "success",
      "closable": "false",
      "label": "成功"
    },
    {
      "tone": "warning",
      "closable": "true",
      "label": "警告（需要用户读完，带关闭）"
    },
    {
      "tone": "error",
      "closable": "true",
      "label": "错误（带关闭）"
    }
  ],
  "anatomy": {
    "message": "消息层根元素，顶部固定的纵向列表容器；pointer-events: none 让下方页面照常可点",
    "item": "单条消息，一行「图标 + 文字（+ 可选关闭）」，带 role=\"status\" 与 aria-live=\"polite\"",
    "icon": "语气图标（装饰），aria-hidden=\"true\"，语义由文字承担",
    "text": "消息文字，超长换行，不截断",
    "close": "可选的关闭按钮（原生 button，热区 44px）"
  },
  "structurePatterns": {
    "tone": "info / success / warning / error —— 图标字形与侧边描边同族，文字保持正文色",
    "closable": "false 读完自己消失 / true 右侧出现关闭按钮",
    "状态类": "is-open 展开（滑下淡入 240ms）"
  },
  "usageHints": [
    "在页面顶部给一条不打断操作的结果提示（提交成功、网络异常、库存告警、操作回执）",
    "触屏上页面就是有限的可视区域，所以消息浮在内容之上（fixed）且不吃手势（pointer-events: none），页面不跳",
    "与 Toast 的分工：Toast 占据视口中央用于「结果就是你此刻唯一关心的事」，Message 贴顶部一条用于「要告诉你但不该拦着你」",
    "组件形态：受控 open + 内容 props；duration 到点回传 close，由宿主决定是否收起",
    "命令式调用由宿主侧组装 —— 命令式 API 需要单例容器与跨端定时器治理，组件不提供全局方法"
  ],
  "doNotInvent": [
    "自动关闭的默认时长与「超时后是否保留」的策略",
    "多条消息的排队、合并、去重与同屏上限",
    "命令式全局方法（Message.success() 这类）与其单例容器",
    "消息内的操作按钮与跳转链接（需要动作时请用通知栏或对话框）"
  ],
  "unknowns": [
    "tone=warning 与 error 是否需要不同的停留时长（当前统一由宿主传 duration）",
    "顶部多条同时出现时是否该限制为最多两条（当前不限，由宿主控制）",
    "是否需要在消息层上提供「点整条跳详情」的交互（当前只有可选的关闭按钮可点）"
  ],
  "interaction": [
    "消息层不吃手势（根 pointer-events: none），只有关闭按钮自己接收手势",
    "自动消失时长由宿主决定：duration=0 表示不自动关闭",
    "入场从上滑下并淡入 240ms（--kole-m-duration-slide），减少动态偏好下瞬时切换",
    "多条并列时纵向排列，新的追加在下方；同屏条数上限由宿主决定"
  ],
  "accessibility": [
    "每条消息 role=\"status\" + aria-live=\"polite\"：读屏朗读一次，不打断用户当前操作",
    "语气图标 aria-hidden=\"true\"，语义全部由文字承担（颜色不是唯一的信息通道）",
    "关闭按钮是原生 button 并带 aria-label，可用 Tab 聚焦、Enter 触发",
    "消息不抢焦点：出现时不移动焦点，用户正在输入的内容不受影响"
  ],
  "api": {
    "source": "implementation",
    "note": "props / events / slots 为 6 端实现的公共接口（说明文字取自规格对应小节）。字段名与各端源码逐名核对：node tools/verify-mobile-docs.mjs",
    "requiredNote": "「必传」按严格定义：实现里**没有默认值**时才为 Y（本门禁逐条核对 props 与各端源码的默认值，防止契约与实现脱节）。",
    "props": [
      {
        "name": "tone",
        "type": "'info' | 'success' | 'warning' | 'error'",
        "default": "'info'",
        "desc": "变体 tone：语气配色与图标形态（规格 §42.3）",
        "required": false
      },
      {
        "name": "open",
        "type": "boolean",
        "default": "false",
        "desc": "状态 open：展开可见（规格 §42.4）",
        "required": false
      },
      {
        "name": "text",
        "type": "string",
        "default": "''",
        "desc": "消息文字；与默认插槽二选一，text 优先（规格 §42.2 text）",
        "required": false
      },
      {
        "name": "duration",
        "type": "number",
        "default": "3000",
        "desc": "自动关闭时长（毫秒）；0 表示不自动关闭（规格 §42.5）",
        "required": false
      },
      {
        "name": "closable",
        "type": "boolean",
        "default": "false",
        "desc": "变体 closable：是否显示右侧关闭按钮（规格 §42.3）",
        "required": false
      }
    ],
    "events": [
      {
        "name": "close",
        "params": "—",
        "desc": "点关闭按钮或 duration 到点时触发；是否收起由宿主决定（规格 §42.5）"
      }
    ],
    "slots": [
      {
        "name": "default",
        "desc": "消息内容（与 text 二选一；text 优先）"
      }
    ]
  },
  "variantClasses": {
    "tone": {
      "info": [
        ".kole-m-message__item--info"
      ],
      "success": [
        ".kole-m-message__item--success"
      ],
      "warning": [
        ".kole-m-message__item--warning"
      ],
      "error": [
        ".kole-m-message__item--error"
      ]
    },
    "closable": {
      "false": [],
      "true": [
        ".kole-m-message__close"
      ]
    }
  },
  "demos": [
    {
      "id": "tones",
      "group": "01 组件类型",
      "title": "四种语气",
      "desc": "信息 / 成功 / 警告 / 错误：图标与侧边描边同族变化，文字保持正文色以保证对比度不随语气波动。",
      "variant": "tone=info|success|warning|error"
    },
    {
      "id": "closable",
      "group": "01 组件类型",
      "title": "可关闭",
      "desc": "closable=true：右侧 × 是原生 button、热区 44px；需要用户读完的长文案给一条显式关闭路径。",
      "variant": "closable=true"
    },
    {
      "id": "duration",
      "group": "02 组件状态",
      "title": "自动消失",
      "desc": "duration 到点回传 close 由宿主收起；计时归宿主 —— 组件不持有默认时长以外的隐式行为。",
      "variant": "duration=3000"
    },
    {
      "id": "stack",
      "group": "02 组件状态",
      "title": "多条并列",
      "desc": "消息层纵向排列，多条同时在场各自独立；同屏条数上限与合并策略由宿主决定。",
      "variant": "多条同时 open"
    },
    {
      "id": "plain",
      "group": "02 组件状态",
      "title": "默认形态",
      "desc": "不带关闭按钮也不阻断操作：消息层自身 pointer-events: none，下方页面仍可正常点击与滚动。",
      "variant": "closable=false"
    }
  ],
  "related": [
    {
      "slug": "mobile-toast",
      "why": "需要占据视口中央、让用户只看结果时用轻提示；顶部一条且不打断操作用消息通知"
    },
    {
      "slug": "mobile-noticebar",
      "why": "常驻在页面里、随内容滚动的提醒用通知栏；消息通知浮在顶部且会消失"
    },
    {
      "slug": "mobile-dialog",
      "why": "需要用户先做决定再继续时用对话框，消息通知从不阻断操作"
    }
  ]
}