评分 - Semi Design Next

代码演示

如何引入

<script setup lang="ts">
    import { Rating } from '@fibrous/semi-ui-vue';
</script>

基本用法

最简单的用法，支持两种尺寸 default， small。

支持传入 number 类型自定义尺寸。具体可以参考自定义

代码

<script setup lang="ts">
    import { Rating } from '@fibrous/semi-ui-vue';
</script>

<template>
    <div>
        <Rating :defaultValue="5" />
        <br />
        <br />
        <Rating :defaultValue="5" size="small" />
    </div>
</template>

半星

通过设置 allowHalf 属性可以支持选择半星。 allowHalf 属性支持展示除0.5以外的小数。

代码

<script setup lang="ts">
    import { Rating } from '@fibrous/semi-ui-vue';
</script>

<template>
    <div>
        <Rating allowHalf :defaultValue="3.5" />
        <br />
        <Rating allowHalf :defaultValue="3.65" disabled />
    </div>
</template>

只读

通过设置 disabled 属性将无法进行交互。

代码

<script setup lang="ts">
    import { Rating } from '@fibrous/semi-ui-vue';
</script>

<template>
    <Rating :defaultValue="3" disabled />
</template>

点击清除

通过设置 allowClear 属性允许再次点击时清除数值，默认为 true。

允许再次点击清除

禁止再次点击清除

代码

<script setup lang="ts">
    import { Rating } from '@fibrous/semi-ui-vue';
</script>

<template>
    <div>
        <span>允许再次点击清除</span>
        <br />
        <Rating allowClear :defaultValue="3" />
        <br />
        <br />
        <span>禁止再次点击清除</span>
        <br />
        <Rating :allowClear="false" :defaultValue="3" />
    </div>
</template>

文案展现

给评分组件加上文案展示。

你对获得的帮助是否满意：

代码

<script setup lang="ts">
    import { ref } from 'vue';
    import { Rating } from '@fibrous/semi-ui-vue';

    const value = ref(0);
    const desc = ['极差', '较差', '一般', '满意', '非常满意'];
</script>

<template>
    <div>
        <span>
            你对获得的帮助是否满意：
            <span v-if="value">{{ desc[value - 1] }}</span>
        </span>
        <br />
        <Rating v-model="value" :tooltips="desc" />
    </div>
</template>

自定义

自定义评分字符、个数及尺寸。
自定义尺寸需要配合自定义的字符才能生效。

自定义字符使用 #character 插槽。

代码

<script setup lang="ts">
    import { IconLikeHeart } from '@fibrous/semi-icons-vue';
    import { Rating } from '@fibrous/semi-ui-vue';
</script>

<template>
    <div>
        <Rating :defaultValue="3" :style="{ color: 'red' }">
            <template #character>
                <IconLikeHeart size="extra-large" />
            </template>
        </Rating>
        <br />
        <br />
        <Rating allowHalf :defaultValue="3" :size="48" :style="{ color: 'red' }">
            <template #character>
                <IconLikeHeart :style="{ fontSize: '48px' }" />
            </template>
        </Rating>
        <br />
        <br />
        <Rating :defaultValue="3" :size="18">
            <template #character>赞</template>
        </Rating>
        <br />
        <br />
        <Rating :count="10" :defaultValue="6" />
    </div>
</template>

API参考

Props

属性	说明	类型	默认值
modelValue	当前值，配合 v-model 使用；传入后由该值决定显示，变回 undefined 时回到 defaultValue 并转为非受控。	`number`	`undefined`
defaultValue	非受控时的初始值。	`number`	`semiDefault("Rating", "defaultValue", 0)`
count	星的总数。	`number`	`semiDefault("Rating", "count", 5)`
allowHalf	是否允许半选。	`boolean`	`semiDefault("Rating", "allowHalf", false)`
allowClear	是否允许再次点击后清除。	`boolean`	`semiDefault("Rating", "allowClear", true)`
disabled	只读，无法进行交互，也无法获得焦点。	`boolean`	`semiDefault("Rating", "disabled", false)`
size	尺寸，可选 default、small，也可传入 number 自定义尺寸。	`number \| "small" \| "default"`	`semiDefault("Rating", "size", "default")`
tooltips	每一项的提示信息。	`string[]`	`semiGlobalDefault("Rating", "tooltips")`
prefixCls	组件的样式类名前缀。	`string`	`semiDefault("Rating", "prefixCls", cssClasses.PREFIX)`
autofocus	挂载时自动获取焦点。	`boolean`	`semiGlobalDefault("Rating", "autofocus")`
preventScroll	指示浏览器是否应滚动文档以显示新聚焦的元素，作用于组件内的聚焦。	`boolean`	`semiGlobalDefault("Rating", "preventScroll")`
ariaLabel	radiogroup 的可访问名称；缺省时名称概括当前取值。	`string`	`semiGlobalDefault("Rating", "ariaLabel")`

Events

