@ticatec/uniface-element 0.2.3 → 0.3.0

package/dist/options-select/README_CN.md

@@ -0,0 +1,632 @@
+# 选项单选组件
+
+一个单选下拉组件，允许用户从预定义列表中选择一个选项，支持自定义样式和行为。
+
+## 功能
+
+- **单选**：从下拉列表中选择一个选项
+- **自定义字段映射**：配置用于键和显示文本的对象属性
+- **选项控制**：隐藏或禁用特定选项
+- **自定义渲染**：使用自定义组件渲染下拉项
+- **必填模式**：防止清除已选值
+- **搜索集成**：与 CommonPicker 配合使用，提供一致的行为
+- **焦点管理**：适当的焦点处理和键盘导航
+- **显示模式**：支持编辑和查看模式
+- **空状态处理**：可自定义的占位符和空文本
+- **事件回调**：支持选择、聚焦和失焦等丰富的事件处理
+
+## 安装
+
+```bash
+npm install @ticatec/uniface-element
+```
+
+## 基本用法
+
+```svelte
+<script>
+  import OptionsSelect from '@ticatec/uniface-element/OptionsSelect';
+  
+  let selectedValue = null;
+  let options = [
+    { code: 'JS', text: 'JavaScript' },
+    { code: 'TS', text: 'TypeScript' },
+    { code: 'PY', text: 'Python' }
+  ];
+</script>
+
+<OptionsSelect 
+  {options} 
+  bind:value={selectedValue}
+/>
+```
+
+## API 参考
+
+### 属性
+
+| 属性 | 类型 | 默认值 | 描述 |
+|------|------|---------|-------------|
+| `value` | `any` | `null` | 选中的选项键/值 |
+| `options` | `Array<any>` | `[]` | 选项对象数组 |
+| `keyField` | `string` | `'code'` | 选项键的属性名 |
+| `textField` | `string` | `'text'` | 选项显示文本的属性名 |
+| `variant` | `'' \| 'plain' \| 'outlined' \| 'filled'` | `''` | 视觉样式变体 |
+| `compact` | `boolean` | `false` | 启用紧凑显示模式 |
+| `disabled` | `boolean` | `false` | 禁用组件 |
+| `readonly` | `boolean` | `false` | 使组件只读 |
+| `mandatory` | `boolean` | `false` | 禁止清除已选值 |
+| `style` | `string` | `''` | 自定义 CSS 样式 |
+| `placeholder` | `string` | `''` | 未选择选项时的占位符文本 |
+| `emptyText` | `string` | `null` | 未选择选项时显示的文本（覆盖占位符） |
+| `disableOptions` | `Array<string>` | `[]` | 要禁用的选项键 |
+| `hideOptions` | `Array<string>` | `[]` | 要隐藏的选项键 |
+| `displayMode` | `DisplayMode` | `DisplayMode.Edit` | 编辑或查看模式 |
+| `menu$height` | `number` | `0` | 下拉菜单的最大高度 |
+| `itemRender` | `any` | `null` | 用于渲染选项的自定义组件 |
+| `onchange` | `OnChangeHandler<any>` | `null` | 更改事件处理程序 |
+| `onfocus` | `(() => void) \| null` | `null` | 聚焦事件处理程序 |
+| `onblur` | `(() => void) \| null` | `null` | 失焦事件处理程序 |
+| `onSelected` | `OnSelectedHandler` | `null` | 选择事件处理程序，包含完整选项数据 |
+
+### 方法
+
+| 方法 | 描述 |
+|--------|-------------|
+| `setFocus()` | 以编程方式聚焦组件 |
+
+## 示例
+
+### 货币选择器
+
+```svelte
+<script>
+  import OptionsSelect from '@ticatec/uniface-element/OptionsSelect';
+  import FormField from '@ticatec/uniface-element/FormField';
+  
+  let selectedCurrency = 'USD';
+  let currencies = [
+    { code: 'USD', text: '美元' },
+    { code: 'EUR', text: '欧元' },
+    { code: 'GBP', text: '英镑' },
+    { code: 'JPY', text: '日元' },
+    { code: 'CNY', text: '人民币' }
+  ];
+  
+  function handleCurrencyChange(currency) {
+    console.log('货币更改为：', currency);
+  }
+</script>
+
+<FormField label="货币">
+  <OptionsSelect 
+    options={currencies}
+    bind:value={selectedCurrency}
+    variant="outlined"
+    placeholder="选择货币"
+    onchange={handleCurrencyChange}
+  />
+</FormField>
+```
+
+### 国家选择器（自定义字段）
+
+```svelte
+<script>
+  import OptionsSelect from '@ticatec/uniface-element/OptionsSelect';
+  
+  let selectedCountry = null;
+  let countries = [
+    { id: 'US', name: '美国' },
+    { id: 'CA', name: '加拿大' },
+    { id: 'UK', name: '英国' },
+    { id: 'DE', name: '德国' },
+    { id: 'JP', name: '日本' }
+  ];
+  
+  function handleCountrySelection(countryItem) {
+    console.log('选择的国家对象：', countryItem);
+  }
+</script>
+
+<OptionsSelect 
+  options={countries}
+  keyField="id"
+  textField="name"
+  bind:value={selectedCountry}
+  variant="filled"
+  placeholder="选择你的国家"
+  onSelected={handleCountrySelection}
+/>
+```
+
+### 状态选择器（带禁用选项）
+
+```svelte
+<script>
+  import OptionsSelect from '@ticatec/uniface-element/OptionsSelect';
+  
+  let taskStatus = 'PENDING';
+  let statusOptions = [
+    { code: 'PENDING', text: '待处理' },
+    { code: 'IN_PROGRESS', text: '进行中' },
+    { code: 'REVIEW', text: '审核中' },
+    { code: 'COMPLETED', text: '已完成' },
+    { code: 'CANCELLED', text: '已取消' },
+    { code: 'ARCHIVED', text: '已归档' }
+  ];
+  
+  let disabledStatuses = ['ARCHIVED']; // 归档状态不可用
+  let hiddenStatuses = ['CANCELLED']; // 隐藏取消选项
+</script>
+
+<div class="status-selector">
+  <label>任务状态</label>
+  <OptionsSelect 
+    options={statusOptions}
+    bind:value={taskStatus}
+    variant="outlined"
+    disableOptions={disabledStatuses}
+    hideOptions={hiddenStatuses}
+    mandatory
+    emptyText="未设置状态"
+  />
+</div>
+```
+
+### 语言偏好
+
+```svelte
+<script>
+  import OptionsSelect from '@ticatec/uniface-element/OptionsSelect';
+  
+  let preferredLanguage = null;
+  let languages = [
+    { locale: 'en', display: '英语' },
+    { locale: 'es', display: '西班牙语' },
+    { locale: 'fr', display: '法语' },
+    { locale: 'de', display: '德语' },
+    { locale: 'zh', display: '中文' },
+    { locale: 'ja', display: '日语' }
+  ];
+  
+  function handleLanguageChange(locale) {
+    console.log('语言更改为：', locale);
+    // 更新应用语言
+    updateAppLanguage(locale);
+  }
+  
+  function handleFocus() {
+    console.log('语言选择器聚焦');
+  }
+  
+  function handleBlur() {
+    console.log('语言选择器失焦');
+  }
+</script>
+
+<div class="language-settings">
+  <OptionsSelect 
+    options={languages}
+    keyField="locale"
+    textField="display"
+    bind:value={preferredLanguage}
+    variant="filled"
+    placeholder="选择你的语言"
+    onchange={handleLanguageChange}
+    onfocus={handleFocus}
+    onblur={handleBlur}
+  />
+</div>
+```
+
+### 优先级选择器（自定义样式）
+
+```svelte
+<script>
+  import OptionsSelect from '@ticatec/uniface-element/OptionsSelect';
+  import PriorityItem from './PriorityItem.svelte'; // 自定义组件
+  
+  let priority = 'MEDIUM';
+  let priorities = [
+    { level: 'LOW', label: '低优先级', color: '#4caf50' },
+    { level: 'MEDIUM', label: '中优先级', color: '#ff9800' },
+    { level: 'HIGH', label: '高优先级', color: '#f44336' },
+    { level: 'URGENT', label: '紧急', color: '#9c27b0' }
+  ];
+  
+  const priorityRenderer = {
+    component: PriorityItem,
+    props: {
+      showIcon: true
+    }
+  };
+</script>
+
+<div class="priority-selector">
+  <label>任务优先级</label>
+  <OptionsSelect 
+    options={priorities}
+    keyField="level"
+    textField="label"
+    bind:value={priority}
+    variant="outlined"
+    itemRender={priorityRenderer}
+    mandatory
+  />
+</div>
+```
+
+### 主题选择器
+
+```svelte
+<script>
+  import OptionsSelect from '@ticatec/uniface-element/OptionsSelect';
+  
+  let currentTheme = 'light';
+  let themes = [
+    { code: 'light', text: '浅色主题' },
+    { code: 'dark', text: '深色主题' },
+    { code: 'auto', text: '系统默认' },
+    { code: 'high-contrast', text: '高对比度' }
+  ];
+  
+  function applyTheme(themeCode) {
+    console.log('应用主题：', themeCode);
+    document.documentElement.setAttribute('data-theme', themeCode);
+  }
+</script>
+
+<div class="theme-settings">
+  <h3>外观</h3>
+  <OptionsSelect 
+    options={themes}
+    bind:value={currentTheme}
+    variant="outlined"
+    mandatory
+    onchange={applyTheme}
+    style="width: 200px;"
+  />
+</div>
+```
+
+### 带多个选择器的表单
+
+```svelte
+<script>
+  import OptionsSelect from '@ticatec/uniface-element/OptionsSelect';
+  import FormField from '@ticatec/uniface-element/FormField';
+  
+  let userProfile = {
+    gender: null,
+    country: null,
+    timezone: null,
+    currency: 'USD'
+  };
+  
+  let genders = [
+    { code: 'M', text: '男性' },
+    { code: 'F', text: '女性' },
+    { code: 'O', text: '其他' },
+    { code: 'N', text: '不愿透露' }
+  ];
+  
+  let countries = [
+    { id: 'US', name: '美国' },
+    { id: 'CA', name: '加拿大' },
+    { id: 'UK', name: '英国' },
+    { id: 'AU', name: '澳大利亚' }
+  ];
+  
+  let timezones = [
+    { code: 'UTC', text: '协调世界时' },
+    { code: 'EST', text: '东部时间' },
+    { code: 'PST', text: '太平洋时间' },
+    { code: 'GMT', text: '格林尼治标准时间' }
+  ];
+  
+  let currencies = [
+    { code: 'USD', text: '美元' },
+    { code: 'EUR', text: '欧元' },
+    { code: 'GBP', text: '英镑' },
+    { code: 'CAD', text: '加拿大元' }
+  ];
+  
+  function saveProfile() {
+    console.log('保存用户信息：', userProfile);
+  }
+</script>
+
+<div class="profile-form">
+  <h3>用户信息</h3>
+  
+  <FormField label="性别">
+    <OptionsSelect 
+      options={genders}
+      bind:value={userProfile.gender}
+      variant="outlined"
+      placeholder="选择性别"
+    />
+  </FormField>
+  
+  <FormField label="国家">
+    <OptionsSelect 
+      options={countries}
+      keyField="id"
+      textField="name"
+      bind:value={userProfile.country}
+      variant="outlined"
+      placeholder="选择国家"
+      mandatory
+    />
+  </FormField>
+  
+  <FormField label="时区">
+    <OptionsSelect 
+      options={timezones}
+      bind:value={userProfile.timezone}
+      variant="outlined"
+      placeholder="选择时区"
+    />
+  </FormField>
+  
+  <FormField label="货币">
+    <OptionsSelect 
+      options={currencies}
+      bind:value={userProfile.currency}
+      variant="outlined"
+      mandatory
+    />
+  </FormField>
+  
+  <button on:click={saveProfile}>保存用户信息</button>
+</div>
+```
+
+### 紧凑表格用法
+
+```svelte
+<script>
+  import OptionsSelect from '@ticatec/uniface-element/OptionsSelect';
+  
+  let statusOptions = [
+    { code: 'ACTIVE', text: '活跃' },
+    { code: 'INACTIVE', text: '非活跃' },
+    { code: 'PENDING', text: '待处理' }
+  ];
+  
+  let users = [
+    { id: 1, name: 'John Doe', status: 'ACTIVE' },
+    { id: 2, name: 'Jane Smith', status: 'INACTIVE' },
+    { id: 3, name: 'Bob Wilson', status: 'PENDING' }
+  ];
+  
+  function updateUserStatus(userId, newStatus) {
+    const user = users.find(u => u.id === userId);
+    if (user) {
+      user.status = newStatus;
+      users = [...users];
+      console.log(`用户 ${user.name} 的状态更新为 ${newStatus}`);
+    }
+  }
+</script>
+
+<table class="user-table">
+  <thead>
+    <tr>
+      <th>姓名</th>
+      <th>状态</th>
+    </tr>
+  </thead>
+  <tbody>
+    {#each users as user}
+      <tr>
+        <td>{user.name}</td>
+        <td>
+          <OptionsSelect 
+            options={statusOptions}
+            value={user.status}
+            compact
+            variant="outlined"
+            onchange={(status) => updateUserStatus(user.id, status)}
+          />
+        </td>
+      </tr>
+    {/each}
+  </tbody>
+</table>
+```
+
+### 动态选项加载
+
+```svelte
+<script>
+  import OptionsSelect from '@ticatec/uniface-element/OptionsSelect';
+  
+  let selectedCategory = null;
+  let selectedProduct = null;
+  let categories = [
+    { id: 'electronics', name: '电子产品' },
+    { id: 'clothing', name: '服装' },
+    { id: 'books', name: '书籍' }
+  ];
+  let products = [];
+  
+  async function loadProducts(categoryId) {
+    if (!categoryId) {
+      products = [];
+      selectedProduct = null;
+      return;
+    }
+    
+    // 模拟 API 调用
+    const productData = {
+      'electronics': [
+        { sku: 'E001', name: '笔记本电脑' },
+        { sku: 'E002', name: '智能手机' }
+      ],
+      'clothing': [
+        { sku: 'C001', name: 'T恤' },
+        { sku: 'C002', name: '牛仔裤' }
+      ],
+      'books': [
+        { sku: 'B001', name: '编程指南' },
+        { sku: 'B002', name: '设计模式' }
+      ]
+    };
+    
+    products = productData[categoryId] || [];
+    selectedProduct = null;
+  }
+  
+  $: loadProducts(selectedCategory);
+</script>
+
+<div class="product-selector">
+  <div class="selector-row">
+    <label>类别</label>
+    <OptionsSelect 
+      options={categories}
+      keyField="id"
+      textField="name"
+      bind:value={selectedCategory}
+      variant="outlined"
+      placeholder="选择类别"
+    />
+  </div>
+  
+  <div class="selector-row">
+    <label>产品</label>
+    <OptionsSelect 
+      options={products}
+      keyField="sku"
+      textField="name"
+      bind:value={selectedProduct}
+      variant="outlined"
+      placeholder={selectedCategory ? '选择产品' : '请先选择类别'}
+      disabled={!selectedCategory}
+    />
+  </div>
+</div>
+```
+
+## 自定义选项渲染
+
+你可以提供一个自定义组件来渲染下拉选项：
+
+```svelte
+<!-- CustomItemRenderer.svelte -->
+<script>
+  export let item;
+  export let disabled = false;
+  
+  import { createEventDispatcher } from 'svelte';
+  const dispatch = createEventDispatcher();
+  
+  function handleClick() {
+    if (!disabled) {
+      dispatch('click');
+    }
+  }
+</script>
+
+<div class="custom-item" class:disabled on:click={handleClick}>
+  <div class="item-icon">📌</div>
+  <div class="item-content">
+    <div class="item-title">{item.title}</div>
+    <div class="item-description">{item.description}</div>
+  </div>
+</div>
+
+<style>
+  .custom-item {
+    display: flex;
+    align-items: center;
+    padding: 12px;
+    cursor: pointer;
+    border-bottom: 1px solid #eee;
+  }
+  
+  .custom-item:hover:not(.disabled) {
+    background-color: #f5f5f5;
+  }
+  
+  .custom-item.disabled {
+    opacity: 0.5;
+    cursor: not-allowed;
+  }
+  
+  .item-icon {
+    margin-right: 12px;
+    font-size: 18px;
+  }
+  
+  .item-title {
+    font-weight: 600;
+    margin-bottom: 4px;
+  }
+  
+  .item-description {
+    font-size: 12px;
+    color: #666;
+  }
+</style>
+```
+
+## 最佳实践
+
+1. **选项管理**：保持选项列表专注且相关
+2. **性能**：对于超大选项列表，考虑虚拟化
+3. **可访问性**：提供清晰的标签和有意义的选项文本
+4. **用户体验**：选择适合你设计的变体和尺寸
+5. **数据验证**：处理选项缺失等边缘情况
+6. **加载状态**：为动态选项显示加载指示器
+7. **错误处理**：优雅处理动态选项的 API 失败
+
+## 样式
+
+```css
+.options-popover {
+  max-height: 300px;
+  overflow-y: auto;
+  border: 1px solid #e0e0e0;
+  border-radius: 4px;
+  background: white;
+  box-shadow: 0 2px 8px rgba(0, 0, 0, 0.1);
+}
+
+.option-item {
+  padding: 8px 12px;
+  cursor: pointer;
+  border-bottom: 1px solid #f0f0f0;
+}
+
+.option-item:hover:not(.disabled) {
+  background-color: #f5f5f5;
+}
+
+.option-item.disabled {
+  opacity: 0.5;
+  cursor: not-allowed;
+  background-color: #fafafa;
+}
+
+.option-item:last-child {
+  border-bottom: none;
+}
+```
+
+## 可访问性
+
+- 全面支持键盘导航（箭头键、回车、Esc键）
+- 为屏幕阅读器提供 ARIA 标签和角色
+- 焦点管理和视觉指示器
+- 高对比度模式兼容性
+- 适当的表单关联标签
+
+## 相关组件
+
+- [选项多选](../options-multi-select/README.md) - 用于多选选项
+- [表单字段](../form-field/README.md) - 用于表单布局和标签
+- [通用选择器](../common/README.md) - 基础选择器功能
+- [查找编辑器](../lookup-editor/README.md) - 用于动态数据查找