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

{
  "schemaVersion": 1,
  "sourceKind": "authored-spec",
  "provenance": "authored-in-repo",
  "specFile": "spec/移动端规格.md",
  "confidence": "high",
  "specSection": "17 · 数字键盘 NumberKeyboard",
  "slug": "mobile-numberkeyboard",
  "name": "数字键盘 NumberKeyboard",
  "semanticTypeCandidates": [
    "keyboard",
    "keypad",
    "numpad"
  ],
  "variantDimensions": [
    {
      "name": "type",
      "values": [
        "number",
        "digit"
      ]
    },
    {
      "name": "showDelete",
      "values": [
        "false",
        "true"
      ]
    },
    {
      "name": "showConfirm",
      "values": [
        "false",
        "true"
      ]
    }
  ],
  "representativeVariants": [
    {
      "type": "number",
      "showDelete": "true",
      "showConfirm": "false",
      "label": "金额键盘（含小数点）"
    },
    {
      "type": "digit",
      "showDelete": "true",
      "showConfirm": "false",
      "label": "纯数字键盘"
    },
    {
      "type": "number",
      "showDelete": "true",
      "showConfirm": "true",
      "label": "带确认键"
    }
  ],
  "anatomy": {
    "keyboard": "根容器，固定在底部",
    "keyboard__key": "单个按键",
    "keyboard__key--delete": "删除键",
    "keyboard__confirm": "确认键（showConfirm=true 时）"
  },
  "structurePatterns": {
    "type": "number（0-9 + 小数点）/ digit（纯 0-9）",
    "showDelete": "false / true",
    "showConfirm": "false / true"
  },
  "usageHints": [
    "为金额、验证码等纯数字输入提供自绘键盘（比系统键盘更可控、更安全）",
    "按键热区不小于 44×44，网格等分排列",
    "按下用 :active，不做悬停态",
    "键盘本身不持有输入值 —— 只 emit 按键事件，由宿主决定写入哪个输入框",
    "容器 role=\"group\" + aria-label",
    "每个按键为原生 button，文字即按键名（读屏读「1」「删除」）",
    "删除键用 aria-label=\"删除\"（不读成符号）"
  ],
  "doNotInvent": [
    "键盘高度的手势拖拽调整",
    "与系统键盘的互斥逻辑"
  ],
  "unknowns": [
    "是否支持自定义按键顺序",
    "长按连续删除的间隔"
  ],
  "interaction": [
    "按键热区不小于 44×44，网格等分排列",
    "按下用 :active，不做悬停态",
    "键盘本身不持有输入值 —— 只 emit 按键事件，由宿主决定写入哪个输入框"
  ],
  "accessibility": [
    "容器 role=\"group\" + aria-label",
    "每个按键为原生 button，文字即按键名（读屏读「1」「删除」）",
    "删除键用 aria-label=\"删除\"（不读成符号）"
  ],
  "api": {
    "source": "implementation",
    "note": "props / events / slots 为 6 端实现的公共接口（说明文字取自规格对应小节）。字段名与各端源码逐名核对：node tools/verify-mobile-docs.mjs",
    "requiredNote": "「必传」按严格定义：实现里**没有默认值**时才为 Y（本门禁逐条核对 props 与各端源码的默认值，防止契约与实现脱节）。",
    "props": [
      {
        "name": "type",
        "type": "'number' | 'digit'",
        "default": "'number'",
        "desc": "变体 type：number 含小数点键，digit 为纯 0-9（规格 §17.3）",
        "required": false
      },
      {
        "name": "showDelete",
        "type": "boolean",
        "default": "true",
        "desc": "变体 showDelete：是否显示删除键（规格 §17.3）",
        "required": false
      },
      {
        "name": "showConfirm",
        "type": "boolean",
        "default": "false",
        "desc": "变体 showConfirm：是否显示确认键（跨两列、品牌色实底）（规格 §17.3）",
        "required": false
      },
      {
        "name": "open",
        "type": "boolean",
        "default": "false",
        "desc": "状态 open：键盘是否展开（规格 §17.4）",
        "required": false
      },
      {
        "name": "confirmDisabled",
        "type": "boolean",
        "default": "false",
        "desc": "状态 disabled：确认键是否不可用（规格 §17.4）",
        "required": false
      }
    ],
    "events": [
      {
        "name": "input",
        "params": "key: string",
        "desc": "按下按键时触发：数字键回传该字符，删除键回传 'delete'，确认键回传 'confirm'；键盘不持有输入值（规格 §17.5）"
      }
    ],
    "slots": [
      {
        "name": "default",
        "desc": "额外的自定义按键（追加在标准按键之后）"
      }
    ]
  },
  "variantClasses": {
    "type": {
      "number": [],
      "digit": []
    },
    "showDelete": {
      "false": [],
      "true": [
        ".kole-m-numberkeyboard__key--delete"
      ]
    },
    "showConfirm": {
      "false": [],
      "true": [
        ".kole-m-numberkeyboard__confirm"
      ]
    }
  },
  "demos": [
    {
      "id": "number",
      "group": "01 组件类型",
      "title": "金额键盘",
      "desc": "含小数点与删除键；按键只回传字符，写入哪个输入框由宿主决定。",
      "variant": "type=number"
    },
    {
      "id": "digit",
      "group": "01 组件类型",
      "title": "纯数字键盘",
      "desc": "验证码场景：没有小数点键，最后两格是删除与收起。",
      "variant": "type=digit"
    },
    {
      "id": "confirm",
      "group": "01 组件类型",
      "title": "带确认键",
      "desc": "确认键跨两列并用品牌色实底，与数字键在视觉上分层。",
      "variant": "showConfirm=true"
    },
    {
      "id": "disabled",
      "group": "02 组件状态",
      "title": "确认键禁用",
      "desc": "金额为 0 时确认键置灰不可点，避免无效提交。",
      "variant": "状态 disabled"
    }
  ],
  "related": [
    {
      "slug": "mobile-dialog",
      "why": "金额确认这类需要「先输入再决定」的场景，键盘配合对话框一起用"
    },
    {
      "slug": "mobile-toast",
      "why": "键盘输入完成后的结果反馈用轻提示"
    },
    {
      "slug": "mobile-popup",
      "why": "键盘本身就是底部浮层；不要再用弹出层包一层同向浮层"
    }
  ]
}