代码演示
如何引入
<script lang="ts">
import { Rating } from '@fibrae/semi-ui-svelte';
</script>基本用法
最简单的用法，支持两种尺寸 default， small。
支持传入 number 类型自定义尺寸。具体可以参考自定义
代码
<script lang="ts">
import { Rating } from '@fibrae/semi-ui-svelte';
</script>
<div>
<Rating value={5} />
<br />
<br />
<Rating size="small" value={5} />
</div>半星
通过设置 allowHalf 属性可以支持选择半星。 allowHalf 属性支持展示除0.5以外的小数。
代码
<script lang="ts">
import { Rating } from '@fibrae/semi-ui-svelte';
</script>
<div>
<Rating allowHalf value={3.5} />
<br />
<Rating allowHalf disabled value={3.65} />
</div>只读
通过设置 disabled 属性将无法进行交互。
代码
<script lang="ts">
import { Rating } from '@fibrae/semi-ui-svelte';
</script>
<Rating disabled value={3} />点击清除
通过设置 allowClear 属性允许再次点击时清除数值，默认为 true。
允许再次点击清除
禁止再次点击清除
禁止再次点击清除
代码
<script lang="ts">
import { Rating } from '@fibrae/semi-ui-svelte';
</script>
<div>
<span>允许再次点击清除</span>
<br />
<Rating allowClear value={3} />
<br />
<br />
<span>禁止再次点击清除</span>
<br />
<Rating allowClear={false} value={3} />
</div>文案展现
给评分组件加上文案展示。
你对获得的帮助是否满意：
代码
<script lang="ts">
import { Rating } from '@fibrae/semi-ui-svelte';
let value = $state<number | undefined>(0);
const desc = ['极差', '较差', '一般', '满意', '非常满意'];
</script>
<div>
<span>
你对获得的帮助是否满意：
{#if value}
<span>{desc[value - 1]}</span>
{/if}
</span>
<br />
<Rating bind:value tooltips={desc} />
</div>自定义
自定义评分字符、个数及尺寸。
自定义尺寸需要配合自定义的字符才能生效。
自定义字符使用 character 属性：传字符串，或用 {#snippet character()}...{/snippet} 传 snippet。
代码
<script lang="ts">
import { IconLikeHeart } from '@fibrae/semi-icons-svelte';
import { Rating } from '@fibrae/semi-ui-svelte';
</script>
<div>
<Rating style="color: red" value={3}>
{#snippet character()}
<IconLikeHeart size="extra-large" />
{/snippet}
</Rating>
<br />
<br />
<Rating allowHalf size={48} style="color: red" value={3}>
{#snippet character()}
<IconLikeHeart style="font-size: 48px" />
{/snippet}
</Rating>
<br />
<br />
<Rating character="赞" size={18} value={3} />
<br />
<br />
<Rating count={10} value={6} />
</div>API参考
Props
| 属性 | 说明 | 类型 | 默认值 |
|---|---|---|---|
| allowClear | 是否允许再次点击后清除。 | boolean | true |
| allowHalf | 是否允许半选。 | boolean | false |
| autofocus | 挂载时自动获取焦点。 | boolean | null | - |
| character | 每颗星中绘制的字符，字符串或 snippet；字符串同时是各星可访问名称与整组摘要的单位，snippet 则用语言包的单位。 | string | Snippet | - |
| count | 星的总数。 | number | 5 |
| disabled | 只读，无法进行交互，也无法获得焦点。 | boolean | false |
| onBlur | 焦点离开整个评分组件时的回调。 | Type(event: FocusEvent) => void | - |
| onChange | 选择变化时的回调，参数为新的值。 | Type(value: number) => void | - |
| onClick | 点击星或按 Enter、Space 选中时的回调，参数为事件与星的序号；会遮住根元素上的原生 click 监听。 | Type(event: MouseEvent | KeyboardEvent, index: number) => void | - |
| onFocus | 焦点进入整个评分组件时的回调，在星之间移动不触发。 | Type(event: FocusEvent) => void | - |
| onHoverChange | 指针经过时数值变化的回调；指针移出或点击清除时收到 undefined。 | Type(value?: number) => void | - |
| onKeyDown | 仅在方向键使值移动时的回调。 | Type(event: KeyboardEvent) => void | - |
| prefixCls | 组件的样式类名前缀。 | string | "semi-rating" |
| preventScroll | 指示浏览器是否应滚动文档以显示新聚焦的元素，作用于组件内的聚焦。 | boolean | - |
| size | 尺寸，可选 default、small，也可传入 number 自定义尺寸。 | 'small' | 'default' | number | "default" |
| tooltips | 每一项的提示信息。 | string[] | - |
| value | 当前值，可用 bind:value 双向绑定。bind:value={get, set} 时完全受控；只传 value 时作为初值，之后由用户操作改变。 | number | - |
Methods
| 方法 | 说明 | 类型 |
|---|---|---|
| blur | 让评分内获得焦点的元素失焦；焦点不在评分内或 disabled 时无效果。 | Type() => void |
| focus | 聚焦 Tab 会到达的 radio，与 autofocus 的落点相同；disabled 时无效果。 | Type() => void |
value 可绑定，没有 defaultValue：只传 value 作为初值，需要读写时用 bind:value，需要拒绝或改写时用函数绑定。class、style（字符串）与原生属性（如 id、aria-labelledby、aria-invalid、aria-required、data-* 等）落在 role="radiogroup" 的根 ul 上；aria-label 原样作为可访问名称，缺省时名称概括当前取值；tabindex 与 name 被丢弃，列表固定为 tabindex="-1"，只有选中的 radio 可以 Tab 到达。
focus()、blur() 经 bind:this 调用：focus() 聚焦 Tab 会到达的 radio（与 autofocus 的落点相同），blur() 只在焦点位于评分内时生效。
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 | 聚焦轮廓宽度 |