XiHan.UI

主题

取本页 Markdown

Rating 评分 ​

用一排图案表示一个离散的分值。

HeadlessStylesVueReactWeb Components

用法 ​

不传 value 即为非受控，组件自行维护评分；default-value 只决定初始档位

整体满意度

组件结构 ​

加粗的是必需部件。

data-scope="rating"：root · label · control · value-text · item · hidden-input

示例 ​

半星与悬停预览 ​

allow-half 使落点分左右半边；划过只发 hover-change，评分要点击后才改变

服务评分

评分：2.5 · 悬停预览：（无）

自定义档数 ​

count 决定几颗星，星星按 1..count 逐颗写出

推荐指数（10 档）

当前：7 / 10

只读与禁用 ​

read-only 仍进入 Tab 序列、读屏可朗读但不可修改；disabled 整条退出 Tab 序列

只读（4 星）
禁用（2 星）

颜色 ​

tone 决定点亮的星使用哪族颜色，不写时沿用警示色

brand
neutral
success
warning
danger
info

尺寸 ​

size 改变星的大小与间距，不写即默认中档

sm
缺省
lg

自定义图标 ​

条目可使用首方图标，也可留空使用皮肤默认星形

换个字形
内置星形与半档

自定义颜色 ​

点亮色与未点亮色各是一个组件令牌，写在行内即可脱离语气档

只换点亮色
点亮与未点亮各给一色

再点一次清空 ​

allowClear 默认开启：点击当前档位清回未评分，键盘在最低档再向下一步同样清零；设为 false 关闭

整体满意度（可清空）

当前：3

关掉清空（再点不清）

当前：3

设计指引 ​

何时使用 ​

  • 收集或展示满意度、星级等小范围的主观分值。

何时不用 ​

特性 ​

  • allowHalf 支持半档，allowClear 允许再次点击清空。
  • 悬停预览与实际值分开，onHoverChange 单独回调。
  • 条目留空时使用库内置的星形图标；也可传入自定义图标与颜色。

组合 ​

最佳实践 ​

  • 档数固定为五档，更多档用户无法分辨差别。
  • 只读展示时同时写出数值（4.2 / 5），图案本身读不出精确值。

反模式 ​

  • 用它展示进度，那是进度条。
  • 不允许清空却也没有默认值，用户误点后无法恢复。

API 参考 ​

产物 ​

层值
自定义元素<xh-rating>
Vue 组件XhRatingControl XhRatingHiddenInput XhRatingItem XhRatingLabel XhRatingRoot XhRatingValueText
组合式函数useRating
状态机ratingMachine
皮肤@xihan-ui/styles/rating.css

Props ​

属性类型必填说明
valuenumber受控评分。提供即受控：内部不再自行落值，只发 onValueChange。
defaultValuenumber非受控初值，默认 0（尚未评分）。
countnumber星星颗数，默认 5。
allowHalfboolean允许半颗星：档位从 1 变为 0.5。
allowClearboolean再次点击当前档位即清零，键盘在最低档再向下一步同样清零；默认开启。
disabledboolean完全不可交互：退出 Tab 序列，指针与键盘都不响应。
readOnlyboolean只读：仍可聚焦、仍能被读屏朗读，但不可修改，也不提供悬停预览。
requiredboolean
namestring表单字段名；提供后表单影子才带 name 并参与提交。
dirDirection文字方向，默认 'ltr'。只改写左右方向键与指针落在哪半边的语义。
toneTone语气：brand / neutral / success / warning / danger / info，决定使用哪族颜色。
sizeSize尺寸：sm / md / lg。
translationsPartial<RatingTranslations>
onValueChange(details: RatingValueChangeDetails) => void
onHoverChange(details: RatingHoverChangeDetails) => void悬停预览变化；指针离开时带 null。它不代表值已变化。

事件 ​

自定义元素将载荷放在 detail；Vue 使用同名 emit。

事件载荷说明
value-changeRatingValueChangeDetails评分变化；detail 为 { value: number }
hover-changeRatingHoverChangeDetails悬停预览变化；detail 为 { value: number | null }，指针离开时带 null

插槽 ​

仅列出带载荷的插槽。

Vue 组件插槽载荷说明
XhRatingItemdefaultRatingItemSlotProps
XhRatingRootdefaultRatingRootSlotProps

