评分 - Semi Design Next

代码演示

如何引入

import { Rating } from '@fibrous/semi-ui-react';

基本用法

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

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

代码

import { Rating } from '@fibrous/semi-ui-react';

export default function RatingDemo() {
    return (
        <div>
            <Rating defaultValue={5} />
            <br />
            <br />
            <Rating size="small" defaultValue={5} />
        </div>
    );
}

半星

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

代码

import { Rating } from '@fibrous/semi-ui-react';

export default function RatingDemo() {
    return (
        <div>
            <Rating allowHalf defaultValue={3.5} />
            <br />
            <Rating allowHalf defaultValue={3.65} disabled />
        </div>
    );
}

只读

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

代码

import { Rating } from '@fibrous/semi-ui-react';

export default function RatingDemo() {
    return <Rating disabled defaultValue={3} />;
}

点击清除

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

允许再次点击清除

禁止再次点击清除

代码

import { Rating } from '@fibrous/semi-ui-react';

export default function RatingDemo() {
    return (
        <div>
            <span>允许再次点击清除</span>
            <br />
            <Rating allowClear defaultValue={3} />
            <br />
            <br />
            <span>禁止再次点击清除</span>
            <br />
            <Rating allowClear={false} defaultValue={3} />
        </div>
    );
}

文案展现

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

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

代码

import { useState } from 'react';
import { Rating } from '@fibrous/semi-ui-react';

export default function RatingDemo() {
    const [value, setValue] = useState(0);
    const change = (val: number) => setValue(val);
    const desc = ['极差', '较差', '一般', '满意', '非常满意'];
    return (
        <div>
            <span>
                你对获得的帮助是否满意：
                {value ? <span>{desc[value - 1]}</span> : ''}
            </span>
            <br />
            <Rating tooltips={desc} onChange={change} value={value} />
        </div>
    );
}

自定义

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

代码

import { IconLikeHeart } from '@fibrous/semi-icons-react';
import { Rating } from '@fibrous/semi-ui-react';

export default function RatingDemo() {
    return (
        <div>
            <Rating style={{ color: 'red' }} character={<IconLikeHeart size="extra-large" />} defaultValue={3} />
            <br />
            <br />
            <Rating style={{ color: 'red' }} size={48} allowHalf character={<IconLikeHeart style={{ fontSize: 48 }} />} defaultValue={3} />
            <br />
            <br />
            <Rating character="赞" size={18} defaultValue={3} />
            <br />
            <br />
            <Rating count={10} defaultValue={6} />
        </div>
    );
}

API参考

Props

属性	说明	类型	默认值
allowClear	是否允许再次点击已选中的星后清除数值。	`boolean`	`true`
allowHalf	是否允许半选。	`boolean`	`false`
aria-invalid	是否校验失败，设置在根元素的 `aria-invalid` 上。	`boolean`	-
aria-required	是否必填，设置在根元素的 `aria-required` 上。	`boolean`	-
autoFocus	挂载时自动获取焦点，落点与 `ref` 的 `focus()` 相同。	`boolean`	-
character	每颗星中绘制的字符，可传入 React 节点，如 `<IconLikeHeart />`，未设置时为星形图标。传入纯文本字符串时，该文本作为各星可访问名称与整组摘要的单位。	`React.ReactNode`	-
className	根元素的类名。	`string`	-
count	星的总数。	`number`	`5`
defaultValue	非受控时的初始值。	`number`	`0`
disabled	只读，无法进行交互，也无法获得焦点。	`boolean`	-
id	根元素的 id。	`string`	-
onBlur	焦点离开整个评分组件时的回调，在星之间移动不触发。	`Type`	-
onChange	选择变化时的回调，参数为新的值。	`Type`	-
onClick	点击星或按 Enter、Space 选中时的回调，参数为事件与星的序号；不会作为根元素的原生 click 监听。	`Type`	-
onFocus	焦点进入整个评分组件时的回调，在星之间移动不触发。	`Type`	-
onHoverChange	指针经过时数值变化的回调；指针移出或点击清除时参数为 `undefined`。	`Type`	-
onKeyDown	方向键使值移动时的回调，其他按键不触发。	`Type`	-
prefixCls	组件的样式类名前缀。	`string`	`"semi-rating"`
preventScroll	聚焦组件内的星（包括 `autoFocus` 与 `focus()`）时，是否阻止浏览器滚动文档以显示新聚焦的星。	`boolean`	-
ref	组件句柄，暴露 `focus()` 与 `blur()` 方法。	`Type`	-
size	尺寸，可选 `default`、`small`，也可传入 number 自定义尺寸。	`'small' \| 'default' \| number`	`"default"`
style	根元素的样式。	`React.CSSProperties`	`{}`
tooltips	每颗星的提示信息，数组下标与星的序号对应；空字符串或缺省的项不显示提示。	`string[]`	-
value	当前受控值，传入后由该值决定显示；变回 `undefined` 时回到 `defaultValue` 并转为非受控。	`number`	-

Methods

方法	说明	类型
blur	焦点位于评分内时移除焦点；禁用时无效。	`Type`
focus	聚焦 Tab 会到达的 radio，与 `autoFocus` 的落点相同；禁用时无效。	`Type`

aria-label 原样作为 radiogroup 的可访问名称，缺省时名称概括当前取值；aria-labelledby 引用标签元素的 id 作为名称；data-* 等其他原生属性落在 role="radiogroup" 的根 ul 上。

ref 上的 focus() 聚焦 Tab 会到达的 radio（与 autoFocus 的落点相同），blur() 只在焦点位于评分内时生效。不再支持 tabIndex：传入的值被丢弃，列表固定为 tabIndex={-1}，只有选中的 radio 可以 Tab 到达。

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	聚焦轮廓宽度