react-ruler-picker

English | 简体中文

用于选择数值的 React 标尺组件，支持 Canvas 刻度、拖拽与滚轮交互、触摸惯性和 TypeScript。

在线演示

• 支持自定义数值范围、步长、方向和刻度样式。
• 支持受控 / 非受控值、指针拖拽、鼠标滚轮和触摸惯性滚动。
• 支持边缘回弹、无障碍属性、prefers-reduced-motion 和 TypeScript。
• 提供 ESM、CommonJS 和 TypeScript 类型声明。

安装

npm install react-ruler-picker

要求 React 16.8 及以上版本。

快速上手

import { useState } from "react";
import { RulerPicker } from "react-ruler-picker";

export function HeightField() {
  const [value, setValue] = useState(170);

  return (
    <RulerPicker
      min={80}
      max={220}
      value={value}
      onValueChange={setValue}
      aria-label="Height in centimeters"
      formatValue={(next) => `${next} cm`}
    />
  );
}

组件首次挂载时会自动注入基础样式，无需额外引入 CSS。通过 orientation="vertical" 使用纵向标尺，也可以通过 ref 调用 scrollToValue 和 getValue。

Props

| Prop | 类型 | 默认值 / 行为 | | --- | --- | --- | | min, max | number | 必填的有限范围边界；传入相反顺序会自动归一化。 | | step | number | 1；最小可选增量。非法或非正值按 1 处理。 | | value | number | 受控的选中数值。 | | defaultValue | number | min；非受控时的初始值。 | | majorStep | number | step * 10；主刻度间隔。 | | labelStep | number | majorStep 或 step * 10；设为 0 隐藏刻度标签。 | | tickSpacing | number | 8；相邻刻度间距（CSS 像素），最小为 1。 | | orientation | 'horizontal' \| 'vertical' | 'horizontal'；标尺方向。 | | tickAlignment | 'top' \| 'bottom' \| 'left' \| 'right' | 'top'；刻度对齐方式。 | | reverse | boolean | false；反转数值递增方向。 | | height | number | 240；纵向标尺高度（CSS 像素）。 | | minorTickStyle, majorTickStyle | TickStyle | 刻度的 width、height、color 和 borderRadius。 | | getTickStyle | (info: TickInfo) => Partial<TickStyle> \| undefined | 单个刻度的样式回调。 | | labelStyle | LabelStyle | 刻度标签字体样式。 | | formatLabel | (value: number) => string | 刻度标签格式化函数。 | | cursorStyle | CursorStyle | 中心指针样式。 | | renderCursor | () => ReactNode | 自定义中心指针。 | | showValue, showEdgeMasks | boolean | true；控制数值显示和边缘遮罩。 | | valueStyle | CSSProperties | 数值区域样式。 | | formatValue | (value: number) => string | 选中数值和 aria-valuetext 的格式化函数。 | | renderValue | (value: number) => ReactNode | 自定义选中数值内容。 | | motion | RulerMotionOptions | 拖拽和惯性滚动参数，见下文。 | | wheelSensitivity | number | 1.8；滚轮灵敏度，设为 0 禁用滚轮。 | | disabled | boolean | false；禁用交互。 | | onScrollStart | () => void | 用户滚动会话开始时调用一次。 | | onValueChange | (value, meta) => void | 数值变化时调用；meta.source 为 drag、wheel、momentum 或 programmatic。 | | onValueChangeEnd | (value: number) => void | 滚动停止并稳定到步长后调用。 | | aria-label | string | 无障碍名称。 | | aria-labelledby, aria-describedby | string | 无障碍标签和描述的元素 ID。 | | className, style | string, CSSProperties | 根容器的 class 和内联样式。 |

惯性与滚轮

<RulerPicker
  min={0}
  max={1000}
  motion={{
    friction: 0.9,
    velocityMultiplier: 1,
    maxVelocity: 3,
    threshold: 0.01,
  }}
  wheelSensitivity={1.8}
/>

| 参数 | 默认值 | 说明 | | --- | --- | --- | | friction | 0.9 | 惯性速度保留比例，范围 [0, 1)；0 禁用惯性。 | | velocityMultiplier | 1 | 释放速度倍率。 | | maxVelocity | 3 | 最大释放速度（CSS 像素/ms）。 | | threshold | 0.01 | 惯性停止阈值（CSS 像素/ms）。 |

组件会根据系统的 prefers-reduced-motion 偏好减少动画。横向标尺支持普通滚轮和触控板，onValueChange 的 meta.source 可用于区分拖拽、滚轮、惯性和代码驱动的变化。

开发

npm ci
npm run dev           # 启动 Playground
npm test              # 运行单元测试
npm run check         # 类型、测试、构建和打包校验
npm run test:react16  # React 16.8 兼容性验证

License

MIT