@ticatec/uniface-element 0.2.0 → 0.2.2

package/docs/form-components/cn/time-editor.md

@@ -0,0 +1,159 @@
+# TimeEditor 组件
+
+时间输入组件，支持小时和分钟的选择。
+
+## 属性
+
+| 属性 | 类型 | 默认值 | 描述 |
+|------|------|--------|------|
+| `variant` | `'' \| 'plain' \| 'outlined' \| 'filled'` | `''` | 外观变体 |
+| `disabled` | `boolean` | `false` | 是否禁用 |
+| `readonly` | `boolean` | `false` | 是否只读 |
+| `compact` | `boolean` | `false` | 是否紧凑模式 |
+| `value` | `string` | `''` | 时间值（格式：HH:MM） |
+| `placeholder` | `string` | `''` | 占位符文本 |
+| `displayMode` | `DisplayMode` | `DisplayMode.Edit` | 显示模式 |
+| `format24h` | `boolean` | `true` | 是否使用24小时格式 |
+| `minuteStep` | `number` | `1` | 分钟步长 |
+| `style` | `string` | `''` | 自定义样式 |
+| `onChange` | `OnChangeHandler<string>` | - | 值变化回调 |
+
+## 使用示例
+
+```svelte
+<script lang="ts">
+  import TimeEditor from '@ticatec/uniface-element/TimeEditor';
+  
+  let startTime: string = '09:00';
+  let endTime: string = '17:30';
+  
+  const handleStartTimeChange = (value: string) => {
+    startTime = value;
+    console.log('开始时间：', value);
+  };
+  
+  const handleEndTimeChange = (value: string) => {
+    endTime = value;
+    console.log('结束时间：', value);
+  };
+</script>
+
+<!-- 开始时间 -->
+<TimeEditor 
+  placeholder="请选择开始时间"
+  bind:value={startTime}
+  onChange={handleStartTimeChange}
+/>
+
+<!-- 结束时间（15分钟间隔） -->
+<TimeEditor 
+  placeholder="请选择结束时间"
+  minuteStep={15}
+  bind:value={endTime}
+  onChange={handleEndTimeChange}
+/>
+```
+
+## 高级用法
+
+### 工作时间设置
+```svelte
+<script lang="ts">
+  interface WorkingHours {
+    start: string;
+    end: string;
+    break_start: string;
+    break_end: string;
+  }
+  
+  let workingHours: WorkingHours = {
+    start: '09:00',
+    end: '18:00',
+    break_start: '12:00',
+    break_end: '13:00'
+  };
+  
+  const updateWorkingHours = (field: keyof WorkingHours) => (value: string) => {
+    workingHours = { ...workingHours, [field]: value };
+  };
+</script>
+
+<div class="working-hours">
+  <div class="time-range">
+    <label>工作时间：</label>
+    <TimeEditor 
+      placeholder="开始时间"
+      minuteStep={30}
+      bind:value={workingHours.start}
+      onChange={updateWorkingHours('start')}
+    />
+    <span>至</span>
+    <TimeEditor 
+      placeholder="结束时间"
+      minuteStep={30}
+      bind:value={workingHours.end}
+      onChange={updateWorkingHours('end')}
+    />
+  </div>
+  
+  <div class="time-range">
+    <label>休息时间：</label>
+    <TimeEditor 
+      placeholder="开始时间"
+      minuteStep={15}
+      bind:value={workingHours.break_start}
+      onChange={updateWorkingHours('break_start')}
+    />
+    <span>至</span>
+    <TimeEditor 
+      placeholder="结束时间"
+      minuteStep={15}
+      bind:value={workingHours.break_end}
+      onChange={updateWorkingHours('break_end')}
+    />
+  </div>
+</div>
+```
+
+## 最佳实践
+
+### 1. 设置合适的步长
+```svelte
+<!-- 会议时间：15分钟间隔 -->
+<TimeEditor minuteStep={15} />
+
+<!-- 工作班次：30分钟间隔 -->
+<TimeEditor minuteStep={30} />
+
+<!-- 精确时间：1分钟间隔 -->
+<TimeEditor minuteStep={1} />
+```
+
+### 2. 时间范围验证
+```svelte
+<script lang="ts">
+  let startTime: string = '';
+  let endTime: string = '';
+  let timeError: string = '';
+  
+  const validateTimeRange = (start: string, end: string): void => {
+    if (start && end) {
+      const startMinutes = timeToMinutes(start);
+      const endMinutes = timeToMinutes(end);
+      
+      if (startMinutes >= endMinutes) {
+        timeError = '结束时间必须晚于开始时间';
+      } else {
+        timeError = '';
+      }
+    }
+  };
+  
+  const timeToMinutes = (time: string): number => {
+    const [hours, minutes] = time.split(':').map(Number);
+    return hours * 60 + minutes;
+  };
+  
+  $: validateTimeRange(startTime, endTime);
+</script>
+```

package/docs/form-components/cn/unit-number-editor.md

