# NumberEditor 数字输入框

一个强大的数字输入组件，提供精度控制、验证和数字数据输入格式化功能。

## 功能特性

- **精度控制**: 配置小数位数以实现精确的数字格式化
- **范围验证**: 设置最小/最大值并自动执行边界检查
- **负数支持**: 可选的负数值支持
- **自定义格式化**: 添加前缀/后缀文本用于货币、单位等
- **输入验证**: 实时验证和适当的错误处理
- **多种变体**: 支持轮廓、填充、朴素和默认样式
- **显示模式**: 在编辑和查看模式之间切换
- **操作图标**: 内置清除功能和可自定义图标
- **焦点管理**: 通过setFocus方法进行程序化焦点控制

## 安装

```bash
npm install @ticatec/uniface-element
```

## 基本用法

```svelte
<script>
  import NumberEditor from '@ticatec/uniface-element/NumberEditor';
  
  let price = 29.99;
</script>

<NumberEditor bind:value={price} />
```

## API 参考

### 属性

| 属性 | 类型 | 默认值 | 描述 |
|------|------|---------|-------------|
| `value` | `number \| null` | `undefined` | 当前数字值 |
| `disabled` | `boolean` | `false` | 禁用输入框 |
| `readonly` | `boolean` | `false` | 设置输入框为只读 |
| `variant` | `'' \| 'plain' \| 'outlined' \| 'filled'` | `''` | 视觉样式变体 |
| `compact` | `boolean` | `false` | 启用紧凑显示模式 |
| `style` | `string` | `''` | 自定义CSS样式 |
| `placeholder` | `string` | `''` | 占位符文本 |
| `precision` | `number \| null` | `null` | 小数位数 |
| `suffix` | `string` | `''` | 在值后显示的文本 |
| `prefix` | `string` | `''` | 在值前显示的文本 |
| `allowNegative` | `boolean` | `false` | 允许负数 |
| `displayMode` | `DisplayMode` | `DisplayMode.Edit` | 编辑或查看模式 |
| `max` | `number \| null` | `null` | 允许的最大值 |
| `min` | `number \| null` | `null` | 允许的最小值 |
| `removable` | `boolean` | `true` | 当有值时显示清除按钮 |
| `onchange` | `OnChangeHandler<number \| null>` | `null` | 变更事件处理器 |
| `class` | `string` | `''` | CSS类名 |

### 方法

| 方法 | 描述 |
|--------|-------------|
| `setFocus()` | 程序化地聚焦输入框 |

### 插槽

| 插槽 | 描述 |
|------|-------------|
| `leading-icon` | 在输入框前显示的图标 |
| `trailing-icon` | 在输入框后显示的图标 |

## 示例

### 货币输入

```svelte
<script>
  import NumberEditor from '@ticatec/uniface-element/NumberEditor';
  import FormField from '@ticatec/uniface-element/FormField';
  
  let amount = 100.00;
</script>

<FormField label="金额">
  <NumberEditor 
    bind:value={amount}
    variant="outlined"
    precision={2}
    prefix="¥"
    allowNegative={false}
    min={0}
  />
</FormField>
```

### 百分比输入

```svelte
<script>
  import NumberEditor from '@ticatec/uniface-element/NumberEditor';
  
  let percentage = 15.5;
</script>

<NumberEditor 
  bind:value={percentage}
  variant="filled"
  precision={1}
  suffix="%"
  min={0}
  max={100}
/>
```

### 重量/测量输入

```svelte
<script>
  import NumberEditor from '@ticatec/uniface-element/NumberEditor';
  import Icon from '@ticatec/uniface-element/Icon';
  
  let weight = 75.2;
</script>

<NumberEditor 
  bind:value={weight}
  variant="outlined"
  precision={3}
  suffix="KG"
  min={1}
  max={200}
>
  <svelte:fragment slot="leading-icon">
    <Icon name="scale" />
  </svelte:fragment>
</NumberEditor>
```

### 整数输入

```svelte
<script>
  import NumberEditor from '@ticatec/uniface-element/NumberEditor';
  
  let age = 25;
</script>

<NumberEditor 
  bind:value={age}
  variant="outlined"
  precision={0}
  min={0}
  max={120}
  placeholder="输入年龄"
/>
```

### 温度输入（支持负值）

```svelte
<script>
  import NumberEditor from '@ticatec/uniface-element/NumberEditor';
  
  let temperature = -5.5;
</script>

<NumberEditor 
  bind:value={temperature}
  variant="filled"
  precision={1}
  suffix="°C"
  allowNegative={true}
  min={-50}
  max={50}
/>
```

