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

{
  "schemaVersion": 1,
  "sourceKind": "authored-spec",
  "provenance": "authored-in-repo",
  "specFile": "spec/移动端规格.md",
  "specSection": "30 · 步进器 Stepper",
  "confidence": "high",
  "slug": "mobile-stepper",
  "name": "步进器 Stepper",
  "semanticTypeCandidates": [
    "stepper",
    "spinbutton",
    "quantity-input"
  ],
  "variantDimensions": [
    {
      "name": "size",
      "values": [
        "default",
        "small"
      ]
    },
    {
      "name": "round",
      "values": [
        "false",
        "true"
      ]
    }
  ],
  "representativeVariants": [
    {
      "size": "default",
      "round": "false",
      "label": "默认（控件高 44px，方角嵌在表单里）"
    },
    {
      "size": "default",
      "round": "true",
      "label": "全圆角（购物车等轻量场合）"
    },
    {
      "size": "small",
      "round": "false",
      "label": "紧凑（视觉 36px，热区外扩回 44px）"
    }
  ],
  "anatomy": {
    "stepper": "根元素，一行里放进「减号 + 值 + 加号」",
    "minus": "减号按钮，到达 min 时置灰",
    "value": "值区；editable=true 时是可聚焦的数字输入框，否则是纯文本",
    "plus": "加号按钮，到达 max 时置灰",
    "unit": "可选单位文案，跟在值后面（如「件」），由默认插槽给出",
    "label": "无障碍分组名称（role=\"group\" + aria-label）"
  },
  "structurePatterns": {
    "size": "default（控件高 44px）/ small（控件高 36px，视觉更紧凑）",
    "round": "false（方角）/ true（全圆角，用于购物车等轻量场合）"
  },
  "usageHints": [
    "在一段有界区间里连续加减小整数（购买数量、份数、编号）",
    "加号与减号必须各自独立占一个 44px 见方的热区",
    "到边界时不是把按钮藏起来，而是置灰 —— 触屏上「按钮消失」会让用户以为界面坏了",
    "单击步进一个 step，不响应长按连击（长按是桌面习惯，触屏上容易多跳）",
    "值变化后立即触发 change 事件，不做防抖"
  ],
  "doNotInvent": [
    "长按连击、惯性加速的时值曲线",
    "小数与浮点精度（本组件只处理整数；金额请用输入框 + 数字键盘）",
    "超出边界的提示文案（由宿主决定是否提示）"
  ],
  "unknowns": [
    "值为 0 时是否自动隐藏整个步进器（购物车场景）",
    "是否需要键盘上的上下方向键加减",
    "单位文案是否随语言变化"
  ],
  "interaction": [
    "加号与减号各自是 44px 见方的热区；size=small 视觉 36px 时用 --kole-m-hit-slack 把热区外扩回 44px",
    "单击步进一个 step，不响应长按连击（长按是桌面习惯，触屏上容易多跳）",
    "到达 min / max 时对应按钮置 disabled 且置灰，点击不产生值与事件",
    "值变化后立即触发 change 事件，不做防抖",
    "editable=true 时值区接受键盘直接输入；非法输入（非数字、越界）在失焦时回落到边界值"
  ],
  "accessibility": [
    "根元素 role=\"group\" + aria-label 说明这组控件在调什么",
    "减号 / 加号是原生 button，各自的 aria-label 是「减少」/「增加」（不用符号代替名称）",
    "值区在只读态置 role=\"spinbutton\" 并写 aria-valuenow / aria-valuemin / aria-valuemax",
    "置灰的按钮用原生 disabled，读屏会播报不可用且键盘会跳过"
  ],
  "api": {
    "source": "implementation",
    "note": "props / events / slots 为 6 端实现的公共接口（说明文字取自规格对应小节）。字段名与各端源码逐名核对：node tools/verify-mobile-docs.mjs",
    "requiredNote": "「必传」按严格定义：实现里**没有默认值**时才为 Y（本门禁逐条核对 props 与各端源码的默认值，防止契约与实现脱节）。",
    "props": [
      {
        "name": "value",
        "type": "number",
        "default": "1",
        "desc": "当前值，受控；变化通过 change 回传（规格 §30.5）",
        "required": false
      },
      {
        "name": "min",
        "type": "number",
        "default": "1",
        "desc": "下界，到达时减号置灰（规格 §30.4）",
        "required": false
      },
      {
        "name": "max",
        "type": "number",
        "default": "99",
        "desc": "上界，到达时加号置灰（规格 §30.4）",
        "required": false
      },
      {
        "name": "step",
        "type": "number",
        "default": "1",
        "desc": "单次步进量（规格 §30.5）",
        "required": false
      },
      {
        "name": "size",
        "type": "'default' | 'small'",
        "default": "'default'",
        "desc": "变体 size：default 高 44px，small 视觉 36px（热区外扩回 44px）（规格 §30.3）",
        "required": false
      },
      {
        "name": "round",
        "type": "boolean",
        "default": "false",
        "desc": "变体 round：全圆角（规格 §30.3）",
        "required": false
      },
      {
        "name": "editable",
        "type": "boolean",
        "default": "false",
        "desc": "值区是否可键盘直接输入（规格 §30.5）",
        "required": false
      },
      {
        "name": "disabled",
        "type": "boolean",
        "default": "false",
        "desc": "状态 disabled：整组置灰且不可聚焦（规格 §30.4）",
        "required": false
      },
      {
        "name": "label",
        "type": "string",
        "default": "''",
        "desc": "无障碍分组名称，落到 role=\"group\" 的 aria-label（规格 §30.6）",
        "required": false
      }
    ],
    "events": [
      {
        "name": "change",
        "params": "(value)",
        "desc": "点加号 / 减号后触发，回传夹到 min~max 的目标值（规格 §30.5）"
      },
      {
        "name": "input",
        "params": "(value)",
        "desc": "editable=true 时值区输入触发，回传原始文本（规格 §30.5）"
      }
    ],
    "slots": [
      {
        "name": "default",
        "desc": "值后面的单位文案（如「件」），渲染在加减号之间（规格 §30.2 unit）"
      }
    ]
  },
  "variantClasses": {
    "size": {
      "default": [],
      "small": [
        ".kole-m-stepper--small"
      ]
    },
    "round": {
      "false": [],
      "true": [
        ".kole-m-stepper--round"
      ]
    }
  },
  "demos": [
    {
      "id": "basic",
      "group": "01 组件类型",
      "title": "基础用法",
      "desc": "减号 / 值 / 加号三段；加减各自是 44px 见方热区。",
      "variant": "size=default"
    },
    {
      "id": "bounds",
      "group": "02 组件状态",
      "title": "边界",
      "desc": "到 min / max 时按钮留在原位置灰而不隐藏：按钮消失会让用户以为界面坏了。",
      "variant": "状态 min|max"
    },
    {
      "id": "size",
      "group": "01 组件类型",
      "title": "圆角两态",
      "desc": "round=true 全圆角用于购物车；round=false 方角嵌在表单里。",
      "variant": "round=false|true"
    },
    {
      "id": "size-small",
      "group": "01 组件类型",
      "title": "紧凑尺寸",
      "desc": "size=small 视觉 36px，热区用 --kole-m-hit-slack 外扩回 44px。",
      "variant": "size=small"
    },
    {
      "id": "disabled",
      "group": "02 组件状态",
      "title": "禁用",
      "desc": "整组置灰、两个按钮都不可聚焦；读屏会播报不可用。",
      "variant": "disabled=true"
    }
  ],
  "related": [
    {
      "slug": "mobile-input",
      "why": "输入范围不固定、也不是整数时用输入框；有界的整数加减用步进器"
    },
    {
      "slug": "mobile-numberkeyboard",
      "why": "数量大到要手打时，输入框配套数字键盘；少量加减直接让步进器承担"
    },
    {
      "slug": "cell",
      "why": "步进器常作为单元格的右侧内容；行结构与点击进下级由单元格负责"
    }
  ]
}