教程 ↗

React 离散年份旋钮的拖动、触摸与键盘实现

用原创 React 示例实现 1980–2026 的离散年份输入,解释位移映射、指针捕获、触摸滚动取消、键盘操作与实际边界结果。

React 离散年份旋钮与整数年份显示的示意图

年份旋钮看起来是一个圆,真正需要稳定的是输入规则:上拖多少距离算一年,到了最早和最晚年份怎么停,手指移动时由组件还是页面处理,以及不用鼠标的人怎样选值。

这个原创 React 小例子把范围固定为 1980 到 2026,初值 2000,向上拖动每 6 个 CSS 像素增加一年。圆形指针只负责显示;状态始终是一份整数年份,鼠标、触摸和键盘都更新它。先把这条输入链路做完整,再决定是否需要更复杂的旋转手势。

选题来自一篇题为 Built a custom draggable knob component in React to scrub through decades of music 的帖子。读取时作者已经删除正文,可见标题只能说明项目主题。下面的映射、代码和结果来自本文自建的本地示例。

用位移选年份 用角度显示年份

如果用鼠标围绕圆心的角度直接算年份,拖动需要一直绕圈,跨越角度起点还要处理跳变。这个小范围年份输入采用相对纵向位移:按下时记住位置和年份,之后每次移动都相对这次起点计算。它与拖动数字输入框类似,手指可以在圆的任何位置开始。

const MIN = 1980, MAX = 2026;
const PX_PER_YEAR = 6;
const clampYear = value =>
  Math.max(MIN, Math.min(MAX, Math.round(value)));

// drag.year 与 drag.y 都在 pointerdown 时保存
const next = clampYear(
  drag.year + (drag.y - event.clientY) / PX_PER_YEAR
);

先四舍五入,再限制上下界。保存的 drag.year 在本次拖动中不变,可以避免把每次已舍入的结果再累加导致漂移。坐标使用 clientY,灵敏度也用 CSS 像素,不乘设备像素比。一次上拖 60 像素就是增加 10 年。

显示角度从 −135° 到 +135°,计算为 -135 + (year - MIN) / (MAX - MIN) * 270。这里的角度映射不参与取值,键盘改变年份也能得到同一指针位置。

英文 React 示例中年份为 2000 旁边显示键盘规则和输入事件

原创英文示例的年份、指针和键盘规则使用同一份状态。

一条 Pointer Events 链路接鼠标和触摸

React 通过 onPointerDown、onPointerMove 和 onPointerUp 接收浏览器指针事件。按下时只接受主指针,鼠标只接受左键;用 pointerId 绑定这一轮拖动。setPointerCapture 让后续事件继续发给组件,即使指针已经离开圆形区域。它不会阻止浏览器把手势解释成页面滚动,这部分交给 touch-action。

下面是可放进已有 React 工程的核心组件。示例使用 React 19.2.0;在组件根目录导入 CSS,再渲染 <YearKnob />。如果要接表单,可以在 year 变化时把整数交给父组件,父组件再负责筛选或保存。

import { useRef, useState } from "react";
const MIN = 1980, MAX = 2026, PX_PER_YEAR = 6;
const clampYear = v => Math.max(MIN, Math.min(MAX, Math.round(v)));

