BootstrapVue 星级评分组件 `<b-form-rating>` 完全指南:交互、只读展示、样式定制与无障碍支持
BootstrapVue 星级评分组件 <b-form-rating> 完全指南:交互、只读展示、样式定制与无障碍支持
<b-form-rating>是 BootstrapVue 提供的自定义星级评分表单控件,既可用于用户输入评分值,也可用于展示聚合后的平均评分。本文以 src/components/form-rating/README.md 为主体,结合 form-rating.js 源码与 form-rating.spec.js 测试用例,系统讲解它的两种工作模式(交互 / 只读)、全部样式与行为 props、表单提交、国际化与键盘无障碍实现。读完本文,你将能独立完成评分录入、只读均分展示、主题色定制、输入组集成与 RTL 场景适配等实战需求。
概述:两种核心工作模式
<b-form-rating> 的取值区间为 1 到允许的星星数量(默认 5 颗星,最少 3 颗星)。由于组件复用了 Bootstrap 的 form-control 样式类,它可以轻松嵌入 输入组(input group)中使用。
组件有两大模式:
- 交互模式(input mode):用户可以从
1到星星总数(默认5)之间以整数增量选择评分值。 - 只读模式(readonly mode):用于展示聚合/平均评分,支持半星(half star) 显示。
交互模式(输入)
<template>
<div>
<b-form-rating v-model="value"></b-form-rating>
<p class="mt-2">Value: {{ value }}</p>
</div>
</template>
<script>
export default {
data() {
return {
value: null
}
}
}
</script>
<!-- b-form-rating.vue -->
初始 value 为 null(未评分状态)。从源码看,form-rating.js 的 data() 中会将传入的 value 用 toFloat 转成浮点数,再通过 clampValue(value, 0, stars) 钳制在 0 到星星总数之间,保证任何外部赋值都不会越界。点击某颗星时,内部子组件 BVFormRatingStar 会触发 selected 事件,由主组件把值写入 localValue 并通过 change 事件同步到 v-model。
只读模式(展示聚合评分)
<template>
<div>
<b-form-rating v-model="value" readonly></b-form-rating>
<p class="mt-2">Value: {{ value }}</p>
</div>
</template>
<script>
export default {
data() {
return {
value: 2.567
}
}
}
</script>
<!-- b-form-rating-non-interactive.vue -->
只读模式下组件仍然可聚焦(focusable),但不可交互,非常适合展示平均分等聚合数值。源码中 isInteractive 计算属性直接由 !this.disabled && !this.readonly 得出,onKeydown 与 onSelected 都会先检查 isInteractive 再处理事件,从机制上保证了只读/禁用状态下用户无法改动评分。
样式定制
主题色变体(variant)与自定义颜色(color)
通过 variant prop 可以一键应用 Bootstrap 主题色变体(默认使用表单控件默认文本色):
<template>
<div>
<b-form-rating v-model="value" variant="warning" class="mb-2"></b-form-rating>
<b-form-rating v-model="value" variant="success" class="mb-2"></b-form-rating>
<b-form-rating v-model="value" variant="danger" class="mb-2"></b-form-rating>
<b-form-rating v-model="value" variant="primary" class="mb-2"></b-form-rating>
<b-form-rating v-model="value" variant="info" class="mb-2"></b-form-rating>
<p class="mt-2">Value: {{ value }}</p>
</div>
</template>
<script>
export default {
data() {
return {
value: 3
}
}
}
</script>
<!-- b-form-rating-variant.vue -->
如果需要自定义颜色,使用 color prop,它接受标准 CSS 颜色名、HEX 值(#...)或 RGB/RGBA(rgb(...)/rgba(...)):
<template>
<div>
<b-form-rating v-model="value" color="indigo" class="mb-2"></b-form-rating>
<b-form-rating v-model="value" color="#ff00ff" class="mb-2"></b-form-rating>
<b-form-rating v-model="value" color="rgb(64, 192, 128)" class="mb-2"></b-form-rating>
<b-form-rating v-model="value" color="rgba(64, 192, 128, 0.75)" class="mb-2"></b-form-rating>
<p class="mt-2">Value: {{ value }}</p>
</div>
</template>
<script>
export default {
data() {
return {
value: null
}
}
}
</script>
<!-- b-form-rating-color.vue -->
注意事项:
colorprop 的优先级高于variantprop;variant会转化为图标上的text-{variant}工具类(utility class)。
这一点在源码中得到印证:renderIcon() 中仅当既未禁用也没有设置 color 时才会把 variant 传给图标(form-rating.js),而每颗星的根元素上通过内联 style: { color } 应用自定义颜色(form-rating.js)。测试用例 has icons with variant class when \variant` set也验证了.bi-star图标带有text-primary` 类(form-rating.spec.js)。
星星数量(stars)
默认 5 颗星,可通过 stars prop 修改,最少为 3 颗:
<template>
<div>
<label for="rating-10">Rating with 10 stars:</label>
<b-form-rating id="rating-10" v-model="value10" stars="10"></b-form-rating>
<p class="mt-2">Value: {{ value10 }}</p>
<label for="rating-7">Rating with 7 stars:</label>
<b-form-rating id="rating-7" v-model="value7" stars="7"></b-form-rating>
<p class="mt-2">Value: {{ value7 }}</p>
</div>
</template>
<script>
export default {
data() {
return {
value10: null,
value7: null,
}
}
}
</script>
<!-- b-form-rating-stars.vue -->
源码中 MIN_STARS = 3、DEFAULT_STARS = 5 两个常量清晰定义了下限与默认值,computeStars() 通过 mathMax(MIN_STARS, toInteger(stars, DEFAULT_STARS)) 保证传入值小于 3 时也会被强制提升到 3(form-rating.js);同时 stars prop 的 validator 要求 toInteger(value) >= MIN_STARS(form-rating.js)。测试中设置 stars: '10' 后渲染出 10 颗星(form-rating.spec.js)。
显示数值(show-value)与精度(precision)
默认不显示当前数值。设置 show-value 为 true 即可显示;precision 控制小数位数,在只读模式下展示聚合/平均评分时尤其有用:
<template>
<div>
<b-form-rating v-model="value" show-value></b-form-rating>
<p class="mt-2">Value: {{ value }}</p>
</div>
</template>
<script>
export default {
data() {
return {
value: 4
}
}
}
</script>
<!-- b-form-rating-value.vue -->
设置精度:
<template>
<div>
<b-form-rating v-model="value" readonly show-value precision="2"></b-form-rating>
<p class="mt-2">Value: {{ value }}</p>
</div>
</template>
<script>
export default {
data() {
return {
value: 3.555
}
}
}
</script>
<!-- b-form-rating-value-precision.vue -->
源码中 computedRating 会先用 value.toFixed(precision) 进行四舍五入再钳制到 <a href="https://link.gitcode.com/i/e365e9f833edab11b9d72c018e08e554" target="_blank">0, stars](默认精度为 3 位),而 formattedRating 则通过 Intl.NumberFormat 结合 locale 格式化显示值([form-rating.js)。测试用例验证了 precision: 2 时 3.5 显示为 3.50、1.236 显示为 1.24(form-rating.spec.js)。
显示最大评分值(show-value-max)
2.13.0+ 新增。在 show-value 基础上再设置 show-value-max 为 true,可同时显示最大可能评分:
<template>
<div>
<b-form-rating
v-model="value"
readonly
show-value
show-value-max
precision="2"
></b-form-rating>
<p class="mt-2">Value: {{ value }}</p>
</div>
</template>
<script>
export default {
data() {
return {
value: 3.555
}
}
}
</script>
<!-- b-form-rating-value-max.vue -->
从 formattedRating 的实现可以看到,开启后显示格式为 `${value}/${stars}`,当值为 null 时左侧显示 -,例如 3.50/5、-/5(form-rating.js)。测试断言 3.50/5 与 -/5 两种输出(form-rating.spec.js)。
尺寸控制(size)
通过 size prop 设置 'sm' 或 'lg' 即可切换小/大尺寸:
<template>
<div>
<label for="rating-sm">Small rating</label>
<b-form-rating id="rating-sm" v-model="value" size="sm"></b-form-rating>
<label for="rating-md" class="mt-3">Default rating (medium)</label>
<b-form-rating id="rating-md" v-model="value"></b-form-rating>
<label for="rating-lg" class="mt-3">Large rating</label>
<b-form-rating id="rating-lg" v-model="value" size="lg"></b-form-rating>
<p class="mt-2">Value: {{ value }}</p>
</div>
</template>
<script>
export default {
data() {
return {
value: null
}
}
}
</script>
<!-- b-form-rating-size.vue -->
size 来自 form-size.js 混入:sizeFormClass 计算属性会生成 form-control-{size} 类(如 form-control-sm、form-control-lg),与 Bootstrap v4 表单控件的尺寸类保持一致。
内联模式(inline)
默认 <b-form-rating> 占据父容器 100% 宽度。设置 inline 为 true 后组件只占内容所需宽度:
<template>
<div>
<label for="rating-inline">Inline rating:</label>
<b-form-rating id="rating-inline" inline value="4"></b-form-rating>
</div>
</template>
<!-- b-form-rating-inline.vue -->
渲染时根元素会由 d-flex 切换为 d-inline-flex,样式文件 _form-rating.scss 中 &.d-inline-flex { width: auto; } 将宽度收窄为内容宽度。
无边框(no-border)
默认组件带标准 Bootstrap form-control 边框,设置 no-border 为 true 可去掉边框:
<template>
<div>
<label for="rating-sm-no-border">Small rating with no border</label>
<b-form-rating id="rating-sm-no-border" v-model="value" no-border size="sm"></b-form-rating>
<label for="rating-md-no-border" class="mt-3">Default rating (medium) with no border</label>
<b-form-rating id="rating-md-no-border" v-model="value" no-border></b-form-rating>
<label for="rating-lg-no-border" class="mt-3">Large rating with no border</label>
<b-form-rating id="rating-lg-no-border" v-model="value" no-border size="lg"></b-form-rating>
<p class="mt-2">Value: {{ value }}</p>
</div>
</template>
<script>
export default {
data() {
return {
value: null
}
}
}
</script>
<!-- b-form-rating-no-border.vue -->
注意事项:
- 出于无障碍考虑,无论是否设置
no-border,组件获得焦点时都会显示焦点环(focus ring)。
实现上 no-border 只是为根元素追加 border-0 类(form-rating.js);而聚焦时的放大反馈由 _form-rating.scss 中的 &:focus:not(:hover) .b-rating-star.focused 规则提供(图标放大到 1.5 倍),与 no-border 无关。
禁用(disabled)
如果需要在用户提交附加信息之前禁止评分,设置 disabled 为 true 即可禁用一切交互:
<template>
<div>
<label for="rating-disabled">Disabled rating</label>
<b-form-rating id="rating-disabled" value="2.75" disabled></b-form-rating>
</div>
</template>
<!-- b-form-rating-disabled.vue -->
源码中禁用态不仅让 isInteractive 变为 false,还会:根元素 tabindex 置为 null、设置 disabled 属性与 aria-disabled="true";watch.disabled 会在被禁用时清除 hasFocus 并调用 blur()(form-rating.js)。样式上禁用态使用 $input-disabled-bg 背景与 $text-muted 文字色(_form-rating.scss)。
只读(readonly)
只读评分保持可聚焦但不可交互,适合展示聚合/平均评分。分数值被允许,当 value 不是整数时会出现半星图标(半星判定阈值为 0.5):
<template>
<div>
<label for="rating-readonly">Readonly rating</label>
<b-form-rating
id="rating-readonly"
value="3.6536"
readonly
show-value
precision="3"
></b-form-rating>
</div>
</template>
<!-- b-form-rating-readonly.vue -->
半星判定逻辑位于子组件 BVFormRatingStar 的 type 计算中:rating >= star ? 'full' : rating >= star - 0.5 ? 'half' : 'empty'(form-rating.js)。测试用例验证了 value = 3.5 时第 4 颗星为 b-rating-star-half(form-rating.spec.js)。
清除按钮(show-clear)
设置 show-clear 为 true 可显示清除图标,点击后值被置为 null:
<template>
<div>
<b-form-rating v-model="value" show-clear show-value></b-form-rating>
<p class="mt-2">Value: {{ value }}</p>
</div>
</template>
<script>
export default {
data() {
return {
value: 2.5
}
}
}
</script>
<!-- b-form-rating-clear.vue -->
注意事项:
- 当设置
readonly或disabled时,清除图标不会显示。
源码中清除图标仅在 showClear && !disabled && !readonly 时渲染,点击后调用 onSelected(null) 把值清空(form-rating.js)。清除按钮也会占用一个 .b-rating-star 位置,因此测试中开启 show-clear 后星星总数变为 6 个(清除 + 5 颗星),点击清除按钮后 change 事件携带 null(form-rating.spec.js)。此外开启 show-clear 时键盘最小值从 1 变为 0(aria-valuemin 与键盘逻辑中的 min 均为 showClear ? 0 : 1)。
自定义图标(Icons)
默认使用 Bootstrap Icons 的 'star'、'star-half'、'star-fill',以及清除按钮用的 'x'。可通过 icon-empty、icon-half、icon-full、icon-clear props 指定其他 Bootstrap Icon 的 kebab-case 名称,前提是对应图标组件已在本地或全局注册:
<template>
<div>
<b-form-rating
icon-empty="heart"
icon-half="heart-half"
icon-full="heart-fill"
icon-clear="slash-circle"
show-clear
variant="danger"
></b-form-rating>
</div>
</template>
<!-- b-form-rating-icons.vue -->
替代方案: 也可以通过 'icon-empty'、'icon-half'、'icon-full'、'icon-clear' 四个作用域插槽(scoped slots) 提供完全自定义的内容。
四个插槽的作用域均暴露 { variant, disabled, readonly } 三个字段,便于根据状态渲染不同的图标(见 package.json)。源码中图标 props 默认值分别为 'star'、'star-fill'、'star-half'、'x'(form-rating.js),主组件默认注册了 BIconStar、BIconStarHalf、BIconStarFill、BIconX 四个内置图标(form-rating.js);子组件渲染时优先取作用域插槽,未提供时回退到默认图标函数(form-rating.js)。
表单提交(Form submission)
如果希望通过标准表单提交方式提交评分值,设置 name prop 为表单字段名即可。组件会生成一个隐藏 input,其值为当前值(无值时为空字符串):
<b-form-rating name="rating" v-model="value"></b-form-rating>
从源码看,当 name 存在时,根元素内会追加一个 type="hidden" 的 <input>,其 value 为 isNull(localValue) ? '' : computedRating,并透传 name 与 form(支持关联指定 <form> 的 form 属性)(form-rating.js)。测试用例验证了设置 name: 'foo'、value: 3.5 时隐藏 input 的 type、name、value 分别为 hidden、foo、3.5(form-rating.spec.js)。
在输入组中使用(Input groups)
以下示例演示把 <b-form-rating> 放进输入组,配合前置清除按钮与后置数值显示:
<template>
<div>
<b-input-group>
<b-input-group-prepend>
<b-button @click="value = null">Clear</b-button>
</b-input-group-prepend>
<b-form-rating v-model="value" color="#ff8800"></b-form-rating>
<b-input-group-append>
<b-input-group-text class="justify-content-center" style="min-width: 3em;">
{{ value }}
</b-input-group-text>
</b-input-group-append>
</b-input-group>
</div>
</template>
<script>
export default {
data() {
return {
value: null
}
}
}
</script>
<!-- b-form-rating-input-group.vue -->
由于组件根元素带 form-control 类(渲染类为 b-rating form-control align-items-center),它能与输入组其他元素自然对齐,无需额外适配。
国际化(Internationalization)
指定 locale 后,开启 show-value 时显示的数值将使用浏览器默认 locale 格式化。通过 locale prop 可改为首选 locale,或传入首选顺序排列的 locale 数组(最优先的在前)。这会影响可选的数值显示,以及组件的从左到右/从右到左(RTL)方向:
<template>
<div>
<b-form-select v-model="locale" :options="locales" class="mb-2"></b-form-select>
<b-form-rating v-model="value" :locale="locale" show-value precision="1"></b-form-rating>
<p class="mt-2">Value: {{ value }}</p>
</div>
</template>
<script>
export default {
data() {
return {
value: 3.5,
locale: 'en-US',
locales: [
{ text: 'English US (en-US)', value: 'en-US' },
{ text: 'French (fr)', value: 'fr' },
{ text: 'Persian (fa)', value: 'fa'},
{ text: 'Arabic Egyptian (ar-EG)', value: 'ar-EG' }
]
}
}
}
</script>
<!-- b-form-rating-i18n.vue -->
实现上,computedLocale 使用 new Intl.NumberFormat(locales).resolvedOptions().locale 解析最终 locale;isRTL 则通过工具函数 locale.js 中的 isLocaleRTL() 判断——该工具内置了 ar、fa、he、ur 等 RTL 语言清单,并会剥离区域修饰符后比较。RTL 判定结果同时作用于根元素 dir 属性(rtl/ltr)与键盘左右方向键的行为反转。
实现说明(Implementation notes)
评分控件使用 Bootstrap v4 的 form-control*、d-*(display)、border-* 与 text-{variant} 类,以及 BootstrapVue 自定义 CSS 完成整体样式。
控件的根元素是一个 <output> 元素,这样可以让 <label> 元素通过 for 属性与它正确关联。测试用例 has expected default structure 断言根标签为 OUTPUT,并验证了默认渲染类 b-rating、d-flex、form-control,默认 5 颗星、role="slider"、aria-valuemin="1"、aria-valuemax="5"(form-rating.spec.js)。
无障碍与键盘操作(Accessibility)
对屏幕阅读器用户而言,<b-form-rating> 表现为一个 slider 类型的输入。根元素上设置了完整的 ARIA 属性:role="slider"、aria-valuemin(有清除按钮时为 0,否则为 1)、aria-valuemax(星星总数)、aria-valuenow(当前评分)、aria-live="off"、aria-disabled 与 aria-readonly(form-rating.js)。数值显示元素带 aria-hidden="true",避免屏幕阅读器重复朗读。
键盘导航用于选择评分值,行为与原生 range 输入一致:
- Left 或 Down:评分值减
1 - Right 或 Up:评分值加
1 - 当
locale解析为从右到左的语言时,Left 与 Right 的行为会互换
键盘处理的核心在 onKeydown:仅当 isInteractive 且按键为四个方向键之一时触发,RTL 模式下通过 amountRtl = -1 反转左右键方向;值会被钳制在 <a href="https://link.gitcode.com/i/b9d3966061fafd55507162a755298596" target="_blank">min, stars] 区间(min 在有清除按钮时为 0),并且小于 min 的递减结果会归为 null([form-rating.js)。测试用例 keyboard navigation works 完整验证了方向键增减、上下限钳制、只读/禁用时按键失效,以及 show-clear 时向左降到 null 的行为(form-rating.spec.js)。
组件注册与入口
<b-form-rating> 与别名 <b-rating> 由 index.js 中的 FormRatingPlugin 导出(BRating: BFormRating),可随 BootstrapVue 全量插件安装,也可按需引入 FormRatingPlugin 或单个组件。TypeScript 类型声明见 index.d.ts,其中暴露了 focus() 与 blur() 两个公开方法(通过 idMixin 生成的 safeId() 与 attemptFocus/attemptBlur 工具实现,见 form-rating.js),可用于编程式聚焦管理。
核心 Props 速查表
| Prop | 类型 | 默认值 | 说明 |
|---|---|---|---|
value |
Number/String | null |
评分值(v-model) |
stars |
Number/String | 5 |
星星数量,最小 3 |
variant |
String | — | Bootstrap 主题色变体,生成 text-{variant} 类 |
color |
String | — | 自定义 CSS 颜色(名称/HEX/RGB/RGBA),优先级高于 variant |
show-value |
Boolean | false |
是否显示当前数值 |
show-value-max |
Boolean | false |
是否在数值后追加最大评分(2.13.0+) |
precision |
Number/String | 未定义 | 显示的小数位数 |
size |
String | — | 'sm' / 'lg' 尺寸 |
inline |
Boolean | false |
内联模式,宽度自适应内容 |
no-border |
Boolean | false |
去掉 form-control 边框 |
disabled |
Boolean | false |
禁用交互 |
readonly |
Boolean | false |
只读模式,允许分数值与半星 |
show-clear |
Boolean | false |
显示清除按钮(只读/禁用时不显示) |
icon-empty / icon-half / icon-full / icon-clear |
String | 'star' / 'star-half' / 'star-fill' / 'x' |
自定义 Bootstrap Icon 名称 |
locale |
String/Array | 浏览器默认 | 数值格式化与 RTL 方向判定 |
name / form |
String | — | 标准表单提交的隐藏 input 关联 |
id |
String | 自动生成 | 根元素 id,可与 <label for> 关联 |
事件方面,组件仅对外发出 change 事件(携带当前评分值)用于驱动 v-model;四个插槽 icon-empty、icon-half、icon-full、icon-clear 均带 { variant, disabled, readonly } 作用域。默认 props 定义集中在 form-rating.js,可供开发时对照参考。