SepRate 评分组件 v1.2.0
星级评分 · count 数量 · allowHalf 半星 · value/defaultValue 受控与非受控 · disabled 禁用 · readonly 只读 · clearable 可清除 · character 自定义字符 · activeCharacter/voidCharacter 双图标 · color 自定义颜色 · colors 分级配色 · showText 常驻文字 · showScore 分值显示 · voidColor 未选中色 · gutter 间距 · precision 精度 · animation 入场动画 · direction 布局方向 · tooltips 文字提示 · size 尺寸 · onChange/onHoverChange 回调 · 键盘导航(←→/Home/End) · 触摸事件支持 · aria 无障碍
1. 基础用法
HTML 声明式标签
JS API 初始化
当前值：
3
2. 半星 allowHalf
HTML 声明式标签
JS API 初始化
当前值：
2.5
3. 数量 count
HTML 声明式标签
JS API 初始化
4. 禁用 / 只读
HTML 声明式标签
disabled
readonly
JS API 初始化
5. 可清除 clearable（再次点击已选项清除）
HTML 声明式标签
JS API 初始化
当前值：
3
6. 自定义字符 character
HTML 声明式标签
字符 A
图标 #heartFill
JS API 初始化
双图标自定义 activeCharacter + voidCharacter
7. 自定义颜色 color
HTML 声明式标签
JS API 初始化
8. 文字提示 tooltips
HTML 声明式标签
JS API 初始化
hover 值：
-
hover 文案：
-
9. 尺寸 size（small / middle / large）
HTML 声明式标签
JS API 初始化
10. 受控模式 value
JS API 初始化
11. API 交互测试
JS API 初始化
状态：
-
12. 键盘导航（← → Home End）
JS API 初始化
当前值：
0
13. 分级配色 colors（根据分值自动变色）
JS API 初始化
当前值：
3
14. 常驻文字 showText + texts
JS API 初始化
15. 分值显示 showScore + scoreTemplate + scorePrecision
JS API 初始化
16. 未选中色 voidColor + 间距 gutter
JS API 初始化
17. 精度 precision（支持 0.1 步进）
JS API 初始化
当前值：
3.5
18. 入场动画 animation（逐个点亮 + 呼吸光晕）
JS API 初始化
19. 垂直布局 direction: 'vertical'
JS API 初始化
详细说明
SepRate 星级评分组件，支持半星、自定义数量/字符/颜色、文字提示、禁用/只读、可清除、受控模式、键盘导航与无障碍，适用于商品评价、满意度调查、内容打分等场景。
Props 配置项
| 参数 | 类型 | 默认值 | 说明 |
|---|---|---|---|
| value | number | - | 当前分值（受控模式），与 defaultValue 二选一 |
| defaultValue | number | 0 | 默认分值（非受控模式） |
| count | number | 5 | 星标总数 |
| allowHalf | boolean | false | 是否允许半星 |
| disabled | boolean | false | 是否禁用，禁用态显示 cursor: not-allowed |
| readonly | boolean | false | 是否只读，不可交互但保留选中态样式 |
| clearable | boolean | false | 是否可通过再次点击当前星清除分值 |
| character | string | '★' | 自定义字符，支持 'A' 文本或 '#heartFill' 图标 key |
| activeCharacter | string | 同 character | 选中态图标，未设置时回退到 character |
| voidCharacter | string | 同 character | 未选中态图标，未设置时回退到 character |
| color | string | --warning | 自定义选中色，如 '#52c41a'，优先级高于 colors |
| colors | string[] | [] | 分级配色数组，按分值区间取色，如 ['#F53F3F','#FF7D00','#F7BA1E','#00B42A','#0FC6C2'] |
| showText | boolean | false | 是否常驻显示评分文字 |
| texts | string[] | [] | 评分文字数组，与分值区间对应，如 ['极差','失望','一般','满意','惊喜'] |
| showScore | boolean | false | 是否显示分值数字 |
| scoreTemplate | string | '' | 分值模板，支持 {value} 和 {total}，如 '{value}/{total}' |
| scorePrecision | number | -1 | 分值小数位数，-1 表示按原值显示，如 2 则 3.5 显示为 3.50 |
| voidColor | string | '' | 未选中星的颜色 |
| gutter | number | -1 | 星标间距（px），-1 表示使用默认间距 |
| precision | number | 1 | 精度步进，如 0.1 支持十分位评分，allowHalf 优先 |
| animation | boolean | true | 是否启入场动画（星星逐个弹跳点亮 + 选中星呼吸光晕） |
| direction | 'horizontal'|'vertical' | 'horizontal' | 布局方向，垂直模式下星星纵向排列 |
| tooltips | string[] | - | 每颗星对应的 hover 文字提示数组 |
| size | 'small'|'middle'|'large' | 'middle' | 尺寸 |
Methods 方法
| 方法 | 参数 | 返回 | 说明 |
|---|---|---|---|
| getValue() | - | number | 获取当前分值 |
| setValue(v) | number | void | 设置分值 |
| getCount() / setCount(n) | number | number / void | 星标总数读写 |
| isAllowHalf() / setAllowHalf(b) | boolean | boolean / void | 半星模式读写 |
| isDisabled() / setDisabled(b) | boolean | boolean / void | 禁用态读写 |
| isReadonly() / setReadonly(b) | boolean | boolean / void | 只读态读写 |
| isClearable() | - | boolean | 是否可清除 |
| clear() | - | void | 清空分值为 0 |
| getCharacter() / setCharacter(c) | string | string / void | 自定义字符读写 |
| getActiveCharacter() / setActiveCharacter(c) | string | string / void | 选中态图标读写 |
| getVoidCharacter() / setVoidCharacter(c) | string | string / void | 未选中态图标读写 |
| getColor() / setColor(c) | string | string / void | 选中色读写 |
| getColors() / setColors(arr) | string[] | string[] / void | 分级配色读写 |
| isShowText() / setShowText(b) | boolean | boolean / void | 常驻文字开关 |
| getTexts() / setTexts(arr) | string[] | string[] / void | 评分文字读写 |
| isShowScore() / setShowScore(b) | boolean | boolean / void | 分值显示开关 |
| getScoreTemplate() / setScoreTemplate(s) | string | string / void | 分值模板读写 |
| getScorePrecision() / setScorePrecision(n) | number | number / void | 分值小数位数读写 |
| getVoidColor() / setVoidColor(c) | string | string / void | 未选中色读写 |
| getGutter() / setGutter(n) | number | number / void | 星标间距读写 |
| getPrecision() / setPrecision(n) | number | number / void | 精度步进读写 |
| isAnimation() / setAnimation(b) | boolean | boolean / void | 入场动画开关 |
| getDirection() / setDirection(v) | string | string / void | 布局方向读写（'horizontal' / 'vertical'） |
| getTooltips() / getSize() | - | - | 获取对应配置 |
| getState() | - | object | 获取完整状态快照 |
| subscribe(fn) | function | unsub | 订阅状态变更 |
| destroy() | - | void | 销毁实例，清空 DOM 与事件 |
Events 事件
| 事件 | 回调参数 | 说明 |
|---|---|---|
| onChange | (value: number) | 分值变化时触发 |
| onHoverChange | (value: number) | 悬停分值变化时触发，配合 tooltips 显示提示文字 |