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

{
  "schemaVersion": 1,
  "sourceKind": "authored-spec",
  "provenance": "authored-in-repo",
  "specFile": "spec/移动端规格.md",
  "confidence": "high",
  "specSection": "13 · 对话框 Dialog",
  "slug": "mobile-dialog",
  "name": "对话框 Dialog",
  "semanticTypeCandidates": [
    "dialog",
    "modal",
    "confirm"
  ],
  "variantDimensions": [
    {
      "name": "variant",
      "values": [
        "confirm",
        "alert"
      ]
    },
    {
      "name": "tone",
      "values": [
        "default",
        "danger"
      ]
    },
    {
      "name": "round",
      "values": [
        "false",
        "true"
      ]
    }
  ],
  "representativeVariants": [
    {
      "variant": "confirm",
      "tone": "default",
      "round": "true",
      "label": "确认框"
    },
    {
      "variant": "confirm",
      "tone": "danger",
      "round": "true",
      "label": "危险确认"
    },
    {
      "variant": "alert",
      "tone": "default",
      "round": "true",
      "label": "提示框（单按钮）"
    }
  ],
  "anatomy": {
    "mask": "遮罩，点击可关（可配置）",
    "dialog": "对话框本体，居中",
    "header": "标题区",
    "body": "内容区",
    "footer": "操作按钮组（取消 / 确认）"
  },
  "structurePatterns": {
    "variant": "confirm（两个按钮）/ alert（单按钮铺满）",
    "tone": "default / danger",
    "round": "false / true"
  },
  "usageHints": [
    "需要用户确认或输入的中断式浮层：标题 + 内容 + 操作按钮组",
    "遮罩点击关闭；closeOnMask=false 时不关闭",
    "Esc 关闭（键盘可达时）",
    "按钮热区不小于 44px；操作按钮等宽排列",
    "对话框 role=\"dialog\" + aria-modal=\"true\" + aria-labelledby 指向标题",
    "遮罩 aria-hidden=\"true\""
  ],
  "doNotInvent": [
    "焦点陷阱（focus trap）的完整实现",
    "多对话框嵌套时的层级规则"
  ],
  "unknowns": [
    "对话框的最大宽度与最大高度",
    "长内容是否在 body 内滚动"
  ],
  "interaction": [
    "遮罩点击关闭；closeOnMask=false 时不关闭",
    "Esc 关闭（键盘可达时）",
    "按钮热区不小于 44px；操作按钮等宽排列"
  ],
  "accessibility": [
    "对话框 role=\"dialog\" + aria-modal=\"true\" + aria-labelledby 指向标题",
    "打开后焦点落在对话框内（本实现只标记 tabindex=\"-1\" + role，焦点陷阱见 §13.7）",
    "遮罩 aria-hidden=\"true\""
  ],
  "api": {
    "source": "implementation",
    "note": "props / events / slots 为 6 端实现的公共接口（说明文字取自规格对应小节）。字段名与各端源码逐名核对：node tools/verify-mobile-docs.mjs",
    "requiredNote": "「必传」按严格定义：实现里**没有默认值**时才为 Y（本门禁逐条核对 props 与各端源码的默认值，防止契约与实现脱节）。",
    "props": [
      {
        "name": "variant",
        "type": "'confirm' | 'alert'",
        "default": "'confirm'",
        "desc": "变体 variant：确认框（两按钮）/ 提示框（单按钮铺满）（规格 §13.3）",
        "required": false
      },
      {
        "name": "tone",
        "type": "'default' | 'danger'",
        "default": "'default'",
        "desc": "变体 tone：danger 时确认按钮用错误色（规格 §13.3）",
        "required": false
      },
      {
        "name": "round",
        "type": "boolean",
        "default": "false",
        "desc": "变体 round：是否切圆角（规格 §13.3）",
        "required": false
      },
      {
        "name": "open",
        "type": "boolean",
        "default": "false",
        "desc": "状态 open：展开且遮罩可见（规格 §13.4）",
        "required": false
      },
      {
        "name": "closeOnMask",
        "type": "boolean",
        "default": "true",
        "desc": "遮罩点击是否关闭；表单类内容通常设为 false（规格 §13.5）",
        "required": false
      },
      {
        "name": "title",
        "type": "string",
        "default": "''",
        "desc": "标题文字，同时作为 aria-labelledby 指向的内容（规格 §13.2 header）",
        "required": false
      },
      {
        "name": "confirmText",
        "type": "string",
        "default": "'确定'",
        "desc": "确认按钮文案（规格 §13.2 footer）",
        "required": false
      },
      {
        "name": "cancelText",
        "type": "string",
        "default": "'取消'",
        "desc": "取消按钮文案（规格 §13.2 footer）",
        "required": false
      },
      {
        "name": "confirmDisabled",
        "type": "boolean",
        "default": "false",
        "desc": "状态 loading：确认按钮进入加载态并禁用（规格 §13.4）",
        "required": false
      }
    ],
    "events": [
      {
        "name": "confirm",
        "params": "—",
        "desc": "点击确认按钮时触发（确认按钮禁用时不触发）"
      },
      {
        "name": "cancel",
        "params": "—",
        "desc": "点击取消按钮或遮罩（closeOnMask=true 时）时触发"
      }
    ],
    "slots": [
      {
        "name": "default",
        "desc": "内容区（规格 §13.2 body）"
      }
    ]
  },
  "variantClasses": {
    "variant": {
      "confirm": [],
      "alert": []
    },
    "tone": {
      "default": [
        ".kole-m-dialog__btn--primary"
      ],
      "danger": [
        ".kole-m-dialog__btn--danger"
      ]
    },
    "round": {
      "false": [],
      "true": [
        ".kole-m-dialog--round"
      ]
    }
  },
  "demos": [
    {
      "id": "confirm",
      "group": "01 组件类型",
      "title": "确认框",
      "desc": "两个按钮等宽排列，取消在左、确认在右（与移动端平台惯例一致）。",
      "variant": "variant=confirm"
    },
    {
      "id": "danger",
      "group": "01 组件类型",
      "title": "危险确认",
      "desc": "删除类操作把确认按钮转为错误色，让代价在视觉上先被看到。",
      "variant": "tone=danger"
    },
    {
      "id": "alert",
      "group": "01 组件类型",
      "title": "提示框",
      "desc": "variant=alert 只有一个按钮并铺满整行，用于「知道了」这类单向告知。",
      "variant": "variant=alert"
    },
    {
      "id": "loading",
      "group": "02 组件状态",
      "title": "提交中",
      "desc": "确认按钮进入禁用态并标记 aria-busy，避免重复提交。",
      "variant": "状态 loading"
    },
    {
      "id": "keep-open",
      "group": "02 组件状态",
      "title": "遮罩不关闭",
      "desc": "closeOnMask=false：已填内容不因一次误触就丢失。",
      "variant": "closeOnMask=false"
    }
  ],
  "related": [
    {
      "slug": "actionsheet",
      "why": "从底部弹出的多选项列表用动作面板，对话框用于需要做决定的中断式确认"
    },
    {
      "slug": "mobile-popup",
      "why": "需要自定义内容与方向时用弹出层，对话框只是它的一种固定形态"
    },
    {
      "slug": "mobile-toast",
      "why": "只是告知结果、不需要用户决定时用轻提示，不要用对话框打断"
    }
  ]
}