antd Rate 评分组件完整指南从基础用法到源码原理与主题定制【免费下载链接】ant-designAn enterprise-class UI design language and React UI library项目地址: https://gitcode.com/GitHub_Trending/an/ant-designRate评分是 antd 数据录入组件体系中用于“对评价进行展示、对事物进行快速评级操作”的核心组件。本指南以 antd 仓库内 Rate 组件的官方中文文档为主体结合其组件实现源码、样式与 Design Token 定义、示例与测试代码系统讲解 Rate 的全部 API、常见业务形态半星、文案、只读、清除、自定义字符、实例方法以及主题变量定制方法。读完本文你将能够熟练在表单与展示场景中使用 Rate并通过 Design Token 深度定制其视觉表现。何时使用 Rate 评分组件按官方文档Rate 适用于两类典型场景对评价进行展示以星级直观呈现已评定的结果例如商品评分、服务评级的只读回显对事物进行快速的评级操作让用户通过点击或键盘在星星上快速打分例如表单中的评分采集。快速上手与基础用法Rate 从 antd 主入口统一导出见 components/index.ts 的export { default as Rate } from ./rate并同时导出类型RateProps。最简用法只需一行代码import React from react; import { Rate } from antd; const App: React.FC () Rate /; export default App;对应的基本用法示例默认渲染 5 颗星星count默认值为 5未选中时值为 0defaultValue默认值为 0。点击第 N 颗星即评分为 N再次点击当前选中的星星默认会清除评分由allowClear控制默认true。三种尺寸small / medium / largeRate 的星星尺寸通过size属性控制可选值为small | medium | large默认medium。参考尺寸示例import React from react; import { Flex, Rate } from antd; const App: React.FC () ( Flex vertical gapmedium Rate sizelarge / Rate / Rate sizesmall / /Flex ); export default App;从源码看尺寸并非直接改图标字号而是通过前缀类名实现ratePrefixCls-large/ratePrefixCls-small见 components/rate/index.tsx再在 CSS 中分别应用starSizeLG/starSizeSM见 components/rate/style/index.ts。因此当外层有ConfigProvider提供统一的size上下文时Rate 会遵循全局尺寸约定下文源码原理会详述合并逻辑。半星评分与文案展现半星allowHalf业务中常出现 2.5、3.5 这样的半星评分。开启allowHalf后鼠标悬停在星星左半区即可选中半星。参考半星示例import React from react; import { Rate } from antd; const App: React.FC () Rate allowHalf defaultValue{2.5} /; export default App;半星在视觉与结构上依赖样式层实现每一颗星星内嵌一层占宽 50% 的“前半星”层.ant-rate-star-first命中-half状态时前后两半同时显现、被选中时覆盖前景色详见 components/rate/style/index.ts。这意味着半星交互走的是标准 DOM 结构而非 canvas 或图片裁切行为可预测且易于通过主题定制。文案展现tooltips onChange 联动星级有时需要配合文字如 terrible / good / wonderful一起展示。antd 提供tooltips属性不仅支持字符串数组还支持TooltipProps对象数组可针对每一项单独配置placement、trigger等。参考文案展现示例import 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 ); }; export default App;注意此示例中的onChange直接回填value使 Rate 处于受控模式文案随评分实时切换。对象式tooltips之所以可行是因为 antd 在包装层做了类型分派characterRender内部用isPlainObject(tooltipsItem)判断——对象形式的条目会完整透传给Tooltip {...tooltipsItem}字符串形式则简化为title见 components/rate/index.tsx。只读展示与评分清除只读disabled对已完成评价做回显时通常需要禁止交互使用disabled。参考只读示例import React from react; import { Rate } from antd; const App: React.FC () Rate disabled defaultValue{2} /; export default App;disabled状态下星星失去 pointer 交互样式层将 cursor 改为default并取消 hover 缩放见 components/rate/style/index.ts。同时组件会合并ConfigProvider的DisabledContext仅当外层整体禁用时才联动源码见 components/rate/index.tsx。清除allowClear默认再次点击当前已选中的星星会清除评分设置allowClear{false}后则不允许清除。参考清除示例import 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 );自定义字符从图标到任意 ReactNode默认星星图标为StarFilled源码中character StarFilled /见 components/rate/index.tsx。character属性支持 ReactNode 或函数可替换为爱心、文字乃至任意元素。参考其他字符示例import 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 );当character为函数时入参携带当前星的index可在运行时“按位”决定每颗星长什么样非常适合表达“1 星很差、5 星很好”的情绪化映射。参考自定义字符示例import 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 );示例第二段展示了经典的“笑脸评分”写法函数版本从 5.18.0 开始支持见 API 表中character的版本说明index从 0 起因此取图标映射时需index 1。API 完整说明通用属性请参考 通用属性文档。Rate 支持的全部属性如下其中“版本”列标注了新能力引入或变更的版本属性说明类型默认值版本全局配置allowClear是否允许再次点击后清除booleantrue×allowHalf是否允许半选booleanfalse×character自定义字符ReactNode | (RateProps) ReactNodeStarFilled /function(): 4.4.0×countstar 总数number5×defaultValue默认值number0×disabled只读无法进行交互booleanfalse×keyboard支持使用键盘操作booleantrue5.18.0×size星星尺寸small | medium | largemedium×tooltips自定义每项的提示信息TooltipProps[] | string[]-×value当前数受控值number-×onBlur失去焦点时的回调function()-×onChange选择时的回调function(value: number)-×onFocus获取焦点时的回调function()-×onHoverChange鼠标经过时数值变化的回调function(value: number)-×onKeyDown按键回调function(event)-×要点提示value配合onChange使用即可切换到受控模式适合与表单Form.Item绑定做校验与回填count可自定义星星总数例如 10 分制场景设count{10}tooltips元素个数通常与count一一对应多出的项不会被渲染keyboard自 5.18.0 起默认开启用户可通过方向键调整评分从而保证键盘可达性antd 的 Rate 本质是对rc-component/rateRcRate的封装除上述属性外的其余属性会通过{...rest}透传给底层组件见 components/rate/index.tsx。实例方法focus() 与 blur()通过 ref 可调用组件实例方法名称描述blur()移除焦点focus()获取焦点底层实现通过React.forwardRef将 ref 转发给 RcRate见 components/rate/index.tsx因此可以在需要时对 Rate 编程式聚焦/失焦。测试侧亦有对应保障components/rate/__tests__/index.test.tsx使用共享用例focusTest(Rate, { refFocus: true })验证了 ref 聚焦链路与回调触发行为。主题变量用 Design Token 深度定制 RateRate 的视觉完全由 cssinjs 生成可通过ConfigProvider的theme.components.Rate覆盖。在 组件 Token 定义文件 中声明的令牌及默认值如下Token含义默认值取自prepareComponentToken见 style/index.tsstarColor星星已选中颜色yellow6默认金色starSize中尺寸星星字号controlHeight * 0.625starSizeSM小尺寸星星字号controlHeightSM * 0.625starSizeLG大尺寸星星字号controlHeightLG * 0.625starHoverScale星星悬浮时的缩放 transformscale(1.1)starBg未选中星星的背景色colorFillContent其余还有内部派生项lineWidthFocus聚焦描边宽度以及被引用但未直接暴露的marginXS星间距、motionDurationMid过渡时长等。官方组件 Token 演示可参见 组件 Token 示例import React from react; import { ConfigProvider, Rate } from antd; /** Test usage. Do not use in your production. */ export default () ( ConfigProvider theme{{ components: { Rate: { starColor: blue, starSize: 40, starHoverScale: scale(2), starBg: red, }, }, }} Rate defaultValue{2.5} / /ConfigProvider );半星结构在样式层的实现也很值得了解每颗星包含“前 50%”与“后 50%”两层-half状态同时点亮两层、-full状态点亮后层并覆盖前景色因此悬停、聚焦与半选都能精确作用于单个星详见 genRateStarStyle。此外组件原生支持 RTLdirection从 ConfigProvider 上下文透传配合-rtl前缀类名即可镜像排列见 components/rate/index.tsx 与 genRateRtlStyle。源码实现原理速览Rate 的源码结构非常精简核心逻辑都在rc-component/rateantd 的 index.tsx 主要负责四件事默认字符注入未传character时默认渲染StarFilled /tooltips 增强通过characterRender把字符串/对象形式的 tooltips 包成Tooltip这也是tooltips能接受TooltipProps对象的直接原因上下文合并size通过useSize((ctx) size ?? ctx)与 ConfigProvider 尺寸上下文合并disabled通过useContext(DisabledContext)与全局禁用上下文合并实现“局部优先、全局兜底”样式接入useStyle(ratePrefixCls)按 cssinjs 规范生成带hashId/cssVarCls的样式并把small/large尺寸落到前缀类上。顺带一提Rate 当前默认尺寸映射为 small/medium/large其视觉规格字号、间距、悬停缩放全部收敛在 style/index.ts 的 Token 体系中无需改源码即可完成品牌化定制。无障碍与键盘操作从文档与代码可确认以下无障碍能力键盘操作keyboard默认true5.18.0 起聚焦后可借助方向键增减评分与原生可访问交互预期一致聚焦可见性:focus-visible时使用starColor颜色的虚线 outline配合starHoverScale缩放提示当前星避免纯靠颜色区分见 style/index.ts禁用态disabled下光标恢复default、hover 缩放关闭从视觉上明确传达“不可交互”测试保障仓库在 a11y 测试 与 index.test.tsx 中覆盖了焦点管理、ref 方法、渲染快照等行为。小结Rate 组件“开箱即用”且扩展点清晰业务上覆盖基本评分、半星、文案联动、只读、清除、自定义字符等全部常见形态控制上支持受控/非受控、focus()/blur()实例方法、默认开启的键盘操作样式上所有视觉令牌星星颜色、三档尺寸、悬浮缩放、背景色均可在theme.components.Rate中覆盖。若需在真实表单中接入校验将value/onChange与 Form 的字段绑定即可更底层的实现细节可继续阅读 Rate 主文件 与其样式 Token 定义 获得完整认识。【免费下载链接】ant-designAn enterprise-class UI design language and React UI library项目地址: https://gitcode.com/GitHub_Trending/an/ant-design创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考