@@ -0,0 +1,164 @@
+# UnitNumberEditor 组件
+
+带单位的数字输入组件，允许用户选择不同的计量单位。
+
+## 类型定义
+
+```typescript
+interface UnitOption {
+  code: string;
+  text: string;
+  ratio: number; // 与基础单位的换算比例
+}
+```
+
+## 属性
+
+| 属性 | 类型 | 默认值 | 描述 |
+|------|------|--------|------|
+| `variant` | `'' \| 'plain' \| 'outlined' \| 'filled'` | `''` | 外观变体 |
+| `disabled` | `boolean` | `false` | 是否禁用 |
+| `readonly` | `boolean` | `false` | 是否只读 |
+| `compact` | `boolean` | `false` | 是否紧凑模式 |
+| `value` | `number \| null` | `null` | 数值 |
+| `unit` | `string` | `''` | 当前选择的单位代码 |
+| `units` | `UnitOption[]` | `[]` | 可用单位选项 |
+| `placeholder` | `string` | `''` | 占位符文本 |
+| `displayMode` | `DisplayMode` | `DisplayMode.Edit` | 显示模式 |
+| `precision` | `number \| null` | `null` | 小数位数 |
+| `style` | `string` | `''` | 自定义样式 |
+| `onChange` | `OnChangeHandler<{value: number, unit: string}>` | - | 值变化回调 |
+
+## 使用示例
+
+```svelte
+<script lang="ts">
+  import UnitNumberEditor, { type UnitOption } from '@ticatec/uniface-element/UnitNumberEditor';
+  
+  // 重量单位选项
+  const weightUnits: UnitOption[] = [
+    { code: 'kg', text: '千克', ratio: 1 },
+    { code: 'g', text: '克', ratio: 0.001 },
+    { code: 'lb', text: '磅', ratio: 0.453592 }
+  ];
+  
+  // 距离单位选项
+  const distanceUnits: UnitOption[] = [
+    { code: 'm', text: '米', ratio: 1 },
+    { code: 'cm', text: '厘米', ratio: 0.01 },
+    { code: 'km', text: '公里', ratio: 1000 },
+    { code: 'in', text: '英寸', ratio: 0.0254 }
+  ];
+  
+  let weight: number | null = null;
+  let weightUnit: string = 'kg';
+  let distance: number | null = null;
+  let distanceUnit: string = 'm';
+  
+  interface UnitValue {
+    value: number;
+    unit: string;
+  }
+  
+  const handleWeightChange = ({value, unit}: UnitValue): void => {
+    weight = value;
+    weightUnit = unit;
+    console.log(`重量: ${value} ${unit}`);
+  };
+  
+  const handleDistanceChange = ({value, unit}: UnitValue): void => {
+    distance = value;
+    distanceUnit = unit;
+    console.log(`距离: ${value} ${unit}`);
+  };
+</script>
+
+<!-- 重量输入 -->
+<UnitNumberEditor 
+  placeholder="请输入重量"
+  units={weightUnits}
+  precision={2}
+  bind:value={weight}
+  bind:unit={weightUnit}
+  onChange={handleWeightChange}
+/>
+
+<!-- 距离输入 -->
+<UnitNumberEditor 
+  placeholder="请输入距离"
+  units={distanceUnits}
+  precision={2}
+  bind:value={distance}
+  bind:unit={distanceUnit}
+  onChange={handleDistanceChange}
+/>
+```
+
+## 高级用法
+
+### 单位换算
+```svelte
+<script lang="ts">
+  let inputValue: number | null = null;
+  let inputUnit: string = 'kg';
+  let baseValue: number | null = null; // 基础单位值
+  
+  const convertToBase = (value: number, unit: string, units: UnitOption[]): number => {
+    const unitOption = units.find(u => u.code === unit);
+    return value * (unitOption?.ratio || 1);
+  };
+  
+  const handleValueChange = ({value, unit}: UnitValue): void => {
+    inputValue = value;
+    inputUnit = unit;
+    
+    if (value !== null) {
+      baseValue = convertToBase(value, unit, weightUnits);
+      console.log(`基础值: ${baseValue} kg`);
+    } else {
+      baseValue = null;
+    }
+  };
+</script>
+
+<UnitNumberEditor 
+  placeholder="请输入重量"
+  units={weightUnits}
+  precision={3}
+  bind:value={inputValue}
+  bind:unit={inputUnit}
+  onChange={handleValueChange}
+/>
+
+{#if baseValue !== null}
+  <p>等于: {baseValue.toFixed(3)} kg</p>
+{/if}
+```
+
+## 最佳实践
+
+### 1. 合理设置精度
+```svelte
+<!-- 重量：3位小数 -->
+<UnitNumberEditor units={weightUnits} precision={3} />
+
+<!-- 距离：2位小数 -->
+<UnitNumberEditor units={distanceUnits} precision={2} />
+
+<!-- 温度：1位小数 -->
+<UnitNumberEditor units={temperatureUnits} precision={1} />
+```
+
+### 2. 提供常用单位
+```svelte
+<script lang="ts">
+  // 按使用频率排序
+  const lengthUnits: UnitOption[] = [
+    { code: 'm', text: '米', ratio: 1 },      // 最常用
+    { code: 'cm', text: '厘米', ratio: 0.01 }, // 常用
+    { code: 'mm', text: '毫米', ratio: 0.001 }, // 常用
+    { code: 'km', text: '公里', ratio: 1000 },  // 较少用
+    { code: 'in', text: '英寸', ratio: 0.0254 } // 特殊需求
+  ];
+</script>
+```