Ant Design Rate 评分组件完全指南API、示例与 Design Token 定制【免费下载链接】ant-designAn enterprise-class UI design language and React UI library项目地址: https://gitcode.com/GitHub_Trending/an/ant-designRate评分是 ant-design 组件库中数据录入Data Entry系列的核心组件用于对事物进行展示评价与快速评级操作。本文以 components/rate/index.en-US.md 为骨架结合组件源码、样式 Token 定义与官方 demo系统讲解 Rate 的全部 API 属性、受控/非受控用法、半星与自定义字符能力、无障碍键盘操作以及通过 ConfigProvider 主题定制星星颜色与尺寸的进阶方案。阅读完你将能在项目中熟练使用 Rate 并完成贴合业务的自定义样式。When To Use使用场景根据组件官方文档Rate 主要应用于两类场景展示评价Show evaluation以星级直观展示历史评分结果例如商品评分、课程评分、服务满意度等场景此时通常配合disabled只读模式。快速评级操作A quick rating operation允许用户在评分区域快速点选例如问卷打分、内容投票此时需要监听onChange回调获取结果。Rate 常被归入表单字段使用因此它也完整支持onFocus、onBlur、onKeyDown等交互回调以及focus()、blur()实例方法可无缝嵌入 Form 校验体系。API 一览Rate 的所有属性均不支持通过 ConfigProvider 组件级配置Global Config 一列为 ×即这些配置只能在使用处通过 props 传入。完整属性表如下源自官方文档PropertyDescriptionTypeDefaultVersionallowClearWhether to allow clear when click againbooleantrueallowHalfWhether to allow semi selectionbooleanfalsecharacterThe custom character of rateReactNode | (RateProps) ReactNodeStarFilled /function(): 4.4.0countStar countnumber5defaultValueThe default valuenumber0disabledIf read only, unable to interactbooleanfalsekeyboardSupport keyboard operationbooleantrue5.18.0sizeStar sizesmall | medium | largemediumtooltipsCustomize tooltip by each characterTooltipProps[] | string[]-valueThe current valuenumber-onBlurCallback when component lose focusfunction()-onChangeCallback when select valuefunction(value: number)-onFocusCallback when component get focusfunction()-onHoverChangeCallback when hover itemfunction(value: number)-onKeyDownCallback when keydown on componentfunction(event)-几个需要特别注意的属性语义value与defaultValue同时提供valueonChange时组件进入受控模式值由外部驱动只提供defaultValue时为非受控模式。二者默认值均为 0即初始无任何星星点亮。allowHalf允许半选选中值可为0.5的倍数例如2.5。allowClear默认true即当再次点击当前已选中的星星时可清除为 0。该行为与allowHalf相互独立。keyboard自 5.18.0 起默认开启支持键盘方向键改变分值在无障碍a11y场景下这是 Rate 可聚焦、可操作的关键保证。character自 4.4.0 起支持传入函数形式函数入参包含当前星星的index可针对每个位置动态返回不同字符。此外 Rate 也支持组件通用属性例如className、style、rootClassName与prefixCls其中 rootClassName / 通用属性 的语义与其他组件一致。Methods实例方法组件通过React.forwardRef暴露实例可通过 ref 调用以下方法详见 index.tsx 中的RateRef类型定义NameDescriptionblur()Remove focusfocus()Get focus使用示例import React, { useRef } from react; import { Button, Rate } from antd; import type { RateRef } from antd/es/rate; // 或从组件类型中提取 const App: React.FC () { const rateRef useRefRateRef(null); return ( Rate ref{rateRef} defaultValue{3} / Button onClick{() rateRef.current?.focus()}聚焦/Button Button onClick{() rateRef.current?.blur()}失焦/Button / ); };基础用法与常见场景基本评分最小用法仅需一行代码参考 basic.tsx默认渲染 5 颗星import React from react; import { Rate } from antd; const App: React.FC () Rate /; export default App;三种尺寸size支持small | medium | large三档默认medium该 demo 自 6.0.0 加入见 size.tsximport React from react; import { Flex, Rate } from antd; const App: React.FC () ( Flex vertical gapmedium Rate sizelarge / Rate / Rate sizesmall / /Flex );尺寸不只会影响视觉源码中是通过在根节点追加-large/-smallclass见下方实现剖析由 CSS-in-JS 样式分别匹配starSizeLG/starSizeSM两个不同字号 Token 来生效的。半星allowHalf支持半星选择配合defaultValue{2.5}可让初始值落在半星上half.tsximport React from react; import { Rate } from antd; const App: React.FC () Rate allowHalf defaultValue{2.5} /; export default App;只读展示disabled让组件进入只读状态无法进行交互适合“评价展示”场景disabled.tsx。从源码看disabled除了阻止鼠标交互外还会通过样式移除 hover 的缩放反馈并让光标变为defaultimport React from react; import { Rate } from antd; const App: React.FC () Rate disabled defaultValue{2} /; export default App;再次点击清除allowClear控制“再次点击当前选中星星是否清空分值”。默认开启显式设为false后可保证用户始终能选到至少一颗星clear.tsximport React from react; import { Flex, Rate } from antd; const App: React.FC () ( Flex gapmedium vertical Flex gapmedium Rate defaultValue{3} / spanallowClear: true/span /Flex Flex gapmedium Rate defaultValue{3} allowClear{false} / spanallowClear: false/span /Flex /Flex );进阶玩法用 tooltips 展示文案通过tooltips为每一颗星星配置提示文案取值既可以是string也可以是完整的 TooltipProps 对象text.tsximport React, { useState } from react; import { Flex, Rate } from antd; import type { RateProps } from antd; const desc: RateProps[tooltips] [ terrible, { placement: top, title: bad, trigger: hover }, normal, good, wonderful, ]; function getDescTitle(value: number, desc: RateProps[tooltips]) { const item desc?.[value - 1]; return item typeof item object ? item.title : item; } const App: React.FC () { const [value, setValue] useState(3); return ( Flex gapmedium vertical Rate tooltips{desc} onChange{setValue} value{value} / {value ? span{getDescTitle(value, desc) as React.ReactNode}/span : null} /Flex ); };该 demo 同时演示了受控模式的标准写法外部用useState持有valueonChange更新状态再在下文同步渲染“terrible / wonderful”等文案。当tooltips元素是对象时组件会在该星位上渲染一个带完整 Tooltip 配置的包裹层。替换默认星星字符character可以替换默认的StarFilled /。无论传图标、字符文字还是单个字符只要是一个ReactNode即可character.tsximport React from react; import { HeartOutlined } from ant-design/icons; import { Flex, Rate } from antd; const App: React.FC () ( Flex vertical gapmedium Rate character{HeartOutlined /} allowHalf / Rate characterA allowHalf style{{ fontSize: 36 }} / Rate character好 allowHalf / /Flex );这里展示了三种思路替换为图标爱心、替换为字母A并直接用style放大字号、替换为中文“好”字适合做趣味评分、满意度表达等场景。按位置自定义字符函数形式character传函数时可基于每个星星的index动态返回字符自 4.4.0 支持实现“前几颗一个表情、后几颗一个表情”的分段表达character-function.tsximport React from react; import { FrownOutlined, MehOutlined, SmileOutlined } from ant-design/icons; import { Flex, Rate } from antd; const customIcons: Recordnumber, React.ReactNode { 1: FrownOutlined /, 2: FrownOutlined /, 3: MehOutlined /, 4: SmileOutlined /, 5: SmileOutlined /, }; const App: React.FC () ( Flex gapmedium vertical Rate defaultValue{2} character{({ index 0 }) index 1} / Rate defaultValue{3} character{({ index 0 }) customIcons[index 1]} / /Flex );第一行用index 1直接显示数字“1 2 3 4 5”第二行则通过Recordnumber, ReactNode映射表让 1–2 星为哭脸、3 星为中性脸、4–5 星为笑脸。实现原理Rate 组件封装剖析Rate 本身是一个基于rc-component/rate的轻量封装components/rate/index.tsx 中可以看出以下关键设计默认字符为 StarFilledcharacter StarFilled /作为默认值来自ant-design/icons。tooltips 通过 characterRender 注入组件内部基于底层characterRender钩子为每个星位包裹一层Tooltip。若tooltips元素是纯对象则直接展开为{...tooltipsItem}否则包装为title{tooltipsItem}。这意味着底层渲染逻辑选中、hover、键盘完全不受影响Tooltip 仅作为视觉层叠加。Disabled 上下文合并disabled会先读取DisabledContext由 ConfigProvider 提供再与显式传入值合并customDisabled ?? disabled从而支持 ConfigProvider 级别的统一禁用控制。Size 上下文合并通过useSize钩子解析出最终尺寸并据此追加${ratePrefixCls}-large/-smallclass未指定时继承 ConfigProvider 的componentSize。RTL 支持从useComponentConfig(rate)读取direction并透传给底层 RcRate组件在style中另有-rtl规则。CSS-in-JS 集成useStyle依据 prefixCls 生成带hashId与cssVarCls的样式支持 antd 的静态样式抽取与 CSS 变量主题切换。Design Token 与主题定制Rate 暴露了 5 个组件级 Design Token可通过 ConfigProvider 的theme.components.Rate定制Token 定义见 components/rate/style/index.tsToken说明默认值推导见prepareComponentTokenstarColor星星已选中部分颜色token.yellow6主题黄色starSize中等尺寸星星的字号controlHeight * 0.625starSizeSMsmall 尺寸星星字号controlHeightSM * 0.625starSizeLGlarge 尺寸星星字号controlHeightLG * 0.625starHoverScale星标 hover 时的缩放 transformscale(1.1)starBg星星未选中背景底色colorFillContent官方在 component-token.tsx 中给出了一个完整示例该 demo 标注为 debug/测试用途不建议直接在生产中使用仅用于演示 Token 生效方式import React from react; import { ConfigProvider, Rate } from antd; export default () ( ConfigProvider theme{{ components: { Rate: { starColor: blue, starSize: 40, starHoverScale: scale(2), starBg: red, }, }, }} Rate defaultValue{2.5} / /ConfigProvider );从样式源码可以印证这些 Token 的实际作用位置半星/满星染色每个星位内部拆分为-first左半与-second右半两个半层。未选中部分统一使用starBg底色当星位处于-half或-full状态时对应半层恢复color: inherit从而透出最外层starColor的颜色见genRateStarStyle。hover 反馈每个星位内的可点区域在 hover 时应用transform: token.starHoverScale同时为:focus-visible绘制lineWidthFocus宽的虚线焦点圈颜色为starColor这是键盘可访问性视觉反馈的一部分。禁用态disabled场景下 hover 的 transform 会被重置为scale(1)光标改为default避免出现“看似可点”的误导。重置样式组件根节点应用了 antd 的resetComponent保证 ul 列表语义listStyle: none、margin/padding: 0在不同浏览器下表现一致。需要说明的是上述 Token 是在 antd 提供的genStyleHooks(Rate, ...)工厂中生成并挂载的因此与 antd 的 Design Token 体系包括全局seedtoken 与算法天然打通例如颜色、间距、动效时长motionDurationMid均取自全局主题。无障碍与键盘操作自 5.18.0 起keyboard默认开启使 Rate 支持纯键盘操作组件可聚焦Tab 到达获得焦点时每颗星显示虚线焦点轮廓源码中以:focus-visiblestarColor虚线实现。通过方向键可在星星间移动配合Enter/选择键完成取值同时触发onKeyDown回调。onFocus/onBlur可感知焦点进出focus()/blur()允许外部指令式管理焦点。若需彻底禁止键盘参与可将keyboard{false}。小结Rate 以极低的 API 复杂度覆盖了评分场景的绝大多数诉求基础的受控/非受控取值、半星精确度、点击清除、只读展示再到tooltips文案、character字符含按 index 的函数形式与三种尺寸。若需深度定制视觉可优先使用starColor/starSize/starHoverScale等 Design Token它们能与你现有的 antd 主题无缝融合。本文所有示例源码均可直接在 components/rate/demo 目录下找到对应的.tsx与.md文件中文说明参见 index.zh-CN.md。【免费下载链接】ant-designAn enterprise-class UI design language and React UI library项目地址: https://gitcode.com/GitHub_Trending/an/ant-design创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考