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

年份旋钮看起来是一个圆,真正需要稳定的是输入规则:上拖多少距离算一年,到了最早和最晚年份怎么停,手指移动时由组件还是页面处理,以及不用鼠标的人怎样选值。
这个原创 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。这里的角度映射不参与取值,键盘改变年份也能得到同一指针位置。

原创英文示例的年份、指针和键盘规则使用同一份状态。
一条 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 的整数精度足够。