组件/ScrubField 拖拽数值域

ScrubField 拖拽数值域

标签即拖动手柄的紧凑数值输入

Verified自 0.3.9

用法

基础

整数、百分比与半步长。

Loading demo...

最佳实践

  • 标签保持简短(W、H、Radius),它就是拖动手柄。
  • active 由宿主判断,通常是「当前值 ≠ 预设值」;与数据比较,不写死常量。
  • 频繁键入的表单用 clampOn="blur";即时预览的检查器保留默认的 'input'。
  • 按轨道位置取值用 TxSlider;带加减按钮的表单字段用 TxNumberInput。

API 参考

属性

属性名类型默认值说明
modelValuenumber—当前值(受控)。
labelstring—短标签,同时是拖动手柄。
min / maxnumber—取值范围;拖动、方向键与键入都会夹取。
stepnumber1步长;小数步长保留相应的小数位。
suffixstring—值后的单位,如 %。
activebooleanfalse以「已改动」样式高亮;是否改动由宿主判断。
disabledbooleanfalse禁用拖动、方向键与键入。
pixelsPerStepnumber2前进一个步长所需的指针位移。
shiftMultipliernumber10按住 Shift 时方向键的倍率。
clampOn'input' | 'blur''input'键入时何时夹取:每次按键或失焦。
ariaLabelstring—手柄的可访问名,缺省用 label。
valueLabelstring'{label} value'输入框的可访问名。

事件

事件名回调参数说明
update:modelValue(value: number)值变化时触发;相同值不重复触发。
change(value: number)与 update:modelValue 同时触发。
scrubStart / scrubEnd—拖动开始与结束(含取消)。

暴露方法

方法名说明
focus()聚焦拖动手柄。
focusInput()聚焦数值输入框。

概述

  • 拖动:在标签上横向拖动,每 pixelsPerStep 像素前进一个 step;按起点累计位移,没有轨道。拖动中按 Esc 放弃,值回到按下时。
  • 键盘:↑ → 增加、↓ ← 减少,Shift 乘以 shiftMultiplier,Home / End 跳到边界。
  • 键入:右侧是原生 <input>;clampOn="blur" 保留输入中的文本,失焦时再夹取;Esc 还原文本。
  • 手柄是 role="slider",带 aria-valuenow / aria-valuemin / aria-valuemax / aria-orientation,有 suffix 时另带 aria-valuetext;输入框是另一个控件,有自己的可访问名。
  • 手柄设置 touch-action: pan-y,纵向手势留给页面滚动;pointercancel 与 lostpointercapture 都会结束拖动。
  • 减弱动效下关闭唯一的状态过渡。

技术实现

  • 量化的是位移而非结果:round(位移 / pixelsPerStep) * step,因此小数步长成立,网格外的起始值也不会被吸附。
  • 源码:packages/tuffex/packages/components/src/scrub-field/。
  • 移植自 Beautiful UI(https://www.beautifului.dev),© 2026 Shane Levine,MIT。
查看源码
packages/tuffex/packages/components/src/scrub-field/index.ts