Stepper

概述

Stepper数字步进器组件，继承自Input，由输入框与-/+按钮组成：点击按钮按步长增减数值，到达边界时对应按钮自动禁用，适合数量、人数等小范围数字的快速调节。原生上下调节按钮已隐藏，数值内容居中显示。

示例

声明一个步进器字段只需要指定widget: 'stepper'，初始值直接使用数字：

const form = document.querySelector('#form');
form.state = {
    count: configurable(1, {
        label: '数量',
        widget: 'stepper',
    }),
};

loading

指南

范围限制

通过min/max限制数值范围。点击-/+按钮时数值会被约束在范围内，到达边界时对应按钮自动禁用：

form.state = {
    age: configurable(25, {
        label: '年龄',
        widget: 'stepper',
        min: 1, 
        max: 120, 
    }),
};

手动键盘输入超出范围的值不会被静默修正，仍走校验链报错（配合required/validate使用）。

步长与小数精度

step控制每次点击-/+按钮的增减幅度，支持小数。小数步长连点产生的浮点误差（如0.1 + 0.2）会按精度自动舍入：

form.state = {
    price: configurable(9.99, {
        label: '价格',
        widget: 'stepper',
        min: 0,
        step: 0.01, 
    }),
    ratio: configurable(0.5, {
        label: '比例',
        widget: 'stepper',
        step: 0.5,
        precision: 1, 
    }),
};

precision未指定时自动取step的小数位数（step: 0.01即保留 2 位）。

单位前后缀

prefix/suffix在输入框内渲染单位，纯展示用途——状态值始终是number，不参与值拼接：

form.state = {
    weight: configurable(50, {
        label: '重量',
        widget: 'stepper',
        min: 0,
        step: 5,
        prefix: '≈', 
        suffix: 'kg', 
    }),
    budget: configurable(1000, {
        label: '预算',
        widget: 'stepper',
        min: 0,
        step: 100,
        prefix: '¥', 
    }),
};

布局顺序固定为[−] [前缀] 输入值 [后缀] [+]：-/+按钮始终在最外侧，单位紧贴输入值。视图态（viewonly）同样渲染前缀+值+后缀。

宽度

输入框默认宽度12em。通过width选项可自定义，设置后输入框撑满指定宽度：

form.state = {
    count: configurable(1, {
        label: '数量',
        widget: 'stepper',
        width: '300px', 
    }),
};

属性

属性	类型	默认值	说明
step	number	1	步长（-/+ 按钮的增减幅度，支持小数）
precision	number		小数精度（保留位数），缺省时取step的小数位数
prefix	string		单位前缀（纯展示，渲染在-按钮之后、输入值之前）
suffix	string		单位后缀（纯展示，渲染在输入值之后、+按钮之前）
min	number		最小值，到达时-按钮禁用
max	number		最大值，到达时+按钮禁用

注意事项

• Stepper继承自Input，完整属性（clearable、icon、actions、filled等）见Input。
• 状态值是number类型，初始值请直接声明为数字（如configurable(1, ...)），不要写成字符串。
• 单位前后缀是纯展示，不会拼进状态值；需要在值中携带单位时请自行使用toState/toInput转换。
• 值为空（如清空输入框后）点击-/+从0起步，再按min/max约束。
• 原生上下调节按钮（spinner）已隐藏；键盘↑/↓仍走原生步进行为，越界由校验兜底。