### 财务计算器

```svelte
<script>
  import NumberEditor from '@ticatec/uniface-element/NumberEditor';
  import FormField from '@ticatec/uniface-element/FormField';
  
  let principal = 10000;
  let rate = 5.5;
  let years = 10;
  
  $: interest = (principal * rate * years) / 100;
  
  function handlePrincipalChange(value) {
    console.log('本金变更为:', value);
  }
</script>

<div class="calculator">
  <FormField label="本金金额">
    <NumberEditor 
      bind:value={principal}
      variant="outlined"
      precision={2}
      prefix="¥"
      min={1}
      onchange={handlePrincipalChange}
    />
  </FormField>
  
  <FormField label="利率">
    <NumberEditor 
      bind:value={rate}
      variant="outlined"
      precision={2}
      suffix="%"
      min={0}
      max={100}
    />
  </FormField>
  
  <FormField label="年数">
    <NumberEditor 
      bind:value={years}
      variant="outlined"
      precision={0}
      min={1}
      max={50}
    />
  </FormField>
  
  <FormField label="总利息">
    <NumberEditor 
      value={interest}
      readonly
      variant="filled"
      precision={2}
      prefix="¥"
    />
  </FormField>
</div>
```

### 查看模式显示

```svelte
<script>
  import NumberEditor from '@ticatec/uniface-element/NumberEditor';
  import { DisplayMode } from '@ticatec/uniface-element';
  
  let value = 1234.56;
  let isEditing = false;
</script>

<NumberEditor 
  bind:value
  displayMode={isEditing ? DisplayMode.Edit : DisplayMode.View}
  precision={2}
  prefix="¥"
  variant="outlined"
/>

<button on:click={() => isEditing = !isEditing}>
  {isEditing ? '查看' : '编辑'}
</button>
```

### 紧凑表单布局

```svelte
<script>
  import NumberEditor from '@ticatec/uniface-element/NumberEditor';
  
  let dimensions = { width: 100, height: 50, depth: 25 };
</script>

<div class="dimensions-form">
  <NumberEditor 
    bind:value={dimensions.width}
    compact
    variant="outlined"
    precision={2}
    suffix="cm"
    placeholder="宽"
  />
  <span>×</span>
  <NumberEditor 
    bind:value={dimensions.height}
    compact
    variant="outlined"
    precision={2}
    suffix="cm"
    placeholder="高"
  />
  <span>×</span>
  <NumberEditor 
    bind:value={dimensions.depth}
    compact
    variant="outlined"
    precision={2}
    suffix="cm"
    placeholder="深"
  />
</div>

<style>
  .dimensions-form {
    display: flex;
    align-items: center;
    gap: 8px;
  }
</style>
```

## 验证

NumberEditor 根据配置的约束自动验证输入：

- **精度**: 将小数位数限制为指定的精度
- **范围**: 在失焦时强制执行最小/最大边界
- **负数**: 当 `allowNegative` 为 false 时阻止负数输入
- **非数字**: 阻止非数字字符和全角字符
- **实时**: 在输入过程中验证并提供即时反馈

## 最佳实践

1. **使用适当的精度**: 根据数据要求设置精度
2. **设置有意义的范围**: 使用 min/max 防止无效值
3. **提供清晰的标签**: 使用 FormField 包装 NumberEditor 并提供描述性标签
4. **处理变更事件**: 实现 onchange 进行验证或计算
5. **考虑用户体验**: 使用占位符文本和适当的变体样式
6. **明智使用前缀/后缀**: 添加单位或货币符号以提高清晰度
7. **在需要时禁用**: 对计算字段使用 readonly，对不可用输入使用 disabled

## 样式

NumberEditor 支持用于样式的 CSS 自定义属性：

```css
.number-editor {
  --number-editor-font-size: 14px;
  --number-editor-padding: 8px 12px;
  --number-editor-border-color: #e0e0e0;
  --number-editor-focus-color: #1976d2;
}
```

## 无障碍功能

- 适当的 ARIA 标签和角色
- 键盘导航支持
- 屏幕阅读器兼容性
- 焦点管理
- 高对比度模式支持

## 相关组件

- [TextEditor](../text-editor/README.md) - 用于文本输入
- [FormField](../form-field/README.md) - 用于表单布局和标签
- [UnitNumberEditor](../unit-number-editor/README.md) - 用于带单位选择的数字