Stepper 步进器

用于在一定范围内输入、调整数字，支持数量增减、禁用、步长、边框/无边框、Din字体等多种功能。

用法

基本引入

import { FQStepper } from '@fq/fq-weapp-ui';

基础用法

<FQStepper value={1} onChange={(val) => console.log(val)} />

非受控用法

<FQStepper defaultValue={2} expanded onChange={(val) => console.log(val)} />

展开形态

<FQStepper value={1} expanded onChange={(val) => console.log(val)} />

禁用状态

<FQStepper value={5} expanded disabled />

边界限制

<FQStepper value={1} expanded min={1} />

步长设置

<FQStepper value={2} expanded step={2} />

无边框样式

<FQStepper value={1} expanded variant="borderless" />

自定义尺寸

<FQStepper
  value={708}
  expanded
  buttonSize="32px"
  inputWidth="72px"
  fontSize="18px"
/>

自定义占位符

<FQStepper
  value={708}
  expanded
  placeholder="请输入数量"
  inputWidth="66px"
/>

事件监听

const max = 5;
const min = -2;

<FQStepper 
  value={1} 
  onChange={(value) => console.log(value)} 
  max={max}
  min={min}
  onBlur={e => {
    console.log('onBlur event:', e);
    setValue(false);
  }}
  onFocus={e => {
    console.log('onFocus event:', e);
    setValue(true);
  }}
  onIncrement={(_, val) => {
    console.log('onIncrement new value', val)
    if (val > max) {
      alert('超过最大值提示文案');
      return false;
    }

    return true;
  }}
  onDecrement={(_, val) => {
    console.log('onDecrement new value', val)
    if (val < min) {
      alert('超过最小值提示文案');
      return false;
    }

    return true;
  }}
  onInputMax={val => {
    console.log('onInputMax event:', val);
  }}
/>

---

属性说明

基础属性

属性	说明	类型	默认值
value	当前数值（受控）	number	-
defaultValue	默认数值（非受控）	number	min(1)
min	最小值	number	1
max	最大值	number	+∞
step	步长	number	1
disabled	是否禁用	boolean	false
expanded	是否展开（增减形态）	boolean	false
expandable	是否允许从数量显示切换为增减形态	boolean	true
buttonSize	按钮大小	string | number	26px
fontSize	字体大小	string | number	13px
inputWidth	输入框宽度	string | number	36px
variant	形态变体	'outlined' | 'borderless'	outlined
placeholder	输入框占位符	string	-
style	自定义样式	CSSProperties	-
className	自定义样式类名	string	-

说明：

• 尺寸类属性支持 number 和带单位字符串。number 会按 px 处理；字符串支持 px/rpx 等常见单位。
• variant 为 outlined 时，组件使用边框效果；borderless 时按钮为独立浅灰块，中央数字无边框。

事件属性

属性	说明	类型	默认值
onChange	数值变化时回调（确认/失焦/按钮）	(value: number) => void	-
onFocus	输入框获得焦点时回调	InputProps['onFocus']	-
onBlur	输入框失去焦点时回调	InputProps['onBlur']	-
onInput	输入框值改变时的回调	(value: number) => void	-
onInputMax	输入框输入到达最大值时触发	(value: number) => void	-
onDecrement	点击减小按钮时触发，返回 false 阻止值变化	(e: ITouchEvent, value: number) => boolean | void	-
onIncrement	点击增加按钮时触发，返回 false 阻止值变化	(e: ITouchEvent, value: number) => boolean | void	-

---

交互说明

• 受控模式：传入 value，组件值由外部状态驱动。
• 非受控模式：不传 value，可通过 defaultValue 指定初始值，后续由组件内部维护。
• 输入阶段：仅在点击键盘的确认按钮/失焦或点击按钮时提交并触发 onChange。
• onDecrement/onIncrement 支持返回 false，可阻止步进器数值变化。

---