ant-design Rate 组件自定义字符函数：用 `(RateProps) =＞ ReactNode` 按索引动态渲染每个评分字符

ant-design Rate 组件自定义字符函数：用(RateProps) => ReactNode按索引动态渲染每个评分字符

【免费下载链接】ant-designAn enterprise-class UI design language and React UI library项目地址: https://gitcode.com/gh_mirrors/ant/ant-design

导读

ant-design 的 Rate（评分）组件默认以实心五角星作为字符，但在真实业务中，评分往往需要承载语义——例如用表情图标表达"不满意 / 一般 / 满意"。Rate 的character属性支持函数形态(RateProps) => ReactNode，允许开发者针对每一个评分位置动态返回不同的字符，实现"按位自定义"的评分样式。本文以 components/rate/demo/character-function.tsx 及其文档 components/rate/demo/character-function.md 为核心，讲解该函数式自定义字符的用法、参数结构、与静态字符的差异，并结合源码与测试说明其背后的实现机制，读完即可在项目里落地"表情评分、数字评分"等自定义交互。

一、从静态字符到函数式字符

Rate 的character属性有两种形态（见 components/rate/index.zh-CN.md 的 API 表格）：

静态字符（ReactNode形态）在 components/rate/demo/character.tsx 中有完整演示：可以把星星替换为字母"A"、中文"好"、图标<HeartOutlined />甚至任意 ReactNode。其局限在于所有位置字符相同，无法表达"第 1 颗很生气、第 5 颗很开心"这类递进语义。

函数式字符（(RateProps) => ReactNode形态）正是为解决这一问题而设计：组件在渲染每一个评分字符时都会调用该函数，并把包含当前字符位置的index传入，开发者据此返回差异化的 ReactNode。该能力自 antd 4.4.0 起提供（见上表character行的版本标注）。

二、character-function 演示完整解读

components/rate/demo/character-function.md 的说明为："可以使用(RateProps) => ReactNode的方式自定义每一个字符。"其配套代码 components/rate/demo/character-function.tsx 给出了两个典型场景：

场景一：按索引渲染数字

<Rate defaultValue={2} character={({ index = 0 }) => index + 1} />

• 组件会渲染 count（默认 5）个字符，每个字符调用一次character；
• 函数参数中index从 0 开始计数，index + 1即得到 1～5 的数字；
• defaultValue={2}表示当前选中第 2 个位置，前两个数字会呈现选中态。

场景二：按索引映射表情图标

const customIcons: Record<number, React.ReactNode> = { 1: <FrownOutlined />, 2: <FrownOutlined />, 3: <MehOutlined />, 4: <SmileOutlined />, 5: <SmileOutlined />, }; <Rate defaultValue={3} character={({ index = 0 }) => customIcons[index + 1]} />

• 先定义Record<number, ReactNode>映射表，把评分等级（1～5）映射为对应的图标节点；
• 由于index从 0 开始，而映射表从 1 开始，因此通过index + 1对齐；
• 这里的FrownOutlined、MehOutlined、SmileOutlined均来自@ant-design/icons，三者配合即形成"低分沮丧、中间平淡、高分满意"的经典表情评分体验。

演示代码将两个 Rate 放在 Flex 容器中纵向排列（vertical gap="middle"），方便对比"数字评分"与"表情评分"两种效果。

默认值与空值安全

示例中写法为({ index = 0 }) => ...，对index设置了默认值0。这是为了处理index可能为undefined的场景：当组件处于一些特殊状态（例如键盘操作或部分渲染路径）时，index可能未被传入，此时按0兜底处理，避免undefined + 1产生NaN。虽然常规渲染下index一定存在，但保留兜底默认值是一种稳妥的防御性写法，也是官方演示采用的写法。

三、源码级原理：character 如何被透传与渲染

从源码看，ant-design 的 Rate 组件本身是 rc-rate 的薄封装。在 components/rate/index.tsx 中：

