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

{
  "schemaVersion": 1,
  "sourceKind": "authored-spec",
  "provenance": "authored-in-repo",
  "specFile": "spec/移动端规格.md",
  "specSection": "27 · 输入框 Input",
  "confidence": "high",
  "slug": "mobile-input",
  "name": "输入框 Input",
  "semanticTypeCandidates": [
    "input",
    "text-field",
    "form-control"
  ],
  "variantDimensions": [
    {
      "name": "size",
      "values": [
        "default",
        "large"
      ]
    },
    {
      "name": "clearable",
      "values": [
        "false",
        "true"
      ]
    }
  ],
  "representativeVariants": [
    {
      "size": "default",
      "clearable": "false",
      "label": "默认输入框（44px，一行一字段）"
    },
    {
      "size": "large",
      "clearable": "false",
      "label": "大尺寸（52px，单字段成组）"
    },
    {
      "size": "default",
      "clearable": "true",
      "label": "可清除（有值时出现清除按钮）"
    }
  ],
  "anatomy": {
    "field": "字段容器，包裹输入框与下方错误提示（错误提示在框外，不挤占输入区）",
    "control": "原生 input，占满剩余宽度，字号 16px",
    "prefix": "可选前缀，放单位或符号（如「¥」）",
    "clear": "可选清除按钮，有值且 clearable=true 时出现在右侧",
    "suffix": "可选后缀，由默认插槽给出的自定义内容（单位、显示密码等）",
    "errorText": "字段下方的错误提示文字"
  },
  "structurePatterns": {
    "size": "default（高度 44px）/ large（高度 52px）",
    "clearable": "false（无清除按钮）/ true（有值时右侧出现清除按钮）"
  },
  "usageHints": [
    "在一行内收集单行文本（姓名、手机号、金额、验证码等）",
    "移动端输入框整行占满、高度不小于 44px，字号不小于 16px，否则 iOS 聚焦时会自动放大页面",
    "清除动作必须在框内完成，因为触屏没有悬停的鼠标可以移开",
    "键盘「完成」键触发 confirm 事件，值随 input 事件实时回传",
    "错误说明放在框外下方，不挤占输入区"
  ],
  "doNotInvent": [
    "输入内容的正则与业务校验（合法性判断在宿主）",
    "inputmode 之外的自定义软键盘行为（键盘类型由宿主按场景指定）",
    "自动填充与验证码自动读取的策略"
  ],
  "unknowns": [
    "密码是否需要内置「显示/隐藏」开关",
    "数字输入的千分位格式化时机",
    "前缀里是否允许放图片/图标"
  ],
  "interaction": [
    "输入框高度不小于 44px；整行可点（把 .kole-m-input 放在 label 里，点行即聚焦）",
    "清除按钮视觉是 16px 图标，热区外扩到 44px 最小触控边长",
    "聚焦反馈是边框色 + 2px 外发光，150ms 过渡；不改变布局（不撑开高度）",
    "有值时清除按钮才出现；清除后焦点留在输入框",
    "键盘「完成」键触发 confirm 事件，值随 input 事件实时回传"
  ],
  "accessibility": [
    "输入框用原生 input，名称由 aria-label 给出（占位文字不算标签）",
    "错误态用 aria-invalid=\"true\"，错误文案用 aria-describedby 关联",
    "清除按钮是原生 button 且带 aria-label=\"清除\"",
    "禁用态用原生 disabled，读屏会跳过"
  ],
  "api": {
    "source": "implementation",
    "note": "props / events / slots 为 6 端实现的公共接口（说明文字取自规格对应小节）。字段名与各端源码逐名核对：node tools/verify-mobile-docs.mjs",
    "requiredNote": "「必传」按严格定义：实现里**没有默认值**时才为 Y（本门禁逐条核对 props 与各端源码的默认值，防止契约与实现脱节）。",
    "props": [
      {
        "name": "value",
        "type": "string",
        "default": "''",
        "desc": "受控值；有值时右侧才出现清除按钮（规格 §27.5）",
        "required": false
      },
      {
        "name": "size",
        "type": "'default' | 'large'",
        "default": "'default'",
        "desc": "变体 size：default 高 44px，large 高 52px（规格 §27.3）",
        "required": false
      },
      {
        "name": "placeholder",
        "type": "string",
        "default": "''",
        "desc": "占位文字；它不算标签，标签由 label 给出（规格 §27.6）",
        "required": false
      },
      {
        "name": "prefix",
        "type": "string",
        "default": "''",
        "desc": "可选前缀，放单位或符号（规格 §27.2 prefix）",
        "required": false
      },
      {
        "name": "clearable",
        "type": "boolean",
        "default": "false",
        "desc": "变体 clearable：有值时显示清除按钮（规格 §27.3）",
        "required": false
      },
      {
        "name": "disabled",
        "type": "boolean",
        "default": "false",
        "desc": "状态 disabled：置灰且不可聚焦（规格 §27.4）",
        "required": false
      },
      {
        "name": "error",
        "type": "string",
        "default": "''",
        "desc": "状态 error：错误文案，非空时写 aria-invalid 并在框外下方显示（规格 §27.6）",
        "required": false
      },
      {
        "name": "label",
        "type": "string",
        "default": "'输入框'",
        "desc": "无障碍名称，落到 aria-label（规格 §27.6）",
        "required": false
      }
    ],
    "events": [
      {
        "name": "input",
        "params": "(value)",
        "desc": "输入时触发，回传当前值（规格 §27.5）"
      },
      {
        "name": "confirm",
        "params": "(value)",
        "desc": "键盘「完成」键触发（规格 §27.5）"
      },
      {
        "name": "clear",
        "params": "—",
        "desc": "点击清除按钮触发，值由宿主置空（规格 §27.5）"
      }
    ],
    "slots": [
      {
        "name": "default",
        "desc": "框内右侧自定义内容（后缀：单位、显示密码等，规格 §27.2 suffix）"
      }
    ]
  },
  "variantClasses": {
    "size": {
      "default": [],
      "large": [
        ".kole-m-input--large"
      ]
    },
    "clearable": {
      "false": [],
      "true": [
        ".kole-m-input__clear"
      ]
    }
  },
  "demos": [
    {
      "id": "basic",
      "group": "01 组件类型",
      "title": "基础用法",
      "desc": "默认高度 44px、字号 16px：iOS 聚焦时不会自动放大页面。",
      "variant": "size=default"
    },
    {
      "id": "prefix",
      "group": "01 组件类型",
      "title": "带前缀",
      "desc": "单位写在框内，避免占位符里重复出现（前缀对读屏隐藏，语义由 label 承担）。",
      "variant": "prefix"
    },
    {
      "id": "clearable",
      "group": "01 组件类型",
      "title": "可清除",
      "desc": "有值时右侧出现清除按钮；点它清空并把焦点交还输入框。",
      "variant": "clearable=true"
    },
    {
      "id": "size",
      "group": "01 组件类型",
      "title": "尺寸两档",
      "desc": "default 44px 用于表单内多字段；large 52px 用于一行一字段。",
      "variant": "size=default|large"
    },
    {
      "id": "error",
      "group": "02 组件状态",
      "title": "错误态",
      "desc": "is-error 边框变错误色，aria-invalid 置位，错误说明在框外下方。",
      "variant": "状态 error"
    },
    {
      "id": "disabled",
      "group": "02 组件状态",
      "title": "禁用",
      "desc": "整框置灰、输入区不可聚焦，读屏会跳过。",
      "variant": "disabled=true"
    }
  ],
  "related": [
    {
      "slug": "mobile-search",
      "why": "输入的目的是搜索时用搜索框（自带搜索图标与清除）；普通文本收集用输入框"
    },
    {
      "slug": "mobile-textarea",
      "why": "内容可能超过一行时用多行文本框；单行文本用输入框"
    },
    {
      "slug": "mobile-numberkeyboard",
      "why": "金额/验证码等需要自定义键盘时，输入框配套数字键盘；键盘只回传按键，写入仍由宿主完成"
    }
  ]
}