跳到主要内容

Stepper 步进器

数字步进控件——[−][ N ][+] 三段拼接,到达 min/max 自动禁用对应按钮。

代码演示​

独立
min=1, max=99
点按数字输入,非编辑时显示单位
零范围 / disabled slider
下单清单
统一冰红茶
¥120 / 箱 · 库存 50
阿萨姆奶茶
¥96 / 箱 · 库存 80
老坛酸菜面
¥48 / 箱 · 库存 30
合计 62 箱 · ¥3,840

视觉规范​

来源:src/components/ui/Stepper/styles.ts、Stepper.tsx。

元素规则
实际交互 framemd/sm 三个 outer 均至少 fixed.hitTarget,不加 hitSlop;xs 是明确的 dense 例外:左右 outer 为 r(24) × 44,中央 adjustable 为 r(40) × 44,三块相邻且互不重叠,不加 hitSlop 或根 padding,Web / 402pt RN harness 总宽 88pt
visual 高度xs r(24)、sm r(28)、md r(32);只有 Web / 402pt RN harness 得到 24/28/32/40/48 的基准值,其他 native window 按实际 r() 结果
圆角8px(radius.md,外层左右两角),中间数字框无独立圆角
按钮 visualmd r(32)² / sm r(28)² / xs r(24)²,嵌在 side outer 内并朝中央贴边;± 基准字号 18px(type.h1),按 fontScale 缩放一次
数值 visualmd r(48) × r(32) / sm r(40) × r(28) / xs r(40) × r(24);1px 上下边线、无左右边线,基准字号 md 14 / sm 13 / xs 11,按 fontScale 缩放一次;formatValue 只替换可见文案
背景 / 描边视觉区域共用无额外染色的系统玻璃,保留 1px c.outline 边;Android、旧 iOS 或减少透明度时使用主题 surface 实色;Web 保留 CSS 近似材质,无 CSS 模糊能力且未启用减少透明度时使用主题渐变
禁用按钮前景 opacity: 0.4(达到 min/max 或整体 disabled 时;按下 0.7),材质与其祖先保持不透明

ThemeProvider fontScale 只改变 ± 与中央数值的文字 metric。三个 visual wrapper、md/sm 至少 44pt 的 outer frame、xs 高 44pt 且横向小于 44pt 的 dense outer、边框、圆角和点击布局都不缩放;动态中央字号不会再经过 useThemedStyles 二次处理。

用法​

import { Stepper } from '@unif/react-native-design';

const [qty, setQty] = useState(12);

<Stepper
value={qty}
onChange={setQty}
min={1}
max={99}
accessibilityLabel="商品数量"
/>;

{
/* 自定义步长 */
}
<Stepper
value={packs}
onChange={setPacks}
step={6}
min={0}
max={120}
accessibilityLabel="整箱数量"
/>;

{
/* 小尺寸 */
}
<Stepper
size="sm"
value={n}
onChange={setN}
min={0}
max={9}
accessibilityLabel="套餐数量"
/>;

{
/* 点按中央输入数字;非编辑时仍显示单位 */
}
<Stepper
size="xs"
editable
value={packs}
onChange={setPacks}
min={0}
max={99}
formatValue={(value) => `${value} 箱`}
accessibilityLabel="整箱数量"
/>;

{
/* 原始 min > max 会折叠为零范围:显示 10,三个操作节点全部禁用 */
}
<Stepper
value={5}
onChange={setQty}
min={10}
max={0}
accessibilityLabel="异常范围数量"
/>;

editable 默认关闭。开启后点按中央值进入纯数字输入,完成或失焦会把有限十进制数字夹到 [min, max] 后通过 onChange 交回;step 只用于加减,不对输入取整。明确输入与当前值相同的数字也提交一次。

空串、只有符号、单位文字和非有限数不会提交,也不会转成 0:保留原草稿并显示错误边框,辅助技术提示“请输入有效数字”。修正后即可提交。输入期间按加减会以有效草稿为基础只提交一次;外部 value、范围、步长变化或禁用会取消草稿。组件卸载不提交数值。业务需要非负整数等规则时,由消费者在受控回调中验证。

