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

{
  "schemaVersion": 1,
  "sourceKind": "authored-spec",
  "provenance": "authored-in-repo",
  "specFile": "spec/移动端规格.md",
  "specSection": "36 · 评分 Rate",
  "confidence": "high",
  "slug": "mobile-rate",
  "name": "评分 Rate",
  "semanticTypeCandidates": [
    "rate",
    "star-rating",
    "score-input"
  ],
  "variantDimensions": [
    {
      "name": "size",
      "values": [
        "default",
        "small"
      ]
    },
    {
      "name": "allowHalf",
      "values": [
        "false",
        "true"
      ]
    },
    {
      "name": "readonly",
      "values": [
        "false",
        "true"
      ]
    }
  ],
  "representativeVariants": [
    {
      "size": "default",
      "allowHalf": "false",
      "readonly": "false",
      "label": "默认（整星可评分，星形 24px）"
    },
    {
      "size": "default",
      "allowHalf": "true",
      "readonly": "false",
      "label": "支持半星（点左半取 N-0.5 分）"
    },
    {
      "size": "small",
      "allowHalf": "false",
      "readonly": "true",
      "label": "行内只读展示（星形 18px，不占键盘序列）"
    }
  ],
  "anatomy": {
    "rate": "根元素，一行里放进「星组 + 数值文案」",
    "stars": "星组，横向排列，只负责布局",
    "star": "单颗星，可点区域（原生 button），自身撑满 44px 高",
    "glyph": "星形本体（视觉 24px），由灰底星 + 品牌色覆盖层叠成",
    "fill": "覆盖层，宽度即该颗星的填充比例（100% 整星 / 50% 半星 / 0% 未选）",
    "text": "数值文案，默认「N 分」，可由默认插槽替换"
  },
  "structurePatterns": {
    "size": "default（星形 24px）/ small（星形 18px，行内展示用）",
    "allowHalf": "false（只能取整星）/ true（允许半星）",
    "readonly": "false（可评分）/ true（只读展示已有评分）"
  },
  "usageHints": [
    "让用户对一次体验给出星级评价（商品、物流、服务），或只读展示已有的平均分",
    "触屏上没有悬停预览：桌面上鼠标划过就能预告「点下去会是几分」，触屏上这个预告不存在",
    "填充比例（含半星）必须直接可读，且星形本体只有 24px、热区要补到 44px 高",
    "点第 N 颗星取 N 分；allowHalf=true 时点第 N 颗星的左半取 N-0.5 分、右半取 N 分",
    "取值后立即触发 change 事件（回传 3.5 这类半星值也是合法输入）"
  ],
  "doNotInvent": [
    "评分的业务含义映射（如「4 分以上算好评」）与统计口径",
    "拖动选分与悬停预览（触屏没有悬停，拖动容易滑错）",
    "评分理由 / 标签的联动采集（由宿主另行组合）",
    "异步提交与失败回滚（宿主负责）"
  ],
  "unknowns": [
    "分值是否允许与文案一一对应（如 1 分「很差」、5 分「很好」）",
    "星形换用图标字体或 SVG 后填充比例的表达是否仍然一致",
    "只读形态是否要显示评价条数（当前由宿主用插槽补）"
  ],
  "interaction": [
    "**取值规则**：点第 N 颗星取 N 分；allowHalf=true 时点第 N 颗星的**左半**取 N-0.5 分、**右半**取 N 分（半星只在开启该项时存在，默认整星）",
    "星形本体视觉 24px（size=small 时 18px），但每颗星的可点区域高度是 44px；横向不做死区，相邻星的边界就是两半分界",
    "一次触摸即取值，不需要二次确认；不响应长按与拖动（拖动选分在触屏上容易滑错，规格未纳入）",
    "已选中的部分用**填充比例**表达（半星就是左半填充），不能只靠颜色深浅区分",
    "取值后立即触发 change 事件（回传 3.5 这类半星值也是合法输入）",
    "readonly=true 时不渲染任何可点区域（只读展示不抢键盘序列）"
  ],
  "accessibility": [
    "可评分形态：根是 role=\"radiogroup\" + aria-label，每颗星是原生 button + role=\"radio\" + aria-checked",
    "星形的名称是「N 星」（aria-label），读屏播报的是分值而不是符号",
    "只读形态：整组是一个 role=\"img\" + aria-label（「评分 4.5 分（满分 5 分）」），组内星形 aria-hidden",
    "禁用态用原生 disabled 并补 aria-disabled=\"true\"",
    "键盘：聚焦后左右方向键步进（整星模式步长 1，半星模式步长 0.5）"
  ],
  "api": {
    "source": "implementation",
    "note": "props / events / slots 为 6 端实现的公共接口（说明文字取自规格对应小节）。字段名与各端源码逐名核对：node tools/verify-mobile-docs.mjs",
    "requiredNote": "「必传」按严格定义：实现里**没有默认值**时才为 Y（本门禁逐条核对 props 与各端源码的默认值，防止契约与实现脱节）。",
    "props": [
      {
        "name": "value",
        "type": "number",
        "default": "0",
        "desc": "受控分值，允许半星（3.5）与 0（未评分）（规格 §36.5）",
        "required": false
      },
      {
        "name": "max",
        "type": "number",
        "default": "5",
        "desc": "满分星数，决定渲染几颗星（规格 §36.2 stars）",
        "required": false
      },
      {
        "name": "allowHalf",
        "type": "boolean",
        "default": "false",
        "desc": "变体 allowHalf：是否允许半星（点左半取 N-0.5 分）（规格 §36.3）",
        "required": false
      },
      {
        "name": "size",
        "type": "'default' | 'small'",
        "default": "'default'",
        "desc": "变体 size：星形 24px 还是 18px（行内展示用）（规格 §36.3）",
        "required": false
      },
      {
        "name": "readonly",
        "type": "boolean",
        "default": "false",
        "desc": "变体 readonly：只读展示（不渲染可点区域，整组用 role=\"img\" 播报）（规格 §36.3）",
        "required": false
      },
      {
        "name": "disabled",
        "type": "boolean",
        "default": "false",
        "desc": "状态 disabled：置灰且不可聚焦，点击不改值（规格 §36.4）",
        "required": false
      },
      {
        "name": "label",
        "type": "string",
        "default": "'评分'",
        "desc": "无障碍名称，落到 radiogroup / img 的 aria-label（规格 §36.6）",
        "required": false
      }
    ],
    "events": [
      {
        "name": "change",
        "params": "(value)",
        "desc": "点星或键盘步进改值时触发，回传新分值（可含 0.5）（规格 §36.5）"
      }
    ],
    "slots": [
      {
        "name": "default",
        "desc": "数值文案位置的自定义内容（如「4.5 分 · 共 128 条评价」），替换默认的「N 分」（规格 §36.2 text）"
      }
    ]
  },
  "variantClasses": {
    "size": {
      "default": [],
      "small": [
        ".kole-m-rate--small"
      ]
    },
    "allowHalf": {
      "false": [],
      "true": [
        ".kole-m-rate--half",
        ".kole-m-rate__half"
      ]
    },
    "readonly": {
      "false": [],
      "true": [
        ".kole-m-rate--readonly"
      ]
    }
  },
  "demos": [
    {
      "id": "basic",
      "group": "01 组件类型",
      "title": "基础用法",
      "desc": "点第 N 颗即取 N 分；整行 44px 高，星形本体只有 24px。",
      "variant": "allowHalf=false"
    },
    {
      "id": "half",
      "group": "01 组件类型",
      "title": "半星",
      "desc": "allowHalf=true：点某颗星的左半取 N-0.5 分、右半取 N 分。",
      "variant": "allowHalf=true"
    },
    {
      "id": "size",
      "group": "01 组件类型",
      "title": "尺寸两档",
      "desc": "size=small 星形 18px 用于行内展示；default 24px 用于可评分场景。",
      "variant": "size=default|small"
    },
    {
      "id": "readonly",
      "group": "02 组件状态",
      "title": "只读展示",
      "desc": "readonly=true：星形不再是按钮、点击不改值，整组用 role=\"img\" 播报分值。",
      "variant": "readonly=true"
    },
    {
      "id": "disabled",
      "group": "02 组件状态",
      "title": "禁用",
      "desc": "整条置灰且不可聚焦：读屏会播报不可用，点击不改值。",
      "variant": "disabled=true"
    }
  ],
  "related": [
    {
      "slug": "mobile-slider",
      "why": "连续区间的粗选用 Slider；离散档位（1~5 星）且带语义的用 Rate"
    },
    {
      "slug": "mobile-form",
      "why": "评分作为表单里的一个字段时，标签、必填星号与错误提示由 Form 的 item 提供"
    },
    {
      "slug": "mobile-tag",
      "why": "只是标注一个既有结论（如「好评」「差评」）用 Tag；需要用户给出分值时用 Rate"
    }
  ]
}