export default function YearKnob() {
  const [year, setYear] = useState(2000);
  const drag = useRef(null);
  function down(e) {
    if (!e.isPrimary || (e.pointerType === "mouse" && e.button !== 0)) return;
    e.currentTarget.focus();
    e.currentTarget.setPointerCapture(e.pointerId);
    drag.current = { id: e.pointerId, y: e.clientY, year };
  }
  function move(e) {
    const d = drag.current;
    if (!d || d.id !== e.pointerId) return;
    setYear(clampYear(d.year + (d.y - e.clientY) / PX_PER_YEAR));
  }
  function end(e) {
    if (drag.current?.id === e.pointerId) drag.current = null;
  }
  function key(e) {
    const delta = { ArrowUp: 1, ArrowRight: 1, ArrowDown: -1,
      ArrowLeft: -1, PageUp: 10, PageDown: -10 }[e.key];
    if (delta !== undefined) {
      e.preventDefault();
      setYear(v => clampYear(v + delta));
    } else if (e.key === "Home" || e.key === "End") {
      e.preventDefault();
      setYear(e.key === "Home" ? MIN : MAX);
    }
  }
  const angle = -135 + (year - MIN) / (MAX - MIN) * 270;
  return <div>
    <div className="year-knob" role="slider" tabIndex={0}
      aria-label="Year" aria-valuemin={MIN} aria-valuemax={MAX}
      aria-valuenow={year} aria-valuetext={String(year)}
      aria-describedby="year-help" onPointerDown={down}
      onPointerMove={move} onPointerUp={end}
      onPointerCancel={end} onLostPointerCapture={end} onKeyDown={key}>
      <div className="year-marker" style={{ transform: `rotate(${angle}deg)` }}><i /></div>
      <strong>{year}</strong>
    </div>
    <p id="year-help">Arrow keys ±1; Page keys ±10; Home 1980; End 2026.</p>
  </div>;
}
.year-knob {
  width: 230px; height: 230px;
  border: 2px solid #303c35; border-radius: 50%;
  position: relative; display: grid; place-items: center;
  touch-action: none; user-select: none; cursor: ns-resize;
}
.year-knob:focus-visible {
  outline: 3px solid #c87450; outline-offset: 6px;
}
.year-marker { position: absolute; inset: 12px; pointer-events: none; }
.year-marker i {
  position: absolute; top: 0; left: calc(50% - 3px);
  width: 6px; height: 24px; background: #c87450;
}

useRef 保存一次拖动的临时起点,useState 保存需要渲染的年份。结束处理同时接 pointerup、pointercancel 和 lostpointercapture,避免取消后还留下旧起点。取消时保留最后已选年份;如果业务要求取消后回到起点,需要额外把 drag.year 还原,这个示例没有采用该行为。

触摸输入的实际失败

在 390×844 的 Chromium 模拟视口里,通过浏览器触摸输入执行同一组件。打开 touch-action: none 后,从 2001 向上拖 60 像素,结果是 2011;事件连续包含触摸的 down、move、up,页面滚动量为 0。

为了看清故障,示例有一个英文的 Protect touch drag 开关。关闭它会把 CSS 设为 touch-action: auto。从 2011 开始上拖 100 像素,浏览器只交给组件前两次移动,年份停在 2014,随后产生 pointercancel,页面滚动了 85 像素。指针捕获仍然存在,但滚动手势的接管终止了组件输入。

这说明需要在手势开始前声明 touch-action。修复点只放在旋钮上,页面其他区域继续正常滚动;把整个页面都禁用触摸滚动会改变阅读体验。MDN 的 Pointer Events 文档 对捕获、取消和 touch-action 的职责有完整说明。

上述是浏览器触摸模拟的实际失败记录,尚未在实体手机、Safari 或移动端读屏软件中验证手感和兼容性。模拟能发现滚动争用,设备上的拇指可达性和辅助技术行为仍需接入项目后实测。

键盘规则和边界一起验收

旋钮使用 role="slider"、tabIndex={0}、名称和当前值属性,使它能进入键盘焦点顺序。只有声明角色还不够,组件自己实现按键。WAI APG Slider Pattern 给出了方向键、Home、End 和可选 Page 键的约定。

输入本示例结果
Home 后再按向下保持 1980
End 后再按向上保持 2026
Home、PageUp、向右1991
从 1991 用鼠标上拖 60 CSS 像素2001
从 2000 按住并把鼠标移出圆形 上移 280 像素限制为 2026 并正常结束

处理了按键才调用 preventDefault(),Tab 等其他键仍由浏览器处理。当前年份通过 aria-valuenow 和 aria-valuetext 表达,焦点轮廓在浅色和深色界面都保留。桌面与 390 像素窄屏检查没有横向溢出;读屏软件还需要另做验收。

如果页面只是选择某一年,原生 input type="range" 或年份下拉框通常更省维护。自定义旋钮适合确实需要这种视觉表现的场景;把整数状态、手势临时状态和角度显示分开,后续调整外观时才容易保住输入行为。

同类数值输入还会遇到 JavaScript 精度问题,可以继续看 HEX 转十进制时用 BigInt 保住精度。本文年份范围很小,普通 Number 的整数精度足够。

← 返回列表