BootstrapVue 星级评分组件 `<b-form-rating>` 完全指南:交互、只读展示、样式定制与无障碍支持

原创2026-09-21 20:46:211,645 阅读
文章标签:前端UI组件

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 -->

注意事项:

  • color prop 的优先级高于 variant prop;
  • 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,可供开发时对照参考。

登录后查看全文
bootstrap-vue