若外层表单依赖此值提交,请通过 onEditingChange 记录编辑状态;编辑未结束时禁用提交按钮,并在提交处理函数中再次检查。非法或空草稿失焦后仍为 true,只有成功提交(含相同值)、取消、外部更新或卸载才通知 false。更换回调函数不会中断会话或重复通知。消费者自己的业务校验错误也应阻止提交。

const [editing, setEditing] = useState(false);
<Stepper
value={qty}
onChange={setQty}
accessibilityLabel="数量"
editable
onEditingChange={setEditing}
/>;
// 提交按钮 disabled={editing};处理提交时也先检查 editing。

受控原始草稿​

需要跨卸载保留未完成输入时,同时传 draft 与 onDraftChange,在组件外的所属状态中保存原文。null 表示未编辑,字符串会原样显示,包括空串、-、01. 等中间输入;省略 draft 时继续由组件持有草稿。上方紧凑示例展示原始字符串与已提交数字的区别。

const [qty, setQty] = useState(4);
const [draft, setDraft] = useState<string | null>(null);

<Stepper
value={qty}
onChange={setQty}
editable
draft={draft}
onDraftChange={setDraft}
accessibilityLabel="商品数量"
/>;
// 未提交判断使用 draft !== null;草稿所属状态可跨 Stepper 卸载保留。

挂载已有草稿只恢复编辑展示,不调用 onChange 或 onDraftChange。卸载仍通知 onEditingChange(false),但不会用 onDraftChange(null) 清空外部草稿;重新挂载会显示同一原文。初次挂载为禁用状态时保留草稿,首次启用再进入编辑。等待资格核验等禁用期间,消费者仍应根据 draft !== null 阻止提交旧数值。

合法数字提交先调用 onChange(number),随后用 onDraftChange(null) 请求结束。宿主接纳 null 后才通知 onEditingChange(false);领域校验拒绝结束时可继续保留原文并修改。同一原文的完成与迟到失焦只交付一次,接纳新原文后可再次提交。外部 value、范围或步长变化,以及活跃编辑时禁用,仍会取消草稿;这些变化会立即使旧输入和旧按钮回调失效,展示回到当前数字;宿主稍后接纳清空通知也不会让旧草稿再次提交。

API​

来源:src/components/ui/Stepper/types.ts、Stepper.tsx。

参数类型默认值说明
valuenumber—当前值(受控,必填)
onChange(value: number) => void—变更回调(已自动夹到 [min, max],必填)
accessibilityLabelstring—中央 adjustable 的上下文名称(必填);左右按钮自动组合“${label},减少 / ${label},增加”
minnumber?0下限(达到时 − 禁用)
maxnumber?99上限(达到时 + 禁用)
stepnumber?1步长(非正数 / 非有限数回退为 1)
size'xs' | 'sm' | 'md''md'visual 高度 r(24) / r(28) / r(32);xs 是横向触控小于 44pt 的 dense 紧凑档(类似 Segmented sm),sm/md 行为不变
formatValue(value: number) => string—格式化中央可见文案;入参是归一化后的安全值,运算与 adjustable now 仍为 number
editableboolean?false允许点按中央值直接输入;合法输入在完成或失焦时提交,非编辑时仍使用 formatValue
draftstring | null—受控原始编辑文字;null 为未编辑,省略时组件内部持有;与 onDraftChange 配合使用
onDraftChange(draft: string | null) => void—进入/输入交付原文,提交或外部更新取消时请求 null;卸载不清空外部草稿
onEditingChange(editing: boolean) => void—编辑会话开始/结束通知;非法失焦不结束,父表单可据此阻止提交旧数值
disabledboolean?false整体禁用(三个操作节点都不暴露 action)
testIDstring?—根定位;派生三个 outer -decrement / -value / -increment 与对应 -*-visual

归一化边界:缺省仍是 min=0、max=99、step=1。只有 typeof === 'number' && Number.isFinite(...) 的输入参与运算;字符串、对象、NaN、Infinity 等未类型化值不会产生 NaN。非法 min 回退 0,非法 max 或 max < safeMin 折叠到 safeMin,非法/非正 step 回退 1,非法 value 回退 safeMin。formatValue 在归一化后调用。零范围、外部 disabled 与空白业务名称都不会暴露任何 action。无 style、valueStyle 或 buttonStyle prop。

无障碍(a11y)​

