@ticatec/uniface-element 0.2.0 → 0.2.2

package/docs/form-components/cn/datetime-picker.md

@@ -0,0 +1,228 @@
+# DateTimePicker 组件
+
+日期时间选择器组件。
+
+## 属性
+
+| 属性 | 类型 | 默认值 | 描述 |
+|------|------|--------|------|
+| `variant` | `'' \| 'plain' \| 'outlined' \| 'filled'` | `''` | 外观变体 |
+| `disabled` | `boolean` | `false` | 是否禁用 |
+| `readonly` | `boolean` | `false` | 是否只读 |
+| `compact` | `boolean` | `false` | 是否紧凑模式 |
+| `value` | `Date \| string \| null` | `null` | 日期时间值 |
+| `format` | `string` | `'YYYY-MM-DD HH:mm'` | 日期时间格式 |
+| `placeholder` | `string` | `''` | 占位符文本 |
+| `displayMode` | `DisplayMode` | `DisplayMode.Edit` | 显示模式 |
+| `minDateTime` | `Date \| string \| null` | `null` | 最小日期时间 |
+| `maxDateTime` | `Date \| string \| null` | `null` | 最大日期时间 |
+| `minuteStep` | `number` | `1` | 分钟步长 |
+| `locale` | `string` | `'zh-CN'` | 语言区域 |
+| `style` | `string` | `''` | 自定义样式 |
+| `onChange` | `OnChangeHandler<Date>` | - | 值变化回调 |
+
+## 使用示例
+
+```svelte
+<script lang="ts">
+  import DateTimePicker from '@ticatec/uniface-element/DateTimePicker';
+  
+  let appointmentTime: Date | null = null;
+  let eventStartTime: Date = new Date();
+  let eventEndTime: Date | null = null;
+  
+  const handleAppointmentChange = (dateTime: Date): void => {
+    appointmentTime = dateTime;
+    console.log('预约时间：', dateTime);
+  };
+  
+  const handleEventStartChange = (dateTime: Date): void => {
+    eventStartTime = dateTime;
+    // 自动设置结束时间为开始时间后1小时
+    if (!eventEndTime) {
+      eventEndTime = new Date(dateTime.getTime() + 60 * 60 * 1000);
+    }
+  };
+  
+  const handleEventEndChange = (dateTime: Date): void => {
+    eventEndTime = dateTime;
+  };
+</script>
+
+<!-- 预约时间选择 -->
+<DateTimePicker 
+  placeholder="请选择预约时间"
+  minDateTime={new Date()}
+  minuteStep={15}
+  bind:value={appointmentTime}
+  onChange={handleAppointmentChange}
+/>
+
+<!-- 事件开始时间 -->
+<DateTimePicker 
+  placeholder="请选择开始时间"
+  bind:value={eventStartTime}
+  onChange={handleEventStartChange}
+/>
+
+<!-- 事件结束时间 -->
+<DateTimePicker 
+  placeholder="请选择结束时间"
+  minDateTime={eventStartTime}
+  bind:value={eventEndTime}
+  onChange={handleEventEndChange}
+/>
+```
+
+## 高级用法
+
+### 会议室预订
+```svelte
+<script lang="ts">
+  interface MeetingSlot {
+    start: Date;
+    end: Date;
+    duration: number; // 分钟
+  }
+  
+  let meetingStart: Date | null = null;
+  let meetingEnd: Date | null = null;
+  
+  // 工作时间限制
+  const getWorkingHourLimits = (date: Date): { min: Date; max: Date } => {
+    const workStart = new Date(date);
+    workStart.setHours(9, 0, 0, 0);
+    
+    const workEnd = new Date(date);
+    workEnd.setHours(18, 0, 0, 0);
+    
+    return { min: workStart, max: workEnd };
+  };
+  
+  const handleMeetingStartChange = (startTime: Date): void => {
+    meetingStart = startTime;
+    
+    // 自动设置结束时间（默认1小时后）
+    if (!meetingEnd) {
+      meetingEnd = new Date(startTime.getTime() + 60 * 60 * 1000);
+    }
+  };
+  
+  const calculateDuration = (start: Date | null, end: Date | null): number => {
+    if (!start || !end) return 0;
+    return Math.round((end.getTime() - start.getTime()) / (1000 * 60));
+  };
+  
+  $: meetingDuration = calculateDuration(meetingStart, meetingEnd);
+  $: workingLimits = meetingStart ? getWorkingHourLimits(meetingStart) : null;
+</script>
+
+<div class="meeting-booking">
+  <div class="datetime-field">
+    <label>会议开始时间：</label>
+    <DateTimePicker 
+      placeholder="请选择开始时间"
+      minDateTime={new Date()}
+      minuteStep={15}
+      bind:value={meetingStart}
+      onChange={handleMeetingStartChange}
+    />
+  </div>
+  
+  <div class="datetime-field">
+    <label>会议结束时间：</label>
+    <DateTimePicker 
+      placeholder="请选择结束时间"
+      minDateTime={meetingStart}
+      maxDateTime={workingLimits?.max}
+      minuteStep={15}
+      bind:value={meetingEnd}
+    />
+  </div>
+  
+  {#if meetingDuration > 0}
+    <div class="duration-info">
+      会议时长：{Math.floor(meetingDuration / 60)}小时{meetingDuration % 60}分钟
+    </div>
+  {/if}
+  
+  {#if workingLimits && meetingEnd && meetingEnd > workingLimits.max}
+    <div class="warning">注意：会议结束时间超出工作时间</div>
+  {/if}
+</div>
+```
+
+## 最佳实践
+
+### 1. 设置合理的时间范围
+```svelte
+<script lang="ts">
+  // 预约：只能选择未来时间
+  const futureOnly: Date = new Date();
+  futureOnly.setMinutes(futureOnly.getMinutes() + 30); // 至少提前30分钟
+  
+  // 工作时间：限制在工作日的工作时间内
+  const isWorkingTime = (date: Date): boolean => {
+    const day: number = date.getDay();
+    const hour: number = date.getHours();
+    return day >= 1 && day <= 5 && hour >= 9 && hour <= 18;
+  };
+</script>
+
+<!-- 预约系统 -->
+<DateTimePicker 
+  minDateTime={futureOnly}
+  minuteStep={30}
+  placeholder="选择预约时间"
+/>
+```
+
+### 2. 本地化和格式化
+```svelte
+<DateTimePicker 
+  locale="zh-CN"
+  format="YYYY年MM月DD日 HH:mm"
+  placeholder="请选择日期时间"
+/>
+
+<DateTimePicker 
+  locale="en-US"
+  format="MM/DD/YYYY hh:mm A"
+  placeholder="Select date and time"
+/>
+```
+
+### 3. 表单验证
+```svelte
+<script lang="ts">
+  let selectedDateTime: Date | null = null;
+  let error: string = '';
+  
+  const validateDateTime = (dateTime: Date | null): void => {
+    if (!dateTime) {
+      error = '请选择日期时间';
+      return;
+    }
+    
+    const now: Date = new Date();
+    const minTime: Date = new Date(now.getTime() + 24 * 60 * 60 * 1000); // 24小时后
+    
+    if (dateTime < minTime) {
+      error = '请选择24小时后的时间';
+      return;
+    }
+    
+    error = '';
+  };
+  
+  $: validateDateTime(selectedDateTime);
+</script>
+
+<DateTimePicker 
+  bind:value={selectedDateTime}
+  onChange={validateDateTime}
+/>
+{#if error}
+  <div class="error-message">{error}</div>
+{/if}
+```

