# Stepper 步进器

## 说明

参数步进器组件，用于在固定范围内进行数值增减操作。支持数字和字符串两种模式，提供小数精度控制、自定义步长、边界限制、格式化等功能。支持长按自动连续增减。

## 属性

> `StepperProps` 是联合类型：`stringMode?: false` 时 value/min/max/step 为 `number`；`stringMode: true` 时为 `string`。

| 属性 | 说明 | 类型 | 默认值 | 必填 |
|------|------|------|--------|------|
| **value** | 当前值。为 null 时展示 `--`，不显示 prefix/suffix/symbol | `number \| null` / `string \| null` | `null` | 否 |
| **onChange** | 点击加/减后的回调。组件为受控模式，外部需更新 value | `(value) => void` | - | 否 |
| **disabled** | 禁用整个组件（加/减均不可用） | `boolean` | `false` | 否 |
| **step** | 每次增减的步长 | `number` / `string` | - | 否 |
| **min** | 最小值限制（达到后禁用减按钮） | `number` / `string` | - | 否 |
| **max** | 最大值限制（达到后禁用加按钮） | `number` / `string` | - | 否 |
| **digits** | 小数位数。设置后做 toFixed 固定精度 | `number` | - | 否 |
| **stringMode** | 是否启用字符串模式（高精度计算） | `boolean` | `false` | 否 |
| **formatter** | 自定义展示格式化。传入后不显示 prefix/suffix，仅显示格式化后的文本 | `(value?) => string` | - | 否 |
| **prefix** | 前缀（仅 symbolType='custom' 且 value !== null 且无 formatter 时展示） | `React.ReactNode` | - | 否 |
| **suffix** | 后缀（仅 symbolType='custom' 且 value !== null 且无 formatter 时展示） | `React.ReactNode` | - | 否 |
| **suffixSubscript** | degree 模式下的下标图标，仅接受 SVG 或 Image 组件 | `ReactElement<SvgProps> \| ReactElement<{ source }>` | - | 否 |
| **iconType** | 左右按钮图标类型。plusMinus 对应 +/-，leftRight 对应左右箭头 | `'plusMinus' \| 'leftRight'` | `'plusMinus'` | 否 |
| **symbolType** | 右侧符号类型。percent 显示百分号（整数），degree 显示温度符号，custom 使用 prefix/suffix | `'percent' \| 'degree' \| 'custom'` | `'custom'` | 否 |
| **accessibilityText** | 中间文本区域的无障碍配置 | `AccessibilityPropsType` | - | 否 |

## 使用示例

```tsx
import React, { useState } from 'react';
import { ParamStepper } from '@hyperOS/IotComponents/paramStepper';
import { Cold } from '@icons/index';

// 1) 数字模式（默认）
function DemoNumber() {
  const [count, setCount] = useState(0);
  return <ParamStepper value={count} onChange={setCount} min={0} max={10} />;
}

// 2) 温度模式 + 下标图标
function DemoTemperature() {
  const [temp, setTemp] = useState(26);
  return (
    <ParamStepper
      value={temp}
      onChange={setTemp}
      step={0.5}
      digits={1}
      symbolType="degree"
      suffixSubscript={<Cold fill="#0099FF" />}
      min={16}
      max={30}
    />
  );
}

// 3) 百分比模式
function DemoPercent() {
  const [pct, setPct] = useState(50);
  return <ParamStepper value={pct} onChange={setPct} symbolType="percent" min={0} max={100} />;
}

// 4) 左右箭头按钮
function DemoLeftRight() {
  const [v, setV] = useState(1);
  return <ParamStepper value={v} onChange={setV} iconType="leftRight" />;
}

// 5) 自定义格式化（formatter 传入后不显示 prefix/suffix）
function DemoFormatter() {
  const [v, setV] = useState(3);
  return (
    <ParamStepper
      value={v}
      onChange={setV}
      formatter={(val) => `${val}档`}
      min={1}
      max={5}
    />
  );
}

// 6) 字符串模式（高精度）
function DemoStringMode() {
  const [amount, setAmount] = useState('0');
  return (
    <ParamStepper
      value={amount}
      onChange={setAmount}
      stringMode
      step="0.01"
      min="0"
      max="9999.99"
      prefix="$"
    />
  );
}
```

## 注意事项

- `symbolType='percent'` 时强制整数，忽略 `digits` 设置
- `formatter` 存在时不显示 `prefix`/`suffix`，仅显示格式化后的文本
- `suffixSubscript` 仅在 `symbolType='degree'` 时生效
- `value === null` 时显示 `--`，不显示任何符号/前后缀