React 适配器 props ​

只列各组件自己声明的那些：继承自 ComponentPropsWithRef 的 DOM 属性不在其中，根组件上与上面 Props 表同名的也不重复列。Vue 的对应物是上面的插槽表。

React 组件属性类型必填说明
XhRatingItemvaluenumber | string是星序号，兼收字符串；向下传递前统一归为数字。
XhRatingItemchildrenSlotChildren<RatingItemSlotProps>
XhRatingRootchildrenSlotChildren<RatingRootSlotProps>

状态 ​

公开状态写入 data-state。

部件取值
item'checked' | 'unchecked'

以下名称仅用于内部状态机。

状态：idle

事件：VALUE.SET · VALUE.STEP · VALUE.TO_MIN · VALUE.TO_MAX · ITEM.SELECT · ITEM.FOCUS · ITEM.HOVER · HOVER.CLEAR · CONTROL.BLUR · FORM.RESET · PRESS.START · PRESS.END

判据：canInteract

connect API ​

getXxxProps() 返回对应部件的宿主属性。

成员类型说明
valuenumber已归一化的评分：非法与越界的宿主输入在这里被夹回。
hoveredValuenumber | null指针预览值；没有预览（或不可交互）时为 null。
highlightedValuenumber当前应点亮到的位置：有预览时是预览值，否则是评分。样式与 data-highlighted 使用的都是它。
valueTextstring分值文本：当前应点亮到的数值，指针预览期间跟随预览值。
countnumber
emptyboolean尚未评分（value 为 0）。
disabledboolean
readOnlyboolean
itemsreadonly number[]1..count 的序号表，作者直接遍历它渲染星星。
getItemState(props: RatingItemProps) => RatingItemState
setValue(next: number) => void
getRootProps() => T['element']
getLabelProps() => T['element']
getControlProps() => T['element']
getValueTextProps() => T['element']分值文本：写在 root 中、control 的兄弟；aria-hidden，读屏使用星星自身的可及名。
getItemProps(props: RatingItemProps) => T['element']
getHiddenInputProps() => T['input']表单出口：一份视觉隐藏的原生输入，随表单提交当前评分。

无障碍 ​

键盘 ​

规格出处：W3C APG

按键生效条件行为
Tab / Shift+Tabfocus outside the control整条评分带只占一个 Tab 位：焦点进入锚点星，无锚点时进入容器并由它转移到首颗
ArrowRight / ArrowUpfocus in control, not disabled/readOnly加一档（allowHalf 时半颗），到顶停在 count；dir=rtl 时改由 ArrowLeft 承担
ArrowLeft / ArrowDownfocus in control, not disabled/readOnly减一档，到底停在最小档，不会退回"还没评"；dir=rtl 时改由 ArrowRight 承担
Homefocus in control, not disabled/readOnly取最小档（allowHalf 时是半颗，否则一颗）
Endfocus in control, not disabled/readOnly取满分（count）

ARIA ​

以下属性由 connect 生成。

部件属性值
controlaria-disabled'true' | 'false'
controlaria-labelledbylabel 部件的 id
controlaria-orientation'horizontal'
controlaria-readonly'true' | 'false'
controlaria-required'true' | 'false'
controlrole'radiogroup'
value-textaria-hidden'true'
itemaria-checked'true' | 'false'
itemaria-disabled'true' | 'false'
itemaria-labelitemLabel?.(item.value, count)
itemaria-posinsetitem.value
itemaria-setsizeratingMax(prop('count'))
itemrole'radio'
hidden-inputaria-hidden'true'

样式参考 ​

皮肤 ​

@xihan-ui/styles/rating.css 使用 [data-scope="rating"][data-part="root"] 部件选择器，位于 xihan.components 层。覆盖样式使用 xihan.overrides。

forced-colors: active 下另有一套规则：颜色交给系统，边框与状态标记改用系统色关键字。

数据属性 ​

由 connect 生成；条件不成立时不输出无值属性。