package/docs/form-components/cn/group-checkbox.md

@@ -0,0 +1,405 @@
+# GroupCheckBox 组件
+
+复选框组组件，将多个复选框选项组织在一起，支持位运算和字符串分隔符两种值存储模式。通常用于多选场景，比单独使用多个CheckBox更加方便。
+
+## 属性
+
+| 属性 | 类型 | 默认值 | 描述 |
+|------|------|--------|------|
+| `variant` | `'' \| 'plain' \| 'outlined' \| 'filled'` | `''` | 外观变体 |
+| `disabled` | `boolean` | `false` | 是否禁用 |
+| `readonly` | `boolean` | `false` | 是否只读 |
+| `compact` | `boolean` | `false` | 是否紧凑模式 |
+| `value` | `string \| number` | - | 选中的值（字符串或位值） |
+| `bitBase` | `boolean` | `false` | 是否使用位运算模式 |
+| `options` | `Array<OptionItem>` | - | 选项数组 |
+| `keyField` | `string` | `'code'` | 值字段名 |
+| `textField` | `string` | `'text'` | 显示字段名 |
+| `delimiter` | `string` | `';'` | 字符串模式下的分隔符 |
+| `displayMode` | `DisplayMode` | `DisplayMode.Edit` | 显示模式 |
+| `item$style` | `string` | `''` | 单个复选框的样式 |
+| `disabledOptions` | `Array<string>` | `[]` | 禁用的选项值 |
+| `hideOptions` | `Array<string>` | `[]` | 隐藏的选项值 |
+| `style` | `string` | `''` | 自定义样式 |
+| `onChange` | `OnChangeHandler<string \| number>` | - | 值变化回调 |
+
+## 使用示例
+
+```svelte
+<script lang="ts">
+  import type { OptionItem } from '@ticatec/uniface-element/types';
+  import GroupCheckBox from '@ticatec/uniface-element/GroupCheckBox';
+  
+  // 权限选项
+  const permissions: OptionItem[] = [
+    { code: 'read', text: '读取权限' },
+    { code: 'write', text: '写入权限' },
+    { code: 'delete', text: '删除权限' },
+    { code: 'admin', text: '管理权限' }
+  ];
+  
+  // 兴趣爱好选项
+  const hobbies: OptionItem[] = [
+    { code: 'sports', text: '运动' },
+    { code: 'music', text: '音乐' },
+    { code: 'reading', text: '阅读' },
+    { code: 'travel', text: '旅行' },
+    { code: 'cooking', text: '烹饪' }
+  ];
+  
+  let userPermissions: number = 0; // 使用位运算
+  let userHobbies: string = ''; // 使用字符串分隔符
+  let userSkills: string = '';
+  
+  const handlePermissionChange = (value: number): void => {
+    userPermissions = value;
+    console.log('用户权限（位值）：', value);
+    
+    // 解析位值以查看具体权限
+    const selectedPermissions: string[] = [];
+    let bitValue: number = value;
+    let index: number = 0;
+    while (bitValue > 0) {
+      if (bitValue & 1) {
+        selectedPermissions.push(permissions[index].text);
+      }
+      bitValue >>= 1;
+      index++;
+    }
+    console.log('选中的权限：', selectedPermissions);
+  };
+  
+  const handleHobbiesChange = (value: string): void => {
+    userHobbies = value;
+    console.log('用户爱好：', value);
+  };
+</script>
+
+<!-- 权限选择（位运算模式） -->
+<div class="form-group">
+  <label>用户权限：</label>
+  <GroupCheckBox 
+    options={permissions}
+    keyField="code"
+    textField="text"
+    bitBase={true}
+    bind:value={userPermissions}
+    onChange={handlePermissionChange}
+  />
+</div>
+
+<!-- 兴趣爱好选择（字符串分隔符模式） -->
+<div class="form-group">
+  <label>兴趣爱好：</label>
+  <GroupCheckBox 
+    options={hobbies}
+    keyField="code"
+    textField="text"
+    delimiter=";"
+    bind:value={userHobbies}
+    onChange={handleHobbiesChange}
+  />
+</div>
+
+<!-- 紧凑模式的复选框组 -->
+<div class="form-group">
+  <label>技能标签：</label>
+  <GroupCheckBox 
+    options={[
+      { code: 'js', text: 'JavaScript' },
+      { code: 'ts', text: 'TypeScript' },
+      { code: 'svelte', text: 'Svelte' },
+      { code: 'vue', text: 'Vue.js' }
+    ]}
+    keyField="code"
+    textField="text"
+    compact={true}
+    item$style="margin-right: 12px;"
+    bind:value={userSkills}
+  />
+</div>
+```
+
+## 位运算模式说明
+
+当 `bitBase` 为 `true` 时，组件使用位运算来存储选中状态：
+- 第1个选项：位值 1 (二进制 0001)
+- 第2个选项：位值 2 (二进制 0010)  
+- 第3个选项：位值 4 (二进制 0100)
+- 第4个选项：位值 8 (二进制 1000)
+
+选择多个选项时，位值相加。例如选择第1和第3个选项，值为 1 + 4 = 5。
+
+### 位运算工具函数
+
+```typescript
+// 检查是否包含某个权限
+const hasPermission = (permissions: number, permission: string): boolean => {
+  const permissionIndex: number = permissionList.findIndex(p => p.code === permission);
+  return (permissions & (1 << permissionIndex)) !== 0;
+};
+
+// 添加权限
+const addPermission = (permissions: number, permission: string): number => {
+  const permissionIndex: number = permissionList.findIndex(p => p.code === permission);
+  return permissions | (1 << permissionIndex);
+};
+
+// 移除权限
+const removePermission = (permissions: number, permission: string): number => {
+  const permissionIndex: number = permissionList.findIndex(p => p.code === permission);
+  return permissions & ~(1 << permissionIndex);
+};
+
+// 解析权限列表
+const parsePermissions = (permissions: number): string[] => {
+  const result: string[] = [];
+  let bitValue: number = permissions;
+  let index: number = 0;
+  while (bitValue > 0) {
+    if (bitValue & 1) {
+      result.push(permissionList[index].code);
+    }
+    bitValue >>= 1;
+    index++;
+  }
+  return result;
+};
+```
+
+## 高级用法
+
+### 动态选项加载
+```svelte
+<script lang="ts">
+  import type { OptionItem } from '@ticatec/uniface-element/types';
+  import { onMount } from 'svelte';
+  
+  let options: OptionItem[] = [];
+  let selectedValues: string = '';
+  let loading: boolean = true;
+  
+  onMount(async (): Promise<void> => {
+    try {
+      const response: Response = await fetch('/api/categories');
+      options = await response.json();
+    } catch (error) {
+      console.error('加载选项失败：', error);
+    } finally {
+      loading = false;
+    }
+  });
+  
+  const saveUserPreferences = async (preferences: string): Promise<void> => {
+    // 实现保存逻辑
+  };
+  
+  const handleChange = (value: string): void => {
+    selectedValues = value;
+    // 同步到服务器
+    saveUserPreferences(value);
+  };
+</script>
+
+{#if loading}
+  <div class="loading">加载选项中...</div>
+{:else}
+  <GroupCheckBox 
+    {options}
+    keyField="id"
+    textField="name"
+    bind:value={selectedValues}
+    onChange={handleChange}
+  />
+{/if}
+```
+
+### 条件禁用和隐藏
+```svelte
+<script lang="ts">
+  import type { OptionItem } from '@ticatec/uniface-element/types';
+  
+  type UserLevel = 'basic' | 'premium' | 'enterprise';
+  
+  const features: OptionItem[] = [
+    { code: 'basic', text: '基础功能' },
+    { code: 'advanced', text: '高级功能' },
+    { code: 'premium', text: '高级功能' },
+    { code: 'enterprise', text: '企业功能' }
+  ];
+  
+  let userLevel: UserLevel = 'basic'; // basic, premium, enterprise
+  let selectedFeatures: string = '';
+  
+  // 根据用户级别动态设置禁用选项
+  $: disabledOptions = ((): string[] => {
+    switch (userLevel) {
+      case 'basic':
+        return ['advanced', 'premium', 'enterprise'];
+      case 'premium':
+        return ['enterprise'];
+      case 'enterprise':
+        return [];
+      default:
+        return ['advanced', 'premium', 'enterprise'];
+    }
+  })();
+  
+  // 隐藏企业功能（如果不是企业用户）
+  $: hideOptions: string[] = userLevel !== 'enterprise' ? ['enterprise'] : [];
+</script>
+
+<div class="form-group">
+  <label>用户级别：</label>
+  <select bind:value={userLevel}>
+    <option value="basic">基础用户</option>
+    <option value="premium">高级用户</option>
+    <option value="enterprise">企业用户</option>
+  </select>
+</div>
+
+<div class="form-group">
+  <label>可用功能：</label>
+  <GroupCheckBox 
+    options={features}
+    keyField="code"
+    textField="text"
+    {disabledOptions}
+    hideOptions={hideOptions}
+    bind:value={selectedFeatures}
+  />
+</div>
+```
+
+### 全选/全不选功能
+```svelte
+<script lang="ts">
+  import type { OptionItem } from '@ticatec/uniface-element/types';
+  
+  const allOptions: OptionItem[] = [
+    { code: 'option1', text: '选项1' },
+    { code: 'option2', text: '选项2' },
+    { code: 'option3', text: '选项3' },
+    { code: 'option4', text: '选项4' }
+  ];
+  
+  let selectedValues: string = '';
+  
+  // 检查是否全选
+  $: isAllSelected = ((): boolean => {
+    if (!selectedValues) return false;
+    const selected: string[] = selectedValues.split(';');
+    return allOptions.every(option => selected.includes(option.code));
+  })();
+  
+  // 检查是否有部分选中
+  $: isIndeterminate = ((): boolean => {
+    if (!selectedValues) return false;
+    const selected: string[] = selectedValues.split(';');
+    return selected.length > 0 && selected.length < allOptions.length;
+  })();
+  
+  const handleSelectAll = (checked: boolean): void => {
+    if (checked) {
+      selectedValues = allOptions.map(opt => opt.code).join(';');
+    } else {
+      selectedValues = '';
+    }
+  };
+  
+  const handleChange = (value: string): void => {
+    selectedValues = value;
+  };
+</script>
+
+<div class="select-all-container">
+  <CheckBox 
+    label="全选"
+    value={isAllSelected}
+    indeterminate={isIndeterminate}
+    onChange={handleSelectAll}
+  />
+</div>
+
+<GroupCheckBox 
+  options={allOptions}
+  keyField="code"
+  textField="text"
+  bind:value={selectedValues}
+  onChange={handleChange}
+/>
+```
+
+## 样式定制
+
+```css
+.form-group {
+  margin-bottom: 20px;
+}
+
+.form-group label {
+  display: block;
+  margin-bottom: 8px;
+  font-weight: 500;
+  color: #333;
+}
+
+.select-all-container {
+  padding: 8px 0;
+  border-bottom: 1px solid #e1e5e9;
+  margin-bottom: 12px;
+}
+
+.loading {
+  padding: 20px;
+  text-align: center;
+  color: #6c757d;
+}
+
+/* 自定义复选框组样式 */
+.custom-checkbox-group {
+  display: grid;
+  grid-template-columns: repeat(auto-fit, minmax(200px, 1fr));
+  gap: 12px;
+  padding: 16px;
+  background: #f8f9fa;
+  border-radius: 8px;
+}
+```
+
+## 组件优势
+
+**相比单独使用CheckBox的优势：**
+
+1. **统一管理**：所有相关选项集中在一个组件中管理
+2. **数据绑定简化**：只需绑定一个值，而不是多个独立的值
+3. **样式一致性**：所有选项具有统一的样式和间距
+4. **选项动态管理**：可以轻松地显示/隐藏、启用/禁用特定选项
+5. **位运算支持**：适合权限系统等需要位运算的场景
+6. **更好的语义化**：明确表达了选项之间的关联关系
+
+## 最佳实践
+
+### 1. 选择合适的存储模式
+```svelte
+<!-- 权限系统：使用位运算 -->
+<GroupCheckBox bitBase={true} />
+
+<!-- 普通多选：使用字符串分隔符 -->
+<GroupCheckBox delimiter="," />
+```
+
+### 2. 提供清晰的标签
+```svelte
+<label>请选择您感兴趣的技术栈：</label>
+<GroupCheckBox 
+  options={techStack}
+  placeholder="选择技术栈"
+/>
+```
+
+### 3. 合理使用紧凑模式
+```svelte
+<!-- 选项较多时使用紧凑模式 -->
+<GroupCheckBox compact={true} />
+```