Vant Rate 评分组件完全指南从基础用法到源码级交互原理【免费下载链接】vantA lightweight, customizable Vue UI library for mobile web apps.项目地址: https://gitcode.com/GitHub_Trending/va/vantRate评分是 Vant 组件库中用于对事物进行评级的轻量级交互组件。在移动端电商、内容社区、服务评价等场景中它承担着收集用户评分反馈的核心职责。本文以 packages/vant/src/rate/README.md 为主干结合组件源码 Rate.tsx、样式文件 index.less 与测试用例 index.spec.ts系统讲解 Rate 的全部属性、事件、主题定制方式并深入剖析其半星计算、滑动手势评分等底层实现原理。读完本文你将能够在项目中灵活配置评分组件并理解其交互机制的可定制边界。一、组件简介与安装Rate 组件通过一组图标默认为星形来表示评分支持v-model双向绑定当前分值同时提供半星、只读、禁用、可清空等多种状态控制。在 Vant 中组件以插件形式注册。通过app.use进行全局注册import { createApp } from vue; import { Rate } from vant; const app createApp(); app.use(Rate);注册完成后即可在模板中使用van-rate标签van-rate这一全局组件名由 index.ts 中的declare module vue全局类型声明提供。更多注册方式如按需引入、自动导入可参考仓库中的进阶用法文档 advanced-usage.zh-CN.md。二、基础用法v-model 双向绑定Rate 的核心数据流通过v-model完成绑定的值即为当前评分van-rate v-modelvalue /import { ref } from vue; export default { setup() { const value ref(3); return { value }; }, };从源码看modelValue的默认值为0Rate.tsx 中modelValue: makeNumberProp(0)且组件通过useCustomFieldValue将其接入表单体系因此嵌套在van-field等表单场景中时也能与表单校验、提交逻辑协同工作。三、自定义图标与样式3.1 自定义图标通过icon设置选中时的图标void-icon设置未选中时的图标。图标名称直接复用 Icon 组件的name属性规则可以传入内置图标名或图片链接van-rate v-modelvalue iconlike void-iconlike-o /默认情况下选中图标为star、未选中为star-o源码 Rate.tsx 与 Rate.tsx 中的makeStringProp(star)与makeStringProp(star-o)。在自定义图标场景中常见做法是使用点赞主题的like/like-o图标对。3.2 自定义尺寸与颜色size控制图标大小color控制选中颜色void-color控制未选中颜色gutter控制图标间距van-rate v-modelvalue :size25 color#ffd21e void-iconstar void-color#eee /size、gutter的类型为number | string默认单位为px也可以传2rem等任意合法 CSS 长度测试用例 index.spec.ts 验证了传入2rem时图标font-size被正确设置颜色默认值分别为#ee0a24Vant 品牌红与#c8c9cc灰色实际渲染时通过Icon组件的color属性下发。3.3 自定义类名前缀icon-prefix用于指定图标类名前缀默认van-icon与 Icon 组件的class-prefix属性语义一致适用于引用了自定义字体图标库、需要替换类名前缀的场景。四、半星与只读小数显示4.1 半星选择设置allow-half后用户可以选中半星van-rate v-modelvalue allow-half /import { ref } from vue; export default { setup() { const value ref(2.5); return { value }; }, };半星的实现原理值得关注。源码 Rate.tsx 中的getRateStatus函数决定了每一颗星的状态当value index时为full满星权重为 1当value 0.5 index且开启allow-half且非只读时为half半星权重为 0.5只读且开启allow-half时支持更精细的小数权重通过Math.round((value - index 1) * 10 ** 10) / 10 ** 10计算消除浮点误差。渲染时半星通过双层图标实现底层渲染空心图标上层叠加一个宽度按小数比例裁剪的实心图标style{{ width: item.value em }}见 Rate.tsx配合 index.less 中__icon--half的position: absolute; overflow: hidden样式实现裁剪效果。4.2 只读状态显示任意小数设置readonly与allow-half后组件可以展示任意小数评分结果常用于展示服务端返回的平均分如 4.3、3.7van-rate v-modelvalue readonly allow-half /import { ref } from vue; export default { setup() { const value ref(3.3); return { value }; }, };测试用例 index.spec.ts 验证了modelValue 3.3时半星图标宽度被精确设置为0.3em。五、自定义数量通过count属性可以设置评分总数即图标个数类型为number | string默认5van-rate v-modelvalue :count6 /源码中count: makeNumericProp(5)同时接受数字与字符串渲染时通过Array(props.count)生成对应数量的图标Rate.tsx测试用例 index.spec.ts 验证了传入字符串4也能正确渲染 4 个图标。六、可清空再次点击归零当clearable属性设置为truev4.6.0 起提供再次点击当前相同的值时评分会被重置为0van-rate v-modelvalue clearable /其判定逻辑在 Rate.tsx 的onClickItem中仅当clearable开启、当前操作被识别为轻点touch.isTap即未发生拖拽位移见 use-touch.ts 中的TAP_OFFSET判断且点击位置对应的值与当前值相同时才将值重置为 0从而避免滑动过程中误触发清空。七、禁用与只读禁用disabled完全禁止交互图标以禁用色展示鼠标样式变为not-allowedvan-rate v-modelvalue disabled /只读readonly仅禁止修改评分视觉上仍为正常颜色鼠标样式为默认van-rate v-modelvalue readonly /源码中unselectable readonly || disabled统一屏蔽了选择行为禁用时还会移除图标的tabindex并设置aria-disabled保持无障碍语义Rate.tsx。样式上index.less 为禁用与只读分别定义了cursor: not-allowed与cursor: default。八、监听 change 事件评分变化时触发change事件回调参数为当前分值van-rate v-modelvalue changeonChange /import { ref } from vue; import { showToast } from vant; export default { setup() { const value ref(3); const onChange (value) showToast(current value: value); return { value, onChange, }; }, };从事件机制看组件同时发射update:modelValue与change两个事件Rate.tsx 中的select函数。测试用例 index.spec.ts 验证了点击第 4 个图标时两者各触发一次且参数为4当点击值与当前值相同时非 clearable 场景不触发任何事件禁用状态下同样不触发。九、API 完整参考9.1 Props 一览参数说明类型默认值v-model当前分值number-count图标总数number | string5size图标大小默认单位为pxnumber | string20pxgutter图标间距默认单位为pxnumber | string4pxcolor选中时的颜色string#ee0a24void-color未选中时的颜色string#c8c9ccdisabled-color禁用时的颜色string#c8c9ccicon选中时的图标名称或图片链接等同于 Icon 组件的name属性stringstarvoid-icon未选中时的图标名称或图片链接等同于 Icon 组件的name属性stringstar-oicon-prefix图标类名前缀等同于 Icon 组件的class-prefix属性stringvan-iconallow-half是否允许半选booleanfalseclearablev4.6.0是否允许再次点击后清除booleanfalsereadonly是否为只读状态只读状态下无法修改评分booleanfalsedisabled是否禁用评分booleanfalsetouchable是否可以通过滑动手势选择评分booleantrue补充说明各属性的源码级细节Rate.tsx 中的rateProps定义modelValue使用makeNumberProp(0)默认 0size、gutter使用numericProp[Number, String]兼容数字与带单位的字符串icon、void-icon、icon-prefix使用makeStringProp其中iconPrefix默认为undefined由 Icon 组件回落至van-icontouchable使用truthPropBoolean类型且默认true这是 Vant 中默认为真的布尔属性的标准写法见 utils/props.ts。9.2 Events事件名说明回调参数change当前分值变化时触发的事件currentValue: number9.3 类型定义组件导出RateProps类型便于在 TypeScript 项目中做 props 类型约束import type { RateProps } from vant;同时 types.ts 导出了RateThemeVars类型对应下方主题定制中的 5 个 CSS 变量可用于 ConfigProvider 的主题变量类型推断。十、主题定制CSS 变量组件提供以下 CSS 变量可通过 ConfigProvider 组件见 config-provider/README.md在全局或局部进行主题定制名称默认值描述--van-rate-icon-size20px图标大小--van-rate-icon-guttervar(--van-padding-base)图标间距--van-rate-icon-void-colorvar(--van-gray-5)未选中颜色--van-rate-icon-full-colorvar(--van-danger-color)选中颜色--van-rate-icon-disabled-colorvar(--van-gray-5)禁用颜色这些变量的默认值定义在 index.less 的:root, :host块中并与rateProps中对应的 props 一一映射size对应--van-rate-icon-size作用于图标的font-sizegutter对应图标padding-rightcolor/void-color/disabled-color分别对应--van-rate-icon-full-color/--van-rate-icon-void-color/--van-rate-icon-disabled-color。值得留意的是props 传入的显式值优先级高于 CSS 变量因此两者可以配合使用用 CSS 变量做全局主题用 props 做单组件覆盖。十一、源码级原理剖析滑动评分与无障碍Rate 不仅支持点击评分默认还支持在图标上横向滑动连续改分touchable默认true。其核心链路如下区域映射updateRanges触摸开始时通过useRect测量组件容器与每个图标的几何位置生成ranges数组。开启allow-half时每个图标被拆分为左半分数index 0.5与右半分数index 1两个区域从而实现半星的精确命中Rate.tsx。坐标换算getScoreByPosition滑动过程中根据手指的clientX / clientY反查命中的ranges区域得到对应分数当手指移出组件垂直范围时还会就近映射到最近一行的图标区域保证横向滑动体验的连续性Rate.tsx。事件绑定touchmove监听使用useEventListener并显式关闭 passive 模式以避免 Chrome 对默认行为阻止的警告滑动仅在touch.isHorizontal()横向位移占主导且非轻点!isTap时触发评分避免与页面纵向滚动冲突Rate.tsx、use-touch.ts。测试用例 index.spec.ts 通过triggerDrag模拟横向拖拽验证了默认模式下连续触发[1, 2, 2, 4]的评分序列以及allow-half模式下触发[1, 1.5, 2, 4]的半星序列touchable: false时拖拽不产生任何事件。此外组件还内置了完整的无障碍支持容器带有roleradiogroup每个图标为roleradio并设置了aria-checked、aria-setsize、aria-posinset、aria-disabled、aria-readonly等属性Rate.tsx键盘用户可以通过 Tab 聚焦并操作评分。十二、完整示例仓库中的 demo/index.vue 汇总了上述全部场景基础用法、自定义图标、自定义样式、半星、自定义数量、可清空、禁用、只读、只读小数、change 事件并配套快照测试 demo.spec.ts。实际开发中可直接参照该文件组织自己的评分交互页面。总结Rate 组件以v-model为核心数据流通过count、size、color、icon、allow-half、clearable、readonly、disabled、touchable等十余个属性覆盖了评分场景的全部常见需求并提供change事件与 5 个 CSS 变量支撑交互反馈与主题定制。从源码实现看其半星渲染采用双层图标宽度裁剪方案滑动评分基于触摸坐标到图标区域的精确映射同时兼顾了表单集成与无障碍语义是一个麻雀虽小、五脏俱全的移动端评分方案可直接在 Vant 项目中开箱即用。【免费下载链接】vantA lightweight, customizable Vue UI library for mobile web apps.项目地址: https://gitcode.com/GitHub_Trending/va/vant创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考 Vant Rate 评分组件完全指南：从基础用法到源码级交互原理
Vant Rate 评分组件完全指南从基础用法到源码级交互原理【免费下载链接】vantA lightweight, customizable Vue UI library for mobile web apps.项目地址: https://gitcode.com/GitHub_Trending/va/vantRate评分是 Vant 组件库中用于对事物进行评级的轻量级交互组件。在移动端电商、内容社区、服务评价等场景中它承担着收集用户评分反馈的核心职责。本文以 packages/vant/src/rate/README.md 为主干结合组件源码 Rate.tsx、样式文件 index.less 与测试用例 index.spec.ts系统讲解 Rate 的全部属性、事件、主题定制方式并深入剖析其半星计算、滑动手势评分等底层实现原理。读完本文你将能够在项目中灵活配置评分组件并理解其交互机制的可定制边界。一、组件简介与安装Rate 组件通过一组图标默认为星形来表示评分支持v-model双向绑定当前分值同时提供半星、只读、禁用、可清空等多种状态控制。在 Vant 中组件以插件形式注册。通过app.use进行全局注册import { createApp } from vue; import { Rate } from vant; const app createApp(); app.use(Rate);注册完成后即可在模板中使用van-rate标签van-rate这一全局组件名由 index.ts 中的declare module vue全局类型声明提供。更多注册方式如按需引入、自动导入可参考仓库中的进阶用法文档 advanced-usage.zh-CN.md。二、基础用法v-model 双向绑定Rate 的核心数据流通过v-model完成绑定的值即为当前评分van-rate v-modelvalue /import { ref } from vue; export default { setup() { const value ref(3); return { value }; }, };从源码看modelValue的默认值为0Rate.tsx 中modelValue: makeNumberProp(0)且组件通过useCustomFieldValue将其接入表单体系因此嵌套在van-field等表单场景中时也能与表单校验、提交逻辑协同工作。三、自定义图标与样式3.1 自定义图标通过icon设置选中时的图标void-icon设置未选中时的图标。图标名称直接复用 Icon 组件的name属性规则可以传入内置图标名或图片链接van-rate v-modelvalue iconlike void-iconlike-o /默认情况下选中图标为star、未选中为star-o源码 Rate.tsx 与 Rate.tsx 中的makeStringProp(star)与makeStringProp(star-o)。在自定义图标场景中常见做法是使用点赞主题的like/like-o图标对。3.2 自定义尺寸与颜色size控制图标大小color控制选中颜色void-color控制未选中颜色gutter控制图标间距van-rate v-modelvalue :size25 color#ffd21e void-iconstar void-color#eee /size、gutter的类型为number | string默认单位为px也可以传2rem等任意合法 CSS 长度测试用例 index.spec.ts 验证了传入2rem时图标font-size被正确设置颜色默认值分别为#ee0a24Vant 品牌红与#c8c9cc灰色实际渲染时通过Icon组件的color属性下发。3.3 自定义类名前缀icon-prefix用于指定图标类名前缀默认van-icon与 Icon 组件的class-prefix属性语义一致适用于引用了自定义字体图标库、需要替换类名前缀的场景。四、半星与只读小数显示4.1 半星选择设置allow-half后用户可以选中半星van-rate v-modelvalue allow-half /import { ref } from vue; export default { setup() { const value ref(2.5); return { value }; }, };半星的实现原理值得关注。源码 Rate.tsx 中的getRateStatus函数决定了每一颗星的状态当value index时为full满星权重为 1当value 0.5 index且开启allow-half且非只读时为half半星权重为 0.5只读且开启allow-half时支持更精细的小数权重通过Math.round((value - index 1) * 10 ** 10) / 10 ** 10计算消除浮点误差。渲染时半星通过双层图标实现底层渲染空心图标上层叠加一个宽度按小数比例裁剪的实心图标style{{ width: item.value em }}见 Rate.tsx配合 index.less 中__icon--half的position: absolute; overflow: hidden样式实现裁剪效果。4.2 只读状态显示任意小数设置readonly与allow-half后组件可以展示任意小数评分结果常用于展示服务端返回的平均分如 4.3、3.7van-rate v-modelvalue readonly allow-half /import { ref } from vue; export default { setup() { const value ref(3.3); return { value }; }, };测试用例 index.spec.ts 验证了modelValue 3.3时半星图标宽度被精确设置为0.3em。五、自定义数量通过count属性可以设置评分总数即图标个数类型为number | string默认5van-rate v-modelvalue :count6 /源码中count: makeNumericProp(5)同时接受数字与字符串渲染时通过Array(props.count)生成对应数量的图标Rate.tsx测试用例 index.spec.ts 验证了传入字符串4也能正确渲染 4 个图标。六、可清空再次点击归零当clearable属性设置为truev4.6.0 起提供再次点击当前相同的值时评分会被重置为0van-rate v-modelvalue clearable /其判定逻辑在 Rate.tsx 的onClickItem中仅当clearable开启、当前操作被识别为轻点touch.isTap即未发生拖拽位移见 use-touch.ts 中的TAP_OFFSET判断且点击位置对应的值与当前值相同时才将值重置为 0从而避免滑动过程中误触发清空。七、禁用与只读禁用disabled完全禁止交互图标以禁用色展示鼠标样式变为not-allowedvan-rate v-modelvalue disabled /只读readonly仅禁止修改评分视觉上仍为正常颜色鼠标样式为默认van-rate v-modelvalue readonly /源码中unselectable readonly || disabled统一屏蔽了选择行为禁用时还会移除图标的tabindex并设置aria-disabled保持无障碍语义Rate.tsx。样式上index.less 为禁用与只读分别定义了cursor: not-allowed与cursor: default。八、监听 change 事件评分变化时触发change事件回调参数为当前分值van-rate v-modelvalue changeonChange /import { ref } from vue; import { showToast } from vant; export default { setup() { const value ref(3); const onChange (value) showToast(current value: value); return { value, onChange, }; }, };从事件机制看组件同时发射update:modelValue与change两个事件Rate.tsx 中的select函数。测试用例 index.spec.ts 验证了点击第 4 个图标时两者各触发一次且参数为4当点击值与当前值相同时非 clearable 场景不触发任何事件禁用状态下同样不触发。九、API 完整参考9.1 Props 一览参数说明类型默认值v-model当前分值number-count图标总数number | string5size图标大小默认单位为pxnumber | string20pxgutter图标间距默认单位为pxnumber | string4pxcolor选中时的颜色string#ee0a24void-color未选中时的颜色string#c8c9ccdisabled-color禁用时的颜色string#c8c9ccicon选中时的图标名称或图片链接等同于 Icon 组件的name属性stringstarvoid-icon未选中时的图标名称或图片链接等同于 Icon 组件的name属性stringstar-oicon-prefix图标类名前缀等同于 Icon 组件的class-prefix属性stringvan-iconallow-half是否允许半选booleanfalseclearablev4.6.0是否允许再次点击后清除booleanfalsereadonly是否为只读状态只读状态下无法修改评分booleanfalsedisabled是否禁用评分booleanfalsetouchable是否可以通过滑动手势选择评分booleantrue补充说明各属性的源码级细节Rate.tsx 中的rateProps定义modelValue使用makeNumberProp(0)默认 0size、gutter使用numericProp[Number, String]兼容数字与带单位的字符串icon、void-icon、icon-prefix使用makeStringProp其中iconPrefix默认为undefined由 Icon 组件回落至van-icontouchable使用truthPropBoolean类型且默认true这是 Vant 中默认为真的布尔属性的标准写法见 utils/props.ts。9.2 Events事件名说明回调参数change当前分值变化时触发的事件currentValue: number9.3 类型定义组件导出RateProps类型便于在 TypeScript 项目中做 props 类型约束import type { RateProps } from vant;同时 types.ts 导出了RateThemeVars类型对应下方主题定制中的 5 个 CSS 变量可用于 ConfigProvider 的主题变量类型推断。十、主题定制CSS 变量组件提供以下 CSS 变量可通过 ConfigProvider 组件见 config-provider/README.md在全局或局部进行主题定制名称默认值描述--van-rate-icon-size20px图标大小--van-rate-icon-guttervar(--van-padding-base)图标间距--van-rate-icon-void-colorvar(--van-gray-5)未选中颜色--van-rate-icon-full-colorvar(--van-danger-color)选中颜色--van-rate-icon-disabled-colorvar(--van-gray-5)禁用颜色这些变量的默认值定义在 index.less 的:root, :host块中并与rateProps中对应的 props 一一映射size对应--van-rate-icon-size作用于图标的font-sizegutter对应图标padding-rightcolor/void-color/disabled-color分别对应--van-rate-icon-full-color/--van-rate-icon-void-color/--van-rate-icon-disabled-color。值得留意的是props 传入的显式值优先级高于 CSS 变量因此两者可以配合使用用 CSS 变量做全局主题用 props 做单组件覆盖。十一、源码级原理剖析滑动评分与无障碍Rate 不仅支持点击评分默认还支持在图标上横向滑动连续改分touchable默认true。其核心链路如下区域映射updateRanges触摸开始时通过useRect测量组件容器与每个图标的几何位置生成ranges数组。开启allow-half时每个图标被拆分为左半分数index 0.5与右半分数index 1两个区域从而实现半星的精确命中Rate.tsx。坐标换算getScoreByPosition滑动过程中根据手指的clientX / clientY反查命中的ranges区域得到对应分数当手指移出组件垂直范围时还会就近映射到最近一行的图标区域保证横向滑动体验的连续性Rate.tsx。事件绑定touchmove监听使用useEventListener并显式关闭 passive 模式以避免 Chrome 对默认行为阻止的警告滑动仅在touch.isHorizontal()横向位移占主导且非轻点!isTap时触发评分避免与页面纵向滚动冲突Rate.tsx、use-touch.ts。测试用例 index.spec.ts 通过triggerDrag模拟横向拖拽验证了默认模式下连续触发[1, 2, 2, 4]的评分序列以及allow-half模式下触发[1, 1.5, 2, 4]的半星序列touchable: false时拖拽不产生任何事件。此外组件还内置了完整的无障碍支持容器带有roleradiogroup每个图标为roleradio并设置了aria-checked、aria-setsize、aria-posinset、aria-disabled、aria-readonly等属性Rate.tsx键盘用户可以通过 Tab 聚焦并操作评分。十二、完整示例仓库中的 demo/index.vue 汇总了上述全部场景基础用法、自定义图标、自定义样式、半星、自定义数量、可清空、禁用、只读、只读小数、change 事件并配套快照测试 demo.spec.ts。实际开发中可直接参照该文件组织自己的评分交互页面。总结Rate 组件以v-model为核心数据流通过count、size、color、icon、allow-half、clearable、readonly、disabled、touchable等十余个属性覆盖了评分场景的全部常见需求并提供change事件与 5 个 CSS 变量支撑交互反馈与主题定制。从源码实现看其半星渲染采用双层图标宽度裁剪方案滑动评分基于触摸坐标到图标区域的精确映射同时兼顾了表单集成与无障碍语义是一个麻雀虽小、五脏俱全的移动端评分方案可直接在 Vant 项目中开箱即用。【免费下载链接】vantA lightweight, customizable Vue UI library for mobile web apps.项目地址: https://gitcode.com/GitHub_Trending/va/vant创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考