@ticatec/uniface-element 0.2.3 → 0.3.0

package/dist/number-editor/README_CN.md

@@ -0,0 +1,357 @@
+# 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) - 用于带单位选择的数字