iter(e03): 新增 rate 评分组件

2026-10-23 18:07:42 +08:00
parent dc4bac4d17
commit ee20322e3f
12 changed files with 206 additions and 7 deletions
@@ -25,6 +25,7 @@ export { spinner } from './spinner.js';
 export { progress } from './progress.js';
 export { tabs } from './tabs.js';
 export { stepper } from './stepper.js';
+export { rate } from './rate.js';
 export { modal } from './modal.js';
 export { drawer } from './drawer.js';
 export { form, formItem } from './form.js';
@@ -0,0 +1,34 @@
+import { effect, h, signal } from '@ui-arch/frame';
+import type { RateProps } from './types.js';
+
+/*** 评分：星标点选，hover 预览移出还原，键盘 ←→/↑↓ 调节，value 信号双向绑定 ***/
+export function rate(props: RateProps): HTMLDivElement {
+  const value = props.value;
+  const max = props.max ?? 5; // 星标总数缺省 5
+  const hover = signal(0); // 预览索引（1 基，0 表示无预览）
+  const emit = (v: number): void => { const n = Math.min(max, Math.max(1, v)); value(n); if (props.onChange) props.onChange(n); }; // 写回信号并回调
+  const render = (): HTMLElement => {
+    const shown = hover() || value(); // 预览优先，无预览显示当前值
+    const stars = [];
+    for (let i = 1; i <= max; i++) {
+      stars.push(h('button', {
+        class: `ua-rate-star${i <= shown ? ' is-on' : ''}`,
+        type: 'button',
+        disabled: props.disabled,
+        'aria-label': `${i} 星`,
+        onClick: () => emit(i),
+        onMouseEnter: () => hover(i),
+      }, '★'));
+    }
+    return h('div', { class: 'ua-rate', role: 'slider', 'aria-label': '评分', 'aria-valuemin': 1, 'aria-valuemax': max, 'aria-valuenow': value(), onMouseLeave: () => hover(0) }, ...stars);
+  };
+  let el!: HTMLElement; // 当前渲染产物（effect 首跑赋值）
+  effect(() => { const next = render(); if (el) el.replaceWith(next); el = next; }); // value/hover 变化整条重渲染（星标少，开销可忽略）
+  const keyNav = (e: KeyboardEvent): void => {
+    if (e.key !== 'ArrowLeft' && e.key !== 'ArrowRight' && e.key !== 'ArrowUp' && e.key !== 'ArrowDown') return; // 卫语句：只拦截方向键
+    e.preventDefault();
+    emit(value() + (e.key === 'ArrowRight' || e.key === 'ArrowUp' ? 1 : -1)); // →/↑ 加一分，←/↓ 减一分
+  };
+  el.addEventListener('keydown', keyNav);
+  return el as HTMLDivElement;
+}
@@ -189,6 +189,14 @@ export interface StepperProps {
  onChange?: (index: number) => void; // 步骤切换回调（点击回跳触发）
 }

+/*** 评分入参 ***/
+export interface RateProps {
+  value: Signal<number>;  // 当前评分（1 基整数值），双向绑定（点击/键盘写回、外部赋值同步）
+  max?: number;           // 星标总数；缺省 5
+  disabled?: boolean | Signal<boolean>; // 禁用态：布尔直接置位，传信号则动态同步
+  onChange?: (value: number) => void;   // 评分变化回调
+}
+
 /*** 徽标入参 ***/
 export interface BadgeProps {
  label: string; // 徽标文案
@@ -39,6 +39,7 @@
      "progress(props)：进度条，value 信号驱动 0-100（满格切 success 色）；不传 value 退化为不确定态无限往复",
      "tabs(props)：标签页，active 信号双向绑定，滑动指示条 + 方向键环形导航，支持禁用页签",
      "stepper(props)：步骤条，done/current/upcoming 三态，active 信号双向绑定，clickable 时已完成步骤可回跳",
+      "rate(props)：评分星标，value 信号双向绑定，hover 预览移出还原，键盘方向键调节，max 可配",
      "modal(props, ...children)：弹窗，open 信号驱动显隐，Esc / 遮罩 / × 关闭，size 三档宽度，footer 提供底部操作区",
      "drawer(props, ...children)：抽屉，open 信号驱动侧滑面板，placement 左右可配、width 可调、footer 操作区，遮罩 / × / Esc 关闭",
      "form(props, items)：表单容器，布局 + 聚合校验，全部通过才触发 onSubmit",
@@ -1015,6 +1016,42 @@
          "clickable: true 时已完成步骤可点击回跳并写回信号，配合 onChange 同步业务状态"
        ]
      },
+      {
+        "id": "rate",
+        "title": "评分 Rate",
+        "demo": "sec-rate",
+        "props": [
+          {
+            "n": "value",
+            "t": "Signal<number>",
+            "r": 1,
+            "d": "当前评分（1 基整数值）信号，双向绑定：点选/键盘写回、外部赋值同步"
+          },
+          {
+            "n": "max",
+            "t": "number",
+            "d": "星标总数；缺省 5",
+            "df": "5"
+          },
+          {
+            "n": "disabled",
+            "t": "boolean | Signal<boolean>",
+            "d": "禁用态：布尔直接置位，传信号则动态同步"
+          },
+          {
+            "n": "onChange",
+            "t": "(value: number) => void",
+            "k": 1,
+            "d": "评分变化回调"
+          }
+        ],
+        "example": "const score = signal(0); rate({ value: score, max: 5, onChange: (v) => console.log(v) })",
+        "steps": [
+          "用 signal(0) 创建评分信号并传入 value；0 表示未评分",
+          "点击星标或聚焦后按 →/↑ 加一分、←/↓ 减一分；悬停高亮预览、移出还原",
+          "max 可调整星标总数；disabled 支持布尔或信号禁用"
+        ]
+      },
      {
        "id": "pagination",
        "title": "分页器 Pagination",
@@ -783,6 +783,37 @@ button.ua-step-dot:hover {
  color: var(--ua-color-text-muted);
 }

+/* —— 评分 —— */
+.ua-rate {
+  display: inline-flex;
+  gap: 2px;
+}
+.ua-rate-star {
+  padding: 0;
+  border: none;
+  background: none;
+  color: var(--ua-color-border); /* 未选中：弱化为边框色 */
+  font-size: 22px;
+  line-height: 1;
+  cursor: pointer;
+  transition: color 0.15s, transform 0.12s;
+}
+.ua-rate-star:hover {
+  transform: scale(1.15); /* 悬停微放大 */
+}
+.ua-rate-star.is-on {
+  color: var(--ua-color-warning); /* 选中：警示黄即星标金 */
+}
+.ua-rate-star:disabled {
+  cursor: not-allowed;
+  opacity: 0.45;
+}
+.ua-rate-star:focus-visible {
+  outline: none;
+  box-shadow: 0 0 0 3px color-mix(in srgb, var(--ua-color-warning) 25%, transparent);
+  border-radius: 4px;
+}
+
 /* —— 徽标 —— */
 .ua-badge {
  display: inline-block;
@@ -1459,7 +1490,8 @@ button.ua-step-dot:hover {
  .ua-modal-overlay,
  .ua-drawer,
  .ua-drawer-overlay,
-  .ua-step-dot {
+  .ua-step-dot,
+  .ua-rate-star {
    animation: none !important;
    transition: none !important;
  }