const { prefixCls, className, rootClassName, style, tooltips, character = <StarFilled />, // 默认静态字符 ...rest } = props; return wrapCSSVar( <RcRate ref={ref} character={character} characterRender={characterRender} {...rest} ... />, );

关键点：

1. 默认值：character未被传入时默认<StarFilled />，即大家熟悉的实心五角星；
2. 直接透传：character原样传给底层rc-rate的RcRate组件，ant-design 层不做任何加工，函数形态的解析完全由rc-rate内部完成（项目依赖"rc-rate": "~2.13.0"，见 package.json）；
3. ant-design 只额外处理 tooltips：组件内部定义characterRender，仅在传入tooltips时用 Tooltip 包裹每个字符节点以显示提示文案，否则原样返回节点；这与character的函数逻辑互不干扰，可以组合使用（详见下文第五节）。

由此可以推断：(RateProps) => ReactNode中的参数对象来自rc-rate在逐个渲染 Star 时注入的信息，其中index表示当前字符位置（从 0 开始）；ant-design 的类型定义RateProps extends RcRateProps（见 components/rate/index.tsx）也保证了函数形态的类型安全。

与 rc-rate 的调用链

完整调用链为：

用户传入 character 函数 → antd Rate（components/rate/index.tsx）透传给 RcRate → rc-rate 逐位渲染 Star，调用 character({ index, ... }) → 返回的 ReactNode 被用于对应位置的字符渲染

antd 侧只负责默认字符、样式（useStyle、CSS 变量包裹）、Tooltip增强与ConfigContext的 prefixCls/direction 传递，渲染核心逻辑在 rc-rate 中完成。

四、函数参数 RateProps 可用的信息

(RateProps) => ReactNode的函数参数类型为RateProps（即 rc-rate 的RcRateProps，antd 在此基础上扩展了rootClassName与tooltips）。虽然官方演示只用到index，但该参数对象承载的是整个 Rate 的属性集合，这意味着：

• index：当前字符所在位置，从 0 开始计数，是函数式自定义的核心依据，配合index + 1即可映射到用户感知的"第几颗星"；
• count：评分总数（默认 5），可用于按比例计算字符样式，例如前 40% 用一种图标、后 60% 用另一种；
• value/defaultValue相关取值：可在函数内感知当前选中值，实现"选中部分高亮、未选中部分置灰"等复杂视觉；
• disabled、allowHalf等其余属性：理论上均可读取，用于组合出更精细的渲染逻辑。

实际开发中，最常用的是index；如需更强的"选中/未选中"差异化渲染，可结合value等属性自行判断。由于 antd 的RateProps由RcRateProps继承而来，函数参数的类型定义在 antd 侧是完整的，TypeScript 下可直接获得属性提示。

五、实战组合：函数式字符 × tooltips × 受控值

函数式字符并非孤立特性，可与 Rate 的其他能力自由组合，这里给出两个可以直接运行的扩展思路：

组合一：表情评分 + 悬停提示

import { FrownOutlined, MehOutlined, SmileOutlined } from '@ant-design/icons'; import { Rate, Flex } from 'antd'; const customIcons: Record<number, React.ReactNode> = { 1: <FrownOutlined />, 2: <FrownOutlined />, 3: <MehOutlined />, 4: <SmileOutlined />, 5: <SmileOutlined />, }; const App = () => ( <Flex vertical gap="middle"> <Rate defaultValue={3} character={({ index = 0 }) => customIcons[index + 1]} tooltips={['很差', '较差', '一般', '满意', '非常满意']} /> </Flex> ); export default App;

tooltips为字符串数组，第 i 项对应第 i 个字符的提示文案，通过 antd 内部characterRender用 Tooltip 包裹（实现见 components/rate/index.tsx），与函数式字符互不冲突。

组合二：表情评分 + 半星

<Rate allowHalf defaultValue={3.5} character={({ index = 0 }) => customIcons[Math.ceil(index + 1)]} />

开启allowHalf后，index仍按整星位置传入，可按实际业务决定取整规则；此写法仅为示意，具体映射需结合自身评分语义调整。

此外，受控用法下可结合value与onChange（onChange回调参数为number，完整回调列表见 components/rate/index.zh-CN.md 的 API 表格）实现完全受控的评分表单，函数式字符在其中不受影响。

六、演示代码是如何被验证的

ant-design 仓库对每个组件的演示代码都有自动化保障，Rate 也不例外：

• components/rate/tests/demo.test.ts 通过共享的demoTest('rate')对全部 demo（含 character-function）执行渲染冒烟测试，确保示例可正常挂载渲染；
• components/rate/tests/demo-extend.test.ts 通过extendTest('rate')做扩展校验（含快照），其快照文件见 components/rate/tests/snapshots/demo-extend.test.ts.snap；
• components/rate/tests/index.test.ts 则对组件本身执行焦点（focusTest）、挂载（mountTest）与 RTL 方向（rtlTest）三项基础测试。

因此，本文引用的 character-function 示例在仓库中始终以可运行的完整形态存在，读者将其中的代码直接复制到自己的 antd 项目即可使用，无需额外安装依赖——只需确保项目已安装antd与@ant-design/icons。

七、小结

Rate 的character函数形态(RateProps) => ReactNode以极低的成本实现了"每个评分位点独立渲染"的能力：

• 用index参数（从 0 开始）区分位点，index + 1对齐用户感知的星级序号；
• 结合Record<number, ReactNode>映射表可快速实现表情、数字、字母等自定义评分，components/rate/demo/character-function.tsx 即是最佳起点；
• 该能力由 antd 透传给底层 rc-rate 完成，antd 负责默认星形字符、Tooltip 增强与样式体系，两者职责清晰；
• 函数式字符可与tooltips、allowHalf、受控value/onChange自由组合，覆盖绝大多数自定义评分场景。

建议开发者在自定义评分时优先参考 components/rate/demo/character-function.tsx 与 components/rate/demo/character.tsx 两个演示，前者解决"按位差异化"，后者解决"整体换肤"，两者结合即可满足几乎全部 Rate 字符定制需求。

【免费下载链接】ant-designAn enterprise-class UI design language and React UI library项目地址: https://gitcode.com/gh_mirrors/ant/ant-design