事件	说明	回调参数
update:modelValue	选择变化时触发，供 v-model 回写。	`[value: number]`
change	选择变化时触发，参数为新的值。	`[value: number]`
hoverChange	指针经过时数值变化；指针移出或点击清除时收到 undefined。	`[value: number \| undefined]`
click	点击星或按 Enter、Space 选中时触发，参数为事件与星的序号；会遮住根元素上的原生 click 监听。	`[event: MouseEvent \| KeyboardEvent, index: number]`
focus	焦点进入整个评分组件时触发，在星之间移动不触发。	`[event: FocusEvent]`
blur	焦点离开整个评分组件时触发。	`[event: FocusEvent]`
keydown	仅在方向键使值移动时触发。	`[event: KeyboardEvent]`

Slots

插槽	说明	作用域参数
character	每颗星中绘制的字符；只含文本时，该文本作为各星可访问名称与整组摘要的单位，否则用语言包的单位。	`any`

Exposes

名称	说明	类型
focus	聚焦 Tab 会到达的 radio，与 autofocus 的落点相同；disabled 时无效果。	`Type`
blur	让评分内获得焦点的元素失焦；焦点不在评分内或 disabled 时无效果。	`Type`

class、style 与原生属性（id、aria-labelledby、aria-invalid、aria-required、data-* 等）经 attrs 落在 role="radiogroup" 的根元素上；tabindex 与 name 被丢弃，列表固定为 tabindex="-1"，只有选中的 radio 可以 Tab 到达。声明了 click 事件后，@click 不再作为根元素的原生点击监听。

Accessibility

ARIA

Rating 具有 aria-checked 表示当前是否选中，aria-posinset 表示在列表的位置，aria-setsize 表示列表的长度。
Semi 支持自定义 Rating 的语义:
- aria-label 作为 radiogroup 的可访问名称，原样使用；
- 自定义字符是纯文本时（React 为 string 类型的 character，Vue 为只含文本的 #character 插槽），各星项名称以这段文本为单位，否则用语言包默认的单位；
- 两者互不影响，可以同时传入。

键盘和焦点

Rating 的初始焦点设置（Tab 停靠点，按 APG radio group）：
- 若 Rating 有选择项，初始焦点设置在最后一个选择项上（如：有 3 颗星被点亮，则初始焦点设置在第三颗被点亮的星上）；
- 若 Rating 没有选择项（值为 0），初始焦点落在表示 0 星的空星 radio 上；
- 当前值不对应任何 radio 时（如未开启 allowHalf 时值为 2.5），第一个 radio 是 Tab 停靠点，键盘仍可进入；此时方向键选中与该值相邻的 radio（2.5 时右箭头得 3，左箭头得 2）。
一个 Rating 组上，可以通过 下箭头 或 右箭头 选中下一个星（值增加，从最后一颗星之后回到 0），上箭头 或 左箭头 选中上一个星（值减小，从 0 回到最后一颗星）；RTL 下只镜像左右方向键，上下方向键不变；
- 用户设置了 allowHalf 属性，按方向键只选中或取消选中半颗星；
Space 选中获得焦点的未选中星；在已选中的星上按 Space 不会清除，清除使用 Enter 或点击（受 allowClear 控制）；
评分列表本身不是 Tab 停靠点，Rating 作为 Tooltip 的触发器时也不会多出一个 Tab 停靠点；
调用实例的 focus() 聚焦的是 Tab 会到达的 radio；
配置 tooltips 时，键盘聚焦星级会显示该星的提示，并通过 aria-describedby 关联；
disabled的 Rating 无法被获取到焦点。

设计变量

下表是组件内部的 Sass 变量，不能覆写。定制样式请覆写 --semi-* CSS 变量（见 Design Token 页），或写不分层的 CSS 规则。

Sass 变量	值	用法
$transition_duration-rating-color	var(--semi-transition_duration-none)	评分-背景色-动画持续时间
$transition_function-rating-color	var(--semi-transition_function-easeIn)	评分-背景色-过渡曲线
$transition_delay-rating-color	var(--semi-transition_delay-none)	评分-背景色-延迟时间
$transform_scale-rating	var(--semi-transform_scale-none)	评分-变大
$color-rating-icon-default	var(--semi-yellow-5)	评分图标按钮颜色 - 已填
$color-rating-bg-default	var(--semi-color-fill-0)	评分图标按钮颜色 - 未填
$color-rating-outline-focus	$color-focus-ring	聚焦轮廓颜色
$spacing-rating-margin	0px	整体外边距
$spacing-rating-padding	0px	整体内边距
$spacing-rating_item-marginRight	6px	评分项右侧外边距
$width-rating_item_small	16px	小尺寸评分项宽度
$font-rating_item_small-fontSize	$width-rating_item_small	小尺寸评分项文本字体大小
$width-rating_item_default	24px	评分项宽度
$font-rating_item_default-fontSize	$width-rating_item_default	评分项文本字体大小
$width-rating-outline-focus	$width-focus-ring	聚焦轮廓宽度