@ticatec/uniface-element 0.2.3 → 0.3.0

package/dist/group-box/group-check-box/README_CN.md

@@ -0,0 +1,750 @@
+# GroupCheckBox 组复选框组件
+
+一个灵活的组复选框组件，允许用户从预定义的选项列表中选择多个选项。支持基于字符串和基于位的值存储、自定义样式变体以及全面的状态管理，包括焦点/失焦事件处理。
+
+## 安装
+
+```bash
+npm install @ticatec/uniface-element
+```
+
+## 导入
+
+```typescript
+import GroupCheckBox from "@ticatec/uniface-element/GroupCheckBox";
+import { DisplayMode } from "@ticatec/uniface-element";
+import type { OnChangeHandler } from "@ticatec/uniface-element";
+```
+
+## 基本用法
+
+```svelte
+<script>
+  import GroupCheckBox from "@ticatec/uniface-element/GroupCheckBox";
+  
+  const options = [
+    { code: "js", text: "JavaScript" },
+    { code: "ts", text: "TypeScript" },
+    { code: "py", text: "Python" },
+    { code: "go", text: "Go" }
+  ];
+  
+  let selectedLanguages = "";
+  
+  function handleChange(value) {
+    console.log('选择的编程语言:', value);
+  }
+</script>
+
+<GroupCheckBox 
+  {options} 
+  bind:value={selectedLanguages}
+  onchange={handleChange}
+/>
+```
+
+## 属性
+
+| 属性 | 类型 | 默认值 | 描述 |
+|------|------|---------|-------------|
+| `value` | `string \| number` | 必需 | 选中的值（带分隔符的字符串或位值） |
+| `options` | `Array<any>` | 必需 | 选项对象数组 |
+| `keyField` | `string` | `"code"` | 选项键/值的字段名称 |
+| `textField` | `string` | `"text"` | 选项显示文本的字段名称 |
+| `delimiter` | `string` | `";"` | 基于字符串的值的分隔符 |
+| `bitBase` | `boolean` | `false` | 是否使用基于位的值存储 |
+| `disabled` | `boolean` | `false` | 组件是否禁用 |
+| `readonly` | `boolean` | `false` | 组件是否只读 |
+| `displayMode` | `DisplayMode` | `DisplayMode.Edit` | 显示模式（编辑或查看） |
+| `variant` | `"" \| "plain" \| "outlined" \| "filled"` | `""` | 视觉变体 |
+| `compact` | `boolean` | `false` | 是否使用紧凑间距 |
+| `disabledOptions` | `Array<string>` | `[]` | 要禁用的选项键数组 |
+| `hideOptions` | `Array<string>` | `[]` | 要隐藏的选项键数组 |
+| `style` | `string` | `""` | 附加 CSS 样式 |
+| `item$style` | `string` | `""` | 单个复选框项目的 CSS 样式 |
+| `onchange` | `OnChangeHandler<string \| number>` | `null` | 更改事件处理程序 |
+| `onfocus` | `(() => void) \| null` | `null` | 焦点事件处理程序 |
+| `onblur` | `(() => void) \| null` | `null` | 失焦事件处理程序 |
+
+## 方法
+
+| 方法 | 描述 |
+|--------|-------------|
+| `setFocus()` | 以编程方式聚焦第一个启用的复选框 |
+
+## 示例
+
+### 基于字符串的选择
+
+```svelte
+<script>
+  import GroupCheckBox from "@ticatec/uniface-element/GroupCheckBox";
+  import FormField from "@ticatec/uniface-element/FormField";
+  
+  const technologies = [
+    { code: "react", text: "React" },
+    { code: "vue", text: "Vue.js" },
+    { code: "svelte", text: "Svelte" },
+    { code: "angular", text: "Angular" }
+  ];
+  
+  let selectedTech = "";
+  
+  function handleTechChange(value) {
+    console.log('选择的技术:', value);
+    console.log('数组形式:', value ? value.split(';') : []);
+  }
+</script>
+
+<div class="demo-section">
+  <FormField label="选择您偏好的技术">
+    <GroupCheckBox 
+      options={technologies}
+      bind:value={selectedTech}
+      onchange={handleTechChange}
+      onfocus={() => console.log('获得焦点')}
+      onblur={() => console.log('失去焦点')}
+    />
+  </FormField>
+  
+  <p>已选择: {selectedTech || '无'}</p>
+</div>
+
+<style>
+  .demo-section {
+    margin: 20px;
+    padding: 20px;
+    border: 1px solid #e2e8f0;
+    border-radius: 8px;
+  }
+</style>
+```
+
+### 基于位的选择以提高性能
+
+```svelte
+<script>
+  import GroupCheckBox from "@ticatec/uniface-element/GroupCheckBox";
+  import FormField from "@ticatec/uniface-element/FormField";
+  
+  const permissions = [
+    { code: "read", text: "读取" },      // 位 0（值 1）
+    { code: "write", text: "写入" },    // 位 1（值 2）
+    { code: "delete", text: "删除" },  // 位 2（值 4）
+    { code: "admin", text: "管理员" }     // 位 3（值 8）
+  ];
+  
+  let userPermissions = 0;
+  
+  function handlePermissionChange(value) {
+    console.log('权限位:', value);
+    console.log('二进制表示:', value.toString(2));
+    
+    // 解码权限
+    const activePermissions = [];
+    permissions.forEach((perm, index) => {
+      if (value & (1 << index)) {
+        activePermissions.push(perm.text);
+      }
+    });
+    console.log('活跃权限:', activePermissions);
+  }
+  
+  // 检查特定权限是否启用
+  function hasPermission(permissionBit) {
+    return (userPermissions & (1 << permissionBit)) !== 0;
+  }
+</script>
+
+<div class="permissions-demo">
+  <FormField label="用户权限">
+    <GroupCheckBox 
+      options={permissions}
+      bitBase={true}
+      bind:value={userPermissions}
+      onchange={handlePermissionChange}
+    />
+  </FormField>
+  
+  <div class="permission-info">
+    <p>权限值: {userPermissions}</p>
+    <p>二进制: {userPermissions.toString(2).padStart(4, '0')}</p>
+    <div class="permission-checks">
+      <p>可读取: {hasPermission(0) ? '✓' : '✗'}</p>
+      <p>可写入: {hasPermission(1) ? '✓' : '✗'}</p>
+      <p>可删除: {hasPermission(2) ? '✓' : '✗'}</p>
+      <p>是管理员: {hasPermission(3) ? '✓' : '✗'}</p>
+    </div>
+  </div>
+</div>
+
+<style>
+  .permissions-demo {
+    margin: 20px;
+    padding: 20px;
+    background: #f8fafc;
+    border-radius: 8px;
+  }
+  
+  .permission-info {
+    margin-top: 16px;
+    padding: 12px;
+    background: white;
+    border-radius: 6px;
+  }
+  
+  .permission-checks {
+    display: grid;
+    grid-template-columns: 1fr 1fr;
+    gap: 8px;
+    margin-top: 8px;
+  }
+</style>
+```
+
+### 不同视觉变体
+
+```svelte
+<script>
+  import GroupCheckBox from "@ticatec/uniface-element/GroupCheckBox";
+  import FormField from "@ticatec/uniface-element/FormField";
+  
+  const colors = [
+    { code: "red", text: "红色" },
+    { code: "blue", text: "蓝色" },
+    { code: "green", text: "绿色" },
+    { code: "yellow", text: "黄色" }
+  ];
+  
+  let selectedColors = "";
+</script>
+
+<div class="variants-demo">
+  <div class="variant-section">
+    <h3>默认变体</h3>
+    <FormField label="选择颜色">
+      <GroupCheckBox options={colors} bind:value={selectedColors} />
+    </FormField>
+  </div>
+  
+  <div class="variant-section">
+    <h3>轮廓变体</h3>
+    <FormField label="选择颜色">
+      <GroupCheckBox 
+        options={colors} 
+        variant="outlined"
+        bind:value={selectedColors} 
+      />
+    </FormField>
+  </div>
+  
+  <div class="variant-section">
+    <h3>填充变体</h3>
+    <FormField label="选择颜色">
+      <GroupCheckBox 
+        options={colors} 
+        variant="filled"
+        bind:value={selectedColors} 
+      />
+    </FormField>
+  </div>
+  
+  <div class="variant-section">
+    <h3>紧凑变体</h3>
+    <FormField label="选择颜色">
+      <GroupCheckBox 
+        options={colors} 
+        compact={true}
+        bind:value={selectedColors} 
+      />
+    </FormField>
+  </div>
+</div>
+
+<style>
+  .variants-demo {
+    display: grid;
+    grid-template-columns: 1fr 1fr;
+    gap: 20px;
+    margin: 20px;
+  }
+  
+  .variant-section {
+    padding: 16px;
+    border: 1px solid #e2e8f0;
+    border-radius: 8px;
+  }
+</style>
+```
+
+### 条件选项和动态行为
+
+```svelte
+<script>
+  import GroupCheckBox from "@ticatec/uniface-element/GroupCheckBox";
+  import FormField from "@ticatec/uniface-element/FormField";
+  
+  const airlines = [
+    { code: "none", text: "无" },
+    { code: "aa", text: "中国国际航空" },
+    { code: "ua", text: "中国东方航空" },
+    { code: "dl", text: "南方航空" },
+    { code: "sw", text: "海南航空" }
+  ];
+  
+  let selectedAirlines = "";
+  let disabledOptions = [];
+  let hideOptions = [];
+  
+  function handleAirlineChange(value) {
+    const selected = value ? value.split(';') : [];
+    
+    // 如果选择了“无”，禁用其他选项
+    if (selected.includes('none')) {
+      if (selected.length > 1) {
+        // 如果“无”与其他选项一起被选中，仅保留“无”
+        selectedAirlines = "none";
+      }
+      disabledOptions = airlines
+        .filter(airline => airline.code !== 'none')
+        .map(airline => airline.code);
+    } else {
+      disabledOptions = [];
+    }
+    
+    // 周末隐藏海南航空（演示逻辑）
+    const today = new Date();
+    if (today.getDay() === 0 || today.getDay() === 6) {
+      hideOptions = ['sw'];
+    } else {
+      hideOptions = [];
+    }
+  }
+  
+  // 处理特殊的“无”选择逻辑
+  function handleSpecialLogic(value) {
+    const selected = value ? value.split(';') : [];
+    
+    if (selected.includes('none') && selected.length > 1) {
+      // 如果选择了其他选项，移除“无”
+      const filteredSelected = selected.filter(option => option !== 'none');
+      selectedAirlines = filteredSelected.join(';');
+    } else {
+      handleAirlineChange(value);
+    }
+  }
+</script>
+
+<div class="conditional-demo">
+  <FormField label="选择偏好的航空公司">
+    <GroupCheckBox 
+      options={airlines}
+      bind:value={selectedAirlines}
+      {disabledOptions}
+      {hideOptions}
+      onchange={handleSpecialLogic}
+    />
+  </FormField>
+  
+  <div class="info-panel">
+    <p><strong>已选择:</strong> {selectedAirlines || '无'}</p>
+    <p><strong>已禁用:</strong> {disabledOptions.join(', ') || '无'}</p>
+    <p><strong>已隐藏:</strong> {hideOptions.join(', ') || '无'}</p>
+    <p class="hint">💡 选择“无”以禁用其他选项</p>
+    {#if hideOptions.includes('sw')}
+      <p class="weekend-notice">🚫 周末不可选择海南航空</p>
+    {/if}
+  </div>
+</div>
+
+<style>
+  .conditional-demo {
+    margin: 20px;
+    padding: 20px;
+    border: 1px solid #e2e8f0;
+    border-radius: 8px;
+  }
+  
+  .info-panel {
+    margin-top: 16px;
+    padding: 12px;
+    background: #f8fafc;
+    border-radius: 6px;
+  }
+  
+  .hint {
+    color: #6b7280;
+    font-style: italic;
+  }
+  
+  .weekend-notice {
+    color: #dc2626;
+    font-weight: 500;
+  }
+</style>
+```
+
+### 只读和显示模式
+
+```svelte
+<script>
+  import GroupCheckBox from "@ticatec/uniface-element/GroupCheckBox";
+  import FormField from "@ticatec/uniface-element/FormField";
+  import { DisplayMode } from "@ticatec/uniface-element";
+  
+  const skills = [
+    { code: "js", text: "JavaScript" },
+    { code: "ts", text: "TypeScript" },
+    { code: "react", text: "React" },
+    { code: "node", text: "Node.js" }
+  ];
+  
+  let userSkills = "js;react;node";  // 预选技能
+</script>
+
+<div class="readonly-demo">
+  <div class="mode-section">
+    <h3>可编辑模式</h3>
+    <FormField label="编辑您的技能">
+      <GroupCheckBox 
+        options={skills}
+        bind:value={userSkills}
+      />
+    </FormField>
+  </div>
+  
+  <div class="mode-section">
+    <h3>只读模式</h3>
+    <FormField label="您的技能（只读）">
+      <GroupCheckBox 
+        options={skills}
+        value={userSkills}
+        readonly={true}
+      />
+    </FormField>
+  </div>
+  
+  <div class="mode-section">
+    <h3>禁用模式</h3>
+    <FormField label="您的技能（禁用）">
+      <GroupCheckBox 
+        options={skills}
+        value={userSkills}
+        disabled={true}
+      />
+    </FormField>
+  </div>
+  
+  <div class="mode-section">
+    <h3>仅显示模式</h3>
+    <FormField label="您的技能（显示）">
+      <GroupCheckBox 
+        options={skills}
+        value={userSkills}
+        displayMode={DisplayMode.View}
+      />
+    </FormField>
+  </div>
+</div>
+
+<style>
+  .readonly-demo {
+    display: grid;
+    grid-template-columns: 1fr 1fr;
+    gap: 20px;
+    margin: 20px;
+  }
+  
+  .mode-section {
+    padding: 16px;
+    border: 1px solid #e2e8f0;
+    border-radius: 8px;
+  }
+</style>
+```
+
+### 自定义样式和字段配置
+
+```svelte
+<script>
+  import GroupCheckBox from "@ticatec/uniface-element/GroupCheckBox";
+  import FormField from "@ticatec/uniface-element/FormField";
+  
+  const departments = [
+    { id: "eng", name: "工程部", active: true },
+    { id: "sales", name: "销售部", active: true },
+    { id: "marketing", name: "市场部", active: false },
+    { id: "hr", name: "人力资源部", active: true }
+  ];
+  
+  let selectedDepartments = "";
+</script>
+
+<div class="custom-demo">
+  <FormField label="选择部门">
+    <GroupCheckBox 
+      options={departments}
+      keyField="id"
+      textField="name"
+      delimiter=","
+      bind:value={selectedDepartments}
+      variant="outlined"
+      style="border: 2px solid #3b82f6; border-radius: 12px; padding: 16px;"
+      item$style="margin: 8px 0; padding: 4px 8px; background: #f0f9ff; border-radius: 6px;"
+    />
+  </FormField>
+  
+  <div class="result">
+    <p><strong>选择的部门:</strong></p>
+    <p>原始值: {selectedDepartments}</p>
+    <p>数组形式: {JSON.stringify(selectedDepartments ? selectedDepartments.split(',') : [])}</p>
+  </div>
+</div>
+
+<style>
+  .custom-demo {
+    margin: 20px;
+    padding: 20px;
+    border: 1px solid #e2e8f0;
+    border-radius: 8px;
+  }
+  
+  .result {
+    margin-top: 16px;
+    padding: 12px;
+    background: #f8fafc;
+    border-radius: 6px;
+  }
+</style>
+```
+
+### 表单集成与验证
+
+```svelte
+<script>
+  import GroupCheckBox from "@ticatec/uniface-element/GroupCheckBox";
+  import FormField from "@ticatec/uniface-element/FormField";
+  
+  const interests = [
+    { code: "sports", text: "运动" },
+    { code: "music", text: "音乐" },
+    { code: "travel", text: "旅行" },
+    { code: "cooking", text: "烹饪" },
+    { code: "reading", text: "阅读" },
+    { code: "gaming", text: "游戏" }
+  ];
+  
+  let formData = {
+    name: '',
+    interests: '',
+    newsletter: false
+  };
+  
+  let errors = {};
+  let groupCheckBoxRef;
+  
+  function validateForm() {
+    errors = {};
+    
+    if (!formData.name.trim()) {
+      errors.name = '姓名是必填项';
+    }
+    
+    if (!formData.interests) {
+      errors.interests = '请至少选择一个兴趣';
+    } else {
+      const selectedCount = formData.interests.split(';').length;
+      if (selectedCount > 3) {
+        errors.interests = '最多选择3个兴趣';
+      }
+    }
+    
+    return Object.keys(errors).length === 0;
+  }
+  
+  function handleSubmit() {
+    if (validateForm()) {
+      console.log('表单提交:', formData);
+      alert('表单提交成功！');
+    } else {
+      console.log('验证错误:', errors);
+      // 聚焦第一个错误字段
+      if (errors.interests) {
+        groupCheckBoxRef.setFocus();
+      }
+    }
+  }
+  
+  function handleInterestChange(value) {
+    formData.interests = value;
+    // 用户选择时清除错误
+    if (errors.interests && value) {
+      delete errors.interests;
+      errors = { ...errors };
+    }
+  }
+</script>
+
+<div class="form-demo">
+  <form on:submit|preventDefault={handleSubmit}>
+    <FormField label="您的姓名" error={errors.name}>
+      <input 
+        type="text" 
+        bind:value={formData.name}
+        class="form-input"
+        class:error={errors.name}
+      />
+    </FormField>
+    
+    <FormField label="您的兴趣（选择1-3项）" error={errors.interests}>
+      <GroupCheckBox 
+        bind:this={groupCheckBoxRef}
+        options={interests}
+        bind:value={formData.interests}
+        onchange={handleInterestChange}
+        variant="outlined"
+      />
+      <p class="field-hint">选择最多3个最能描述您的兴趣</p>
+    </FormField>
+    
+    <FormField label="订阅简讯">
+      <label class="checkbox-label">
+        <input type="checkbox" bind:checked={formData.newsletter} />
+        订阅我们的简讯
+      </label>
+    </FormField>
+    
+    <div class="form-actions">
+      <button type="submit" class="submit-btn">提交</button>
+      <button type="button" on:click={() => console.log(formData)} class="preview-btn">
+        预览数据
+      </button>
+    </div>
+  </form>
+</div>
+
+<style>
+  .form-demo {
+    max-width: 500px;
+    margin: 20px;
+    padding: 24px;
+    border: 1px solid #e2e8f0;
+    border-radius: 8px;
+  }
+  
+  .form-input {
+    width: 100%;
+    padding: 8px 12px;
+    border: 1px solid #d1d5db;
+    border-radius: 6px;
+  }
+  
+  .form-input.error {
+    border-color: #dc2626;
+  }
+  
+  .field-hint {
+    margin-top: 4px;
+    font-size: 0.875rem;
+    color: #6b7280;
+  }
+  
+  .checkbox-label {
+    display: flex;
+    align-items: center;
+    gap: 8px;
+    cursor: pointer;
+  }
+  
+  .form-actions {
+    display: flex;
+    gap: 12px;
+    margin-top: 20px;
+  }
+  
+  .submit-btn, .preview-btn {
+    padding: 10px 20px;
+    border-radius: 6px;
+    border: none;
+    cursor: pointer;
+  }
+  
+  .submit-btn {
+    background: #3b82f6;
+    color: white;
+  }
+  
+  .preview-btn {
+    background: #f3f4f6;
+    color: #374151;
+    border: 1px solid #d1d5db;
+  }
+</style>
+```
+
+## 值格式
+
+### 基于字符串的值
+当 `bitBase` 为 `false`（默认值）时，选中的值存储为带分隔符的字符串：
+- 单一选择：`"option1"`
+- 多项选择：`"option1;option2;option3"`
+- 无选择：`""`
+
+### 基于位的值
+当 `bitBase` 为 `true` 时，选中的值存储为一个数字，每个位表示一个选项：
+- 第一个选项（索引0）：位0（值1）
+- 第二个选项（索引1）：位1（值2）
+- 第三个选项（索引2）：位2（值4）
+- 组合：第一和第三个选项 = 1 + 4 = 5
+
+## 样式
+
+GroupCheckBox 组件可通过 CSS 自定义属性进行样式化：
+
+```css
+.uniface-group-box {
+  --checkbox-spacing: 8px;
+  --checkbox-padding: 4px 8px;
+  --border-color: #e2e8f0;
+  --background-color: #ffffff;
+  --hover-background: #f9fafb;
+}
+
+/* 变体特定样式 */
+.uniface-group-box.outlined {
+  border: 1px solid var(--border-color);
+  border-radius: 6px;
+  padding: 12px;
+}
+
+.uniface-group-box.filled {
+  background-color: #f8fafc;
+  border-radius: 6px;
+  padding: 12px;
+}
+
+.uniface-group-box.compact {
+  --checkbox-spacing: 4px;
+  --checkbox-padding: 2px 4px;
+}
+```
+
+## 可访问性
+
+GroupCheckBox 组件包括以下可访问性功能：
+
+- 复选框之间的键盘导航
+- 使用 `setFocus()` 方法进行焦点管理
+- ARIA 标签和描述
+- 状态变化的屏幕阅读器提示
+- 适当的 Tab 键顺序管理
+
+## 最佳实践
+
+1. **选项管理**：保持选项数组的稳定性以避免不必要的重新渲染
+2. **性能**：对于大型数据集或性能关键场景，使用基于位的值
+3. **验证**：为必选项目实现适当的验证
+4. **用户体验**：为禁用/隐藏选项提供清晰的反馈
+5. **可访问性**：始终提供有意义的标签和描述
+6. **状态管理**：适当地处理焦点/失焦事件以进行表单验证
+