部件属性值
rootdata-disabled''（条件成立时才出现）
rootdata-empty''（条件成立时才出现）
rootdata-readonly''（条件成立时才出现）
rootdata-sizeprops.size
rootdata-toneprops.tone
labeldata-disabled''（条件成立时才出现）
controldata-disabled''（条件成立时才出现）
controldata-readonly''（条件成立时才出现）
value-textdata-disabled''（条件成立时才出现）
value-textdata-empty''（条件成立时才出现）
value-textdata-readonly''（条件成立时才出现）
itemdata-disabled''（条件成立时才出现）
itemdata-half''（条件成立时才出现）
itemdata-highlighted''（条件成立时才出现）
itemdata-pressed''（条件成立时才出现）
itemdata-readonly''（条件成立时才出现）
itemdata-state'checked' | 'unchecked'
itemdata-xh-action-control''
itemdata-xh-action-display'always'
itemdata-xh-action-profile'icon'
itemdata-xh-action-size'xs'
itemdata-xh-action-variant'ghost'
hidden-inputdata-disabled''（条件成立时才出现）

CSS 变量 ​

本组件公开覆盖槽由独立皮肤的实际消费位生成；默认来源、作用部件和状态均与 CSS 同源。

变量部件CSS 属性状态默认来源说明
--xh-rating-gaprootgapdefault--xh-space-1rating 的 root 部件 gap 覆盖槽。
--xh-rating-item-bg-presseditembackground-colordisabled
is(:active, [data-pressed])
loading
not([data-disabled])
not([data-loading])
pressed		--xh-bg-subtle-hoverrating 的 item 部件 background-color 覆盖槽。
--xh-rating-item-fgitembackground-color
background-image
color		default
dir(rtl)
disabled
empty
focus-visible
half
hover
is(:active, [data-pressed])
loading
not(:empty)
not([data-disabled])
not([data-loading])
pressed		--xh-fg-subtlerating 的 item 部件 background-color、background-image、color 覆盖槽。
--xh-rating-item-fg-highlighteditembackground-color
background-image
color		@media print
dir(rtl)
disabled
empty
focus-visible
half
highlighted
hover
is(:active, [data-pressed])
loading
not(:empty)
not([data-disabled])
not([data-loading])
pressed		--xh-_rating-accentrating 的 item 部件 background-color、background-image、color 覆盖槽。
--xh-rating-item-font-sizeitem
root		--xh-icon-size
font-size		default--xh-_rating-item-sizerating 的 item、root 部件 --xh-icon-size、font-size 覆盖槽。
--xh-rating-item-gapcontrolgapdefault--xh-_rating-item-gaprating 的 control 部件 gap 覆盖槽。
--xh-rating-item-radiusitemborder-radiusdefault--xh-shape-controlrating 的 item 部件 border-radius 覆盖槽。
--xh-rating-label-fglabelcolordefault--xh-fg-defaultrating 的 label 部件 color 覆盖槽。
--xh-rating-label-fg-disabledlabelcolordisabled--xh-fg-subtlerating 的 label 部件 color 覆盖槽。
--xh-rating-label-font-sizelabelfont-sizedefault--xh-text-label-sizerating 的 label 部件 font-size 覆盖槽。
--xh-rating-label-font-weightlabelfont-weightdefault--xh-text-label-weightrating 的 label 部件 font-weight 覆盖槽。
--xh-rating-value-text-fgvalue-textcolordefault--xh-fg-mutedrating 的 value-text 部件 color 覆盖槽。
--xh-rating-value-text-fg-disabledvalue-textcolordisabled--xh-fg-subtlerating 的 value-text 部件 color 覆盖槽。
--xh-rating-value-text-font-sizevalue-textfont-sizedefault--xh-_rating-font-sizerating 的 value-text 部件 font-size 覆盖槽。

动效 ​

动效角色：按压 · 状态 · 切换（见动效规范）。

clip-path 走 transition 过渡。时长与缓动读动效令牌，改令牌即改全局节奏。

系统开启减弱动效时由令牌层统一收敛，皮肤不另作判断。

响应式 ​

皮肤另按输入能力分档：pointer: coarse：同一份皮肤在触屏与带指针的设备上不一样，与视口宽度无关。

RTL ​

皮肤用逻辑属性排布（inline-start 一族），dir="rtl" 下自动镜像；另有按 dir 分支的规则。

Released under The MIT License

Copyright ©2021-Present XiHanFun and contributors.