113 lines
5.1 KiB
JSON
113 lines
5.1 KiB
JSON
{
|
||
"slug": "rate",
|
||
"end": "react",
|
||
"curated": true,
|
||
"summary": "评分：分数走 value/defaultValue，allowHalf 等为 props，变化回调 onChange。",
|
||
"usage": [
|
||
"React 端分值逻辑是「传 value 受控、传 defaultValue 非受控」的唯一分流点（Rate.jsx:33）。",
|
||
"半星不靠拆图标，而是每个星内部再叠一层宽度百分比填充：stars 数组算出每颗星的填充比例（Rate.jsx:35,55）。",
|
||
"半星判定用鼠标位置：allowHalf 时按 getBoundingClientRect 判断是否落在左半边像素（Rate.jsx:41-45）。",
|
||
"重复点击同一分值会归零：next === current 时置 0（Rate.jsx:46），是组件内建的行为而不是父组件判断。",
|
||
"文案由数值反查 texts 数组，showText 为真才渲染（Rate.jsx:36,58）；尺寸用 size=\"sm\" | \"lg\" 拼到根类名上（Rate.jsx:52）。"
|
||
],
|
||
"bestPractices": [
|
||
"只读展示用 readonly，不要用 disabled：两者都阻止交互，但 readonly 有独立的 is-readonly 类供样式区分（Rate.jsx:39,52）。",
|
||
"texts 长度要与 count 对齐，反查下标是 Math.ceil(current) - 1，长度不足会取到 undefined（Rate.jsx:36）。",
|
||
"需要「点击后归零」以外的清空策略请在父级处理 onChange 的 0 值，组件不提供独立清空入口。"
|
||
],
|
||
"apiCarrier": {
|
||
"kind": "props",
|
||
"note": "React 端的 API 载体是 props 与回调：属性驱动外观（type/size/disabled 等布尔与枚举），交互经 onXxx 回传（如 onChange/onClick/onSelectionChange）；没有 v-model，受控组件固定写成 value + onChange，非受控则用 defaultValue。",
|
||
"table": [
|
||
{
|
||
"name": "value",
|
||
"type": "number",
|
||
"desc": "受控分值"
|
||
},
|
||
{
|
||
"name": "defaultValue",
|
||
"type": "number",
|
||
"desc": "非受控初始分值"
|
||
},
|
||
{
|
||
"name": "count",
|
||
"type": "number",
|
||
"desc": "星星数量，默认 5"
|
||
},
|
||
{
|
||
"name": "allowHalf",
|
||
"type": "boolean",
|
||
"desc": "允许半星，按点击位置在星的左右半边判定"
|
||
},
|
||
{
|
||
"name": "readonly",
|
||
"type": "boolean",
|
||
"desc": "只读，不响应点击"
|
||
},
|
||
{
|
||
"name": "disabled",
|
||
"type": "boolean",
|
||
"desc": "禁用"
|
||
},
|
||
{
|
||
"name": "size",
|
||
"type": "'default' | 'sm' | 'lg'",
|
||
"desc": "尺寸，非 default 时追加到根类名"
|
||
},
|
||
{
|
||
"name": "showText",
|
||
"type": "boolean",
|
||
"desc": "是否显示评分文案"
|
||
},
|
||
{
|
||
"name": "texts",
|
||
"type": "string[]",
|
||
"desc": "文案数组，按分值取下标"
|
||
},
|
||
{
|
||
"name": "onChange",
|
||
"type": "(value) => void",
|
||
"desc": "分值变化回调，重复点击同分回传 0"
|
||
}
|
||
]
|
||
},
|
||
"a11y": [
|
||
"每颗星是带 onClick 的 span（Rate.jsx:54），不是可聚焦控件，键盘用户无法评分。",
|
||
"没有 role=\"slider\"/\"radiogroup\" 或 aria-valuenow，读屏读不出当前分值。",
|
||
"只读态建议在业务侧补一段可见文本（如「4.5 分」），因为 showText 只覆盖文案而不暴露数值语义。"
|
||
],
|
||
"resources": [
|
||
{
|
||
"file": "frameworks/Rate.jsx",
|
||
"kind": "React（React）",
|
||
"desc": "React 端组件实现源码，props 与回调的唯一定义处"
|
||
},
|
||
{
|
||
"file": "frameworks/Rate.css",
|
||
"kind": "样式",
|
||
"desc": "该 React 实现依赖的样式文件"
|
||
}
|
||
],
|
||
"exampleIds": [
|
||
"rate-ex-1",
|
||
"rate-ex-2",
|
||
"rate-ex-3",
|
||
"rate-ex-4"
|
||
],
|
||
"notes": [
|
||
"frameworks/Rate.jsx:9 中可指到 value（number）——受控分值",
|
||
"frameworks/Rate.jsx:9 中可指到 defaultValue（number）——非受控初始分值",
|
||
"frameworks/Rate.jsx:10 中可指到 count（number）——星星数量，默认 5",
|
||
"frameworks/Rate.jsx:11 中可指到 allowHalf（boolean）——允许半星，按点击位置在星的左右半边判定",
|
||
"frameworks/Rate.jsx:12 中可指到 readonly（boolean）——只读，不响应点击",
|
||
"frameworks/Rate.jsx:12 中可指到 disabled（boolean）——禁用",
|
||
"frameworks/Rate.jsx:13 中可指到 size（'default' | 'sm' | 'lg'）——尺寸，非 default 时追加到根类名",
|
||
"frameworks/Rate.jsx:14 中可指到 showText（boolean）——是否显示评分文案",
|
||
"frameworks/Rate.jsx:15 中可指到 texts（string[]）——文案数组，按分值取下标",
|
||
"frameworks/Rate.jsx:16 中可指到 onChange（(value) => void）——分值变化回调，重复点击同分回传 0",
|
||
"props 解构清单见 frameworks/Rate.jsx:20-31；本文件 table 只列该端真正消费的属性与回调。",
|
||
"过滤口径：事实包 consumedApi 里还包含绑在组件内部节点上的同名处理器（如 onClick/onChange 绑在内部 button、input、checkbox 上，见 frameworks/Rate.jsx 全文），它们不是对外 props，因此未进 table。",
|
||
"table 构成核验：10 行中 10 行是 frameworks/Rate.jsx 解构出的顶层 props（解构块 frameworks/Rate.jsx:20-31）；本组件 table 全部为顶层 props。"
|
||
]
|
||
}
|