来源:src/components/ui/Stepper/Stepper.tsx、accessibility.ts、 accessibility.web.ts、types.ts。

  • 默认 role:− / + 两个 outer <Pressable> 是 button;中央 outer <View> 在 native 是 'adjustable',在 Web 映射为 role="slider"。根 <View> 不设 role,内部 visual 子树隐藏出 a11y tree。
  • accessible name:trim 后非空的必填 accessibilityLabel 命名中央 adjustable;左右按钮组合“${accessibilityLabel},减少 / ${accessibilityLabel},增加”。空白名称会禁用并移除三个 action/role 语义,在 effect 诊断。
  • 单一归一化结果同时驱动可见值、disabled opacity、side/native/Web handler 和状态。native custom accessibilityActions 到 safeMin 只列 increment、到 safeMax 只列 decrement;标准 adjustable 手势仍可能派发无效方向,driver 会在调用 onChange 前将其确定性 no-op。
  • Web 中央 slider 显式输出 aria-disabled、aria-valuemin/max/now 与 tab order;ArrowUp/Right 增加,ArrowDown/Left 减少,Home/End 跳到上下限。已识别的边界按键仍阻止浏览器默认行为,但不会发出无效变更。
  • 外部 disabled 或零范围时,native 中央完全省略 accessibilityActions 与 onAccessibilityAction;Web 中央设置 aria-disabled=true、tabIndex=-1 并省略键盘 handler。两个侧按钮也都 disabled 且没有 handler。
  • 开启 editable 时中央仍保留原 adjustable 增减语义,可点按进入输入框;输入框使用相同业务名称和 44pt 高度,不携带 slider 的方向键 handler,左右方向键用于移动光标。编辑错误保留在输入框并提供错误提示,两个侧按钮只对有效草稿开放。
  • 两侧采用 platform seam:native 使用 RNGH Pressable,Web 使用 RN core Pressable,不依赖 Website 的仓库级 RNGH shim。
<Stepper
value={qty}
onChange={setQty}
min={1}
max={99}
accessibilityLabel="统一冰红茶数量"
/>

Native / Web 人工测量​

在 runtime harness 的 Stepper 区用 Inspector 测量:

节点testID预期布局
md/sm 左右 outer platform Pressablestepper-middle-decrement / stepper-middle-incrementnative 为 RNGH、Web 为 RN core;side outer = max(44, visual button width) × max(44, visual height),透明、无 hitSlop;visual 朝中央贴边
md/sm 中央 adjustable outerstepper-middle-valuevalue outer = max(44, visual value width) × max(44, visual height)
xs 三个 outerstepper-compact-decrement / stepper-compact-value / stepper-compact-incrementr(24)×44 / r(40)×44 / r(24)×44;无 hitSlop、无根 padding,三块互不重叠;Web / 402pt RN harness 总宽 88pt,横向触控小于 44pt
md visual wrappers对应 -decrement-visual / -value-visual / -increment-visual实现为 r(32)×r(32) / r(48)×r(32) / r(32)×r(32);Web 与 402pt RN harness 是 32×32 / 48×32 / 32×32,其他 native window 按实际 r() 结果
sm visual wrappersstepper-zero-range-*-visualr(28)×r(28) / r(40)×r(28) / r(28)×r(28);outer 按 md/sm 公式至少 44pt

Web Inspector 检查中央 role=slider、aria-valuemin/max/now、disabled 与 tab order;键盘逐一验证 ArrowUp/Right、ArrowDown/Left、Home、End。iOS 需要分别检查过滤后的 custom action 列表与标准 adjustable 手势:无效标准方向可能派发,但业务值和 unexpected 计数必须不变。RN 宽屏 Inspector 还要确认动态 outer 包住完整 scaled visual。stepper-zero-range-value 必须上报 disabled 且没有 handler。这些人工行只有真实执行后才能记为 PASS。

使用注意​

  • 需要直接编辑时使用 editable;非编辑显示单位仍用 formatValue。
  • ❌ 不要用覆盖层替换 Stepper 中央值;单位文案用 formatValue,数值行为仍由 Stepper 持有
  • ❌ 不要省略或复用无上下文的 accessibilityLabel——名称应说明正在调整哪个业务值
  • ❌ 不要去掉描边或圆角——Stepper 必须看起来"可点击"