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

{
  "schemaVersion": 1,
  "sourceKind": "authored-spec",
  "provenance": "authored-in-repo",
  "specFile": "spec/移动端规格.md",
  "specSection": "31 · 多行文本框 Textarea",
  "confidence": "high",
  "slug": "mobile-textarea",
  "name": "多行文本框 Textarea",
  "semanticTypeCandidates": [
    "textarea",
    "multiline-input",
    "text-field"
  ],
  "variantDimensions": [
    {
      "name": "size",
      "values": [
        "default",
        "large"
      ]
    },
    {
      "name": "showCounter",
      "values": [
        "false",
        "true"
      ]
    }
  ],
  "representativeVariants": [
    {
      "size": "default",
      "showCounter": "false",
      "label": "默认（最小 3 行，无计数）"
    },
    {
      "size": "default",
      "showCounter": "true",
      "label": "带计数（右下角「已输入/上限」）"
    },
    {
      "size": "large",
      "showCounter": "true",
      "label": "长文本（最小 5 行）+ 计数"
    }
  ],
  "anatomy": {
    "field": "字段容器，包裹文本框、计数行与错误提示",
    "control": "原生 textarea，多行输入，行高不小于 1.5 倍字号",
    "counter": "右下角字数计数（已输入/上限），maxlength>0 时出现",
    "errorText": "字段下方的错误提示文字（与计数同行时计数不消失）",
    "label": "无障碍名称（aria-label），textarea 的初始高度由 rows 决定"
  },
  "structurePatterns": {
    "size": "default（最小高度 3 行）/ large（最小高度 5 行，长文本场景）",
    "showCounter": "false（不显示计数）/ true（右下角显示「已输入/上限」）"
  },
  "usageHints": [
    "收集可能超过一行的自由文本（备注、收货说明、退换原因）",
    "文本框本身要够高（至少 3 行），因为触屏不能像桌面那样在输入过程中看到上下文",
    "要给出实时字数反馈，超限时是「止写 + 报错」而不是静默截断",
    "只允许纵向伸缩（resize: vertical），不允许横向拉宽破坏 375 宽的布局",
    "不使用自动增高（高度随内容跳动会让上下文错位），需要更长文本时用 size=large"
  ],
  "doNotInvent": [
    "自动增高（随内容撑高）的实现细节",
    "富文本 / Markdown 的编辑与渲染",
    "内容敏感词过滤与提交前的业务校验"
  ],
  "unknowns": [
    "maxlength 缺省时上限取多少（本实现默认 200）",
    "是否需要在接近上限时提前变色（本实现只在到达上限时变色）",
    "计数是否包含空格与换行"
  ],
  "interaction": [
    "文本框最小高度 3 行（约 88px）；只允许纵向伸缩（resize: vertical），不允许横向拉宽破坏 375 宽的布局",
    "计数随输入实时更新；达到上限时计数置错误色并停止接收新字符（原生 maxlength 兜底，超限靠宿主提示）",
    "文本框整体可点即聚焦（外层不出可点装饰）；错误提示与计数都在框外，不挤占输入区",
    "聚焦反馈是边框色 + 2px 外发光，150ms 过渡；不改变高度",
    "不使用自动增高（高度随内容跳动会让上下文错位），需要更长文本时用 size=large"
  ],
  "accessibility": [
    "控件是原生 textarea，名称由 aria-label 给出（占位文字不算标签）",
    "错误态用 aria-invalid=\"true\" + aria-describedby 关联错误文案",
    "计数是参考信息，用 aria-live=\"polite\" 播报（不要每敲一个字都播报，只在接近上限时提示）",
    "禁用态用原生 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": "受控文本；长度决定计数与 is-full（规格 §31.5）",
        "required": false
      },
      {
        "name": "size",
        "type": "'default' | 'large'",
        "default": "'default'",
        "desc": "变体 size：default 最小 3 行，large 最小 5 行（规格 §31.3）",
        "required": false
      },
      {
        "name": "placeholder",
        "type": "string",
        "default": "''",
        "desc": "占位文字；它不算标签，标签由 label 给出（规格 §31.6）",
        "required": false
      },
      {
        "name": "maxlength",
        "type": "number",
        "default": "200",
        "desc": "字数上限；0 表示不限。到上限时计数转错误色并停止接收（规格 §31.5）",
        "required": false
      },
      {
        "name": "showCounter",
        "type": "boolean",
        "default": "false",
        "desc": "变体 showCounter：右下角是否显示「已输入/上限」（规格 §31.3）",
        "required": false
      },
      {
        "name": "disabled",
        "type": "boolean",
        "default": "false",
        "desc": "状态 disabled：置灰且不可聚焦（规格 §31.4）",
        "required": false
      },
      {
        "name": "error",
        "type": "string",
        "default": "''",
        "desc": "状态 error：错误文案，非空时写 aria-invalid 并显示在框外下方（规格 §31.6）",
        "required": false
      },
      {
        "name": "label",
        "type": "string",
        "default": "'多行文本'",
        "desc": "无障碍名称，落到 aria-label（规格 §31.6）",
        "required": false
      },
      {
        "name": "rows",
        "type": "number",
        "default": "3",
        "desc": "textarea 的初始行数（规格 §31.2 label 行）",
        "required": false
      }
    ],
    "events": [
      {
        "name": "input",
        "params": "(value)",
        "desc": "输入时触发，回传当前文本（计数与 is-full 由此派生）（规格 §31.5）"
      }
    ],
    "slots": [
      {
        "name": "default",
        "desc": "文本框下方的追加内容（如提示语），排在计数行之后（规格 §31.2 field）"
      }
    ]
  },
  "variantClasses": {
    "size": {
      "default": [],
      "large": [
        ".kole-m-textarea--large"
      ]
    },
    "showCounter": {
      "false": [],
      "true": [
        ".kole-m-textarea__counter"
      ]
    }
  },
  "demos": [
    {
      "id": "basic",
      "group": "01 组件类型",
      "title": "基础用法",
      "desc": "最小高度 3 行：触屏上不能像桌面那样看到输入上下文。",
      "variant": "size=default"
    },
    {
      "id": "counter",
      "group": "01 组件类型",
      "title": "带计数",
      "desc": "showCounter=true：计数随输入实时更新；点「填到上限」可看到 is-full 形态。",
      "variant": "showCounter=true"
    },
    {
      "id": "full",
      "group": "02 组件状态",
      "title": "到达上限",
      "desc": "is-full：计数变错误色并停止接收新字符，不静默截断。",
      "variant": "状态 full"
    },
    {
      "id": "size",
      "group": "01 组件类型",
      "title": "尺寸两档",
      "desc": "default 最小 3 行；large 最小 5 行。两者都只允许纵向拉伸。",
      "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-input",
      "why": "内容只占一行时用输入框；可能超过一行（备注、说明）时用多行文本框"
    },
    {
      "slug": "mobile-numberkeyboard",
      "why": "金额、验证码这类数字内容配数字键盘；自由文本用多行文本框，无需自定义键盘"
    },
    {
      "slug": "mobile-dialog",
      "why": "长文本要在提交前整体确认时用对话框，把多行文本框放进对话框内容区"
    }
  ]
}