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

{
  "schemaVersion": 1,
  "sourceKind": "authored-spec",
  "provenance": "authored-in-repo",
  "specFile": "spec/移动端规格.md",
  "confidence": "high",
  "specSection": "12 · 轻提示 Toast",
  "slug": "mobile-toast",
  "name": "轻提示 Toast",
  "semanticTypeCandidates": [
    "toast",
    "message",
    "snackbar"
  ],
  "variantDimensions": [
    {
      "name": "tone",
      "values": [
        "info",
        "success",
        "warning",
        "danger",
        "loading"
      ]
    },
    {
      "name": "position",
      "values": [
        "center",
        "bottom",
        "top"
      ]
    },
    {
      "name": "mask",
      "values": [
        "false",
        "true"
      ]
    }
  ],
  "representativeVariants": [
    {
      "tone": "info",
      "position": "center",
      "mask": "false",
      "label": "居中提示"
    },
    {
      "tone": "success",
      "position": "bottom",
      "mask": "false",
      "label": "底部成功提示"
    },
    {
      "tone": "loading",
      "position": "center",
      "mask": "true",
      "label": "加载中（带遮罩）"
    }
  ],
  "anatomy": {
    "toast": "浮层本体，居中于视口",
    "icon": "状态图标（可选）",
    "text": "提示文字",
    "mask": "可选透明遮罩（mask=true 时阻断下方点击）"
  },
  "structurePatterns": {
    "tone": "info / success / warning / danger / loading",
    "position": "center / bottom / top",
    "mask": "false / true（阻断交互）"
  },
  "usageHints": [
    "在屏幕中央或底部短暂提示一条结果信息（成功 / 失败 / 警告 / 加载中），不打断当前操作",
    "提示本身不可点（不抢焦点、不阻断），mask=true 时遮罩吸收手势",
    "出现 / 消失动画 240ms；自动关闭时长由宿主控制（本组件只负责显示态）",
    "容器 role=\"status\" + aria-live=\"polite\"（结果朗读一次，不反复打断）",
    "图标为装饰（aria-hidden=\"true\"），语义全部由文字承担"
  ],
  "doNotInvent": [
    "自动关闭的默认时长",
    "多条提示的排队 / 合并策略"
  ],
  "unknowns": [
    "单行文字的最大宽度与换行规则",
    "是否需要点击穿透设置"
  ],
  "interaction": [
    "提示本身不可点（不抢焦点、不阻断），mask=true 时遮罩吸收手势",
    "出现 / 消失动画 240ms；自动关闭时长由宿主控制（本组件只负责显示态）"
  ],
  "accessibility": [
    "容器 role=\"status\" + aria-live=\"polite\"（结果朗读一次，不反复打断）",
    "图标为装饰（aria-hidden=\"true\"），语义全部由文字承担"
  ],
  "api": {
    "source": "implementation",
    "note": "props / events / slots 为 6 端实现的公共接口（说明文字取自规格对应小节）。字段名与各端源码逐名核对：node tools/verify-mobile-docs.mjs",
    "requiredNote": "「必传」按严格定义：实现里**没有默认值**时才为 Y（本门禁逐条核对 props 与各端源码的默认值，防止契约与实现脱节）。",
    "props": [
      {
        "name": "tone",
        "type": "'info' | 'success' | 'warning' | 'danger' | 'loading'",
        "default": "'info'",
        "desc": "变体 tone：语义配色与图标形态（规格 §12.3）",
        "required": false
      },
      {
        "name": "position",
        "type": "'center' | 'bottom' | 'top'",
        "default": "'center'",
        "desc": "变体 position：提示出现的位置（规格 §12.3）",
        "required": false
      },
      {
        "name": "open",
        "type": "boolean",
        "default": "false",
        "desc": "状态 open：展开可见（规格 §12.4）",
        "required": false
      },
      {
        "name": "mask",
        "type": "boolean",
        "default": "false",
        "desc": "是否显示遮罩并阻断下方交互（规格 §12.3）",
        "required": false
      },
      {
        "name": "text",
        "type": "string",
        "default": "''",
        "desc": "提示文字（规格 §12.2 text）",
        "required": false
      }
    ],
    "events": [],
    "slots": [
      {
        "name": "default",
        "desc": "提示内容（与 text 二选一；text 优先）"
      }
    ]
  },
  "variantClasses": {
    "tone": {
      "info": [],
      "success": [],
      "warning": [],
      "danger": [],
      "loading": [
        ".kole-m-toast--loading"
      ]
    },
    "position": {
      "center": [
        ".kole-m-toast--center"
      ],
      "bottom": [
        ".kole-m-toast--bottom"
      ],
      "top": [
        ".kole-m-toast--top"
      ]
    },
    "mask": {
      "false": [],
      "true": [
        ".kole-m-toast__mask"
      ]
    }
  },
  "demos": [
    {
      "id": "center",
      "group": "01 组件类型",
      "title": "居中提示",
      "desc": "最常用的形态：居中显示一条结果，不打断当前操作。",
      "variant": "position=center"
    },
    {
      "id": "tone",
      "group": "01 组件类型",
      "title": "语义语气",
      "desc": "成功 / 警告等语气只改变图标与语义，文字始终是唯一的信息载体。",
      "variant": "tone=success|warning"
    },
    {
      "id": "top",
      "group": "01 组件类型",
      "title": "顶部提示",
      "desc": "出现在顶部时不遮挡底部操作区，适合「已复制」这类轻反馈。",
      "variant": "position=top"
    },
    {
      "id": "loading",
      "group": "02 组件状态",
      "title": "加载中",
      "desc": "tone=loading 时图标持续旋转并标记 aria-busy；减少动态偏好下停止旋转。",
      "variant": "状态 loading"
    },
    {
      "id": "mask",
      "group": "02 组件状态",
      "title": "带遮罩",
      "desc": "mask=true 时遮罩吸收手势，下方内容在提示期间不可点。",
      "variant": "mask=true"
    }
  ],
  "related": [
    {
      "slug": "mobile-popup",
      "why": "需要承载内容与操作时用弹出层，轻提示只承载一句结果"
    },
    {
      "slug": "mobile-noticebar",
      "why": "常驻的通告用通知栏，一次性反馈用轻提示"
    },
    {
      "slug": "mobile-dialog",
      "why": "需要用户做决定（确认 / 取消）时用对话框，提示不需要决定"
    }
  ]
}