@ticatec/uniface-element 0.2.0 → 0.2.2

package/docs/form-components/cn/prompts-text-editor.md

@@ -0,0 +1,241 @@
+# PromptsTextEditor 组件
+
+带自动完成提示的文本输入组件。
+
+## 属性
+
+| 属性 | 类型 | 默认值 | 描述 |
+|------|------|--------|------|
+| `variant` | `'' \| 'plain' \| 'outlined' \| 'filled'` | `''` | 外观变体 |
+| `disabled` | `boolean` | `false` | 是否禁用 |
+| `readonly` | `boolean` | `false` | 是否只读 |
+| `compact` | `boolean` | `false` | 是否紧凑模式 |
+| `value` | `string` | `''` | 输入值 |
+| `placeholder` | `string` | `''` | 占位符文本 |
+| `displayMode` | `DisplayMode` | `DisplayMode.Edit` | 显示模式 |
+| `prompts` | `Array<string>` | `[]` | 提示选项数组 |
+| `maxPrompts` | `number` | `10` | 最大显示提示数量 |
+| `minChars` | `number` | `1` | 触发提示的最小字符数 |
+| `caseSensitive` | `boolean` | `false` | 是否区分大小写 |
+| `style` | `string` | `''` | 自定义样式 |
+| `onChange` | `OnChangeHandler<string>` | - | 值变化回调 |
+
+## 使用示例
+
+```svelte
+<script lang="ts">
+  import PromptsTextEditor from '@ticatec/uniface-element/PromptsTextEditor';
+  
+  // 邮箱域名提示
+  const emailDomains: string[] = [
+    'gmail.com',
+    'qq.com',
+    '163.com',
+    '126.com',
+    'hotmail.com',
+    'yahoo.com',
+    'outlook.com',
+    'sina.com'
+  ];
+  
+  // 城市名称提示
+  const cities: string[] = [
+    '北京市',
+    '上海市',
+    '广州市',
+    '深圳市',
+    '杭州市',
+    '南京市',
+    '成都市',
+    '武汉市',
+    '西安市',
+    '重庆市'
+  ];
+  
+  let email: string = '';
+  let city: string = '';
+  
+  const handleEmailChange = (value: string): void => {
+    email = value;
+    console.log('邮箱：', value);
+  };
+  
+  const handleCityChange = (value: string): void => {
+    city = value;
+    console.log('城市：', value);
+  };
+</script>
+
+<!-- 邮箱输入（域名提示） -->
+<PromptsTextEditor 
+  placeholder="请输入邮箱地址"
+  prompts={emailDomains}
+  bind:value={email}
+  onChange={handleEmailChange}
+/>
+
+<!-- 城市输入（自动完成） -->
+<PromptsTextEditor 
+  placeholder="请输入城市名称"
+  prompts={cities}
+  minChars={1}
+  maxPrompts={5}
+  bind:value={city}
+  onChange={handleCityChange}
+/>
+```
+
+## 高级用法
+
+### 动态提示
+```svelte
+<script lang="ts">
+  import { onMount } from 'svelte';
+  
+  let searchValue: string = '';
+  let dynamicPrompts: string[] = [];
+  let isLoading: boolean = false;
+  
+  // 从API获取提示
+  const fetchPrompts = async (query: string): Promise<string[]> => {
+    if (query.length < 2) return [];
+    
+    isLoading = true;
+    try {
+      const response = await fetch(`/api/suggestions?q=${encodeURIComponent(query)}`);
+      const data = await response.json();
+      return data.suggestions || [];
+    } catch (error) {
+      console.error('获取提示失败：', error);
+      return [];
+    } finally {
+      isLoading = false;
+    }
+  };
+  
+  // 防抖更新提示
+  let debounceTimeout: number;
+  const updatePrompts = (value: string): void => {
+    clearTimeout(debounceTimeout);
+    debounceTimeout = setTimeout(async () => {
+      dynamicPrompts = await fetchPrompts(value);
+    }, 300);
+  };
+  
+  const handleSearchChange = (value: string): void => {
+    searchValue = value;
+    updatePrompts(value);
+  };
+</script>
+
+<PromptsTextEditor 
+  placeholder="搜索产品..."
+  prompts={dynamicPrompts}
+  minChars={2}
+  maxPrompts={8}
+  bind:value={searchValue}
+  onChange={handleSearchChange}
+/>
+
+{#if isLoading}
+  <div class="loading-hint">正在获取建议...</div>
+{/if}
+```
+
+### 标签输入
+```svelte
+<script lang="ts">
+  const availableTags: string[] = [
+    'JavaScript',
+    'TypeScript',
+    'Svelte',
+    'Vue.js',
+    'React',
+    'Node.js',
+    'Python',
+    'Java',
+    'Go',
+    'Rust'
+  ];
+  
+  let tagInput: string = '';
+  let selectedTags: string[] = [];
+  
+  const handleTagInput = (value: string): void => {
+    tagInput = value;
+    
+    // 检查是否输入了分隔符
+    if (value.includes(',') || value.includes(';')) {
+      const newTags = value.split(/[,;]/).map(tag => tag.trim()).filter(Boolean);
+      
+      newTags.forEach(tag => {
+        if (tag && !selectedTags.includes(tag)) {
+          selectedTags = [...selectedTags, tag];
+        }
+      });
+      
+      tagInput = ''; // 清空输入
+    }
+  };
+  
+  const removeTag = (tagToRemove: string): void => {
+    selectedTags = selectedTags.filter(tag => tag !== tagToRemove);
+  };
+  
+  // 过滤已选择的标签
+  $: filteredPrompts = availableTags.filter(tag => 
+    !selectedTags.includes(tag) && 
+    tag.toLowerCase().includes(tagInput.toLowerCase())
+  );
+</script>
+
+<div class="tag-input-container">
+  <!-- 已选择的标签 -->
+  <div class="selected-tags">
+    {#each selectedTags as tag}
+      <span class="tag">
+        {tag}
+        <button type="button" on:click={() => removeTag(tag)}>×</button>
+      </span>
+    {/each}
+  </div>
+  
+  <!-- 标签输入 -->
+  <PromptsTextEditor 
+    placeholder="输入标签名称..."
+    prompts={filteredPrompts}
+    bind:value={tagInput}
+    onChange={handleTagInput}
+    minChars={1}
+    maxPrompts={6}
+  />
+  
+  <div class="tag-hint">使用逗号或分号分隔多个标签</div>
+</div>
+```
+
+## 最佳实践
+
+### 1. 合理设置触发条件
+```svelte
+<!-- 短词汇：1个字符触发 -->
+<PromptsTextEditor minChars={1} prompts={shortWords} />
+
+<!-- 长词汇或搜索：2-3个字符触发 -->
+<PromptsTextEditor minChars={2} prompts={searchTerms} />
+```
+
+### 2. 限制提示数量
+```svelte
+<!-- 避免显示过多提示 -->
+<PromptsTextEditor maxPrompts={6} prompts={largeDataset} />
+```
+
+### 3. 区分大小写处理
+```svelte
+<!-- 代码或技术术语：区分大小写 -->
+<PromptsTextEditor caseSensitive={true} prompts={codeSnippets} />
+
+<!-- 一般文本：不区分大小写 -->
+<PromptsTextEditor caseSensitive={false} prompts={commonWords} />
+```

package/docs/form-components/cn/radiobutton.md

@@ -0,0 +1,84 @@
+# RadioButton 组件
+
+单选按钮组件，用于在多个选项中选择一个。
+
+## 属性
+
+| 属性 | 类型 | 默认值 | 描述 |
+|------|------|--------|------|
+| `variant` | `'' \| 'plain' \| 'outlined' \| 'filled'` | `''` | 外观变体 |
+| `disabled` | `boolean` | `false` | 是否禁用 |
+| `readonly` | `boolean` | `false` | 是否只读 |
+| `value` | `any` | `null` | 选中的值 |
+| `groupValue` | `any` | `null` | 单选组的当前值 |
+| `label` | `string` | `''` | 标签文本 |
+| `displayMode` | `DisplayMode` | `DisplayMode.Edit` | 显示模式 |
+| `style` | `string` | `''` | 自定义样式 |
+| `onChange` | `OnChangeHandler<any>` | - | 值变化回调 |
+
+## 使用示例
+
+```svelte
+<script lang="ts">
+  import RadioButton from '@ticatec/uniface-element/RadioButton';
+  
+  let selectedPayment: string = 'credit';
+  let selectedSize: string = 'M';
+  
+  const handlePaymentChange = (value: string): void => {
+    selectedPayment = value;
+    console.log('支付方式：', value);
+  };
+  
+  const handleSizeChange = (value: string): void => {
+    selectedSize = value;
+    console.log('尺寸：', value);
+  };
+</script>
+
+<!-- 支付方式选择 -->
+<div>
+  <h4>请选择支付方式：</h4>
+  <RadioButton 
+    label="信用卡支付"
+    value="credit"
+    groupValue={selectedPayment}
+    onChange={handlePaymentChange}
+  />
+  <RadioButton 
+    label="支付宝"
+    value="alipay"
+    groupValue={selectedPayment}
+    onChange={handlePaymentChange}
+  />
+  <RadioButton 
+    label="微信支付"
+    value="wechat"
+    groupValue={selectedPayment}
+    onChange={handlePaymentChange}
+  />
+</div>
+
+<!-- 尺寸选择 -->
+<div>
+  <h4>请选择尺寸：</h4>
+  <RadioButton 
+    label="小号 (S)"
+    value="S"
+    groupValue={selectedSize}
+    onChange={handleSizeChange}
+  />
+  <RadioButton 
+    label="中号 (M)"
+    value="M"
+    groupValue={selectedSize}
+    onChange={handleSizeChange}
+  />
+  <RadioButton 
+    label="大号 (L)"
+    value="L"
+    groupValue={selectedSize}
+    onChange={handleSizeChange}
+  />
+</div>
+```

package/docs/form-components/cn/switch.md

@@ -0,0 +1,178 @@
+# Switch 组件
+
+开关组件，提供布尔值的可视化切换。
+
+## 属性
+
+| 属性 | 类型 | 默认值 | 描述 |
+|------|------|--------|------|
+| `variant` | `'' \| 'plain' \| 'outlined' \| 'filled'` | `''` | 外观变体 |
+| `disabled` | `boolean` | `false` | 是否禁用 |
+| `readonly` | `boolean` | `false` | 是否只读 |
+| `value` | `boolean` | `false` | 开关状态 |
+| `label` | `string` | `''` | 标签文本 |
+| `size` | `'small' \| 'medium' \| 'large'` | `'medium'` | 开关大小 |
+| `displayMode` | `DisplayMode` | `DisplayMode.Edit` | 显示模式 |
+| `style` | `string` | `''` | 自定义样式 |
+| `onChange` | `OnChangeHandler<boolean>` | - | 值变化回调 |
+
+## 使用示例
+
+```svelte
+<script lang="ts">
+  import Switch from '@ticatec/uniface-element/Switch';
+  
+  let darkMode: boolean = false;
+  let notifications: boolean = true;
+  let autoSave: boolean = false;
+  
+  const handleDarkModeChange = (enabled: boolean): void => {
+    darkMode = enabled;
+    // 应用深色主题逻辑
+    document.body.classList.toggle('dark-theme', enabled);
+  };
+  
+  const handleNotificationChange = (enabled: boolean): void => {
+    notifications = enabled;
+    console.log('通知设置：', enabled);
+  };
+  
+  const handleAutoSaveChange = (enabled: boolean): void => {
+    autoSave = enabled;
+    console.log('自动保存：', enabled);
+  };
+</script>
+
+<!-- 深色模式开关 -->
+<Switch 
+  label="深色模式"
+  bind:value={darkMode}
+  onChange={handleDarkModeChange}
+/>
+
+<!-- 通知开关（大尺寸） -->
+<Switch 
+  label="推送通知"
+  size="large"
+  bind:value={notifications}
+  onChange={handleNotificationChange}
+/>
+
+<!-- 自动保存开关（小尺寸） -->
+<Switch 
+  label="自动保存"
+  size="small"
+  bind:value={autoSave}
+  onChange={handleAutoSaveChange}
+/>
+```
+
+## 高级用法
+
+### 设置面板
+```svelte
+<script lang="ts">
+  interface AppSettings {
+    darkMode: boolean;
+    notifications: boolean;
+    autoSave: boolean;
+    showPreview: boolean;
+    enableShortcuts: boolean;
+  }
+  
+  let settings: AppSettings = {
+    darkMode: false,
+    notifications: true,
+    autoSave: true,
+    showPreview: true,
+    enableShortcuts: true
+  };
+  
+  const updateSetting = (key: keyof AppSettings) => (value: boolean): void => {
+    settings = { ...settings, [key]: value };
+    localStorage.setItem('app-settings', JSON.stringify(settings));
+  };
+  
+  // 页面加载时恢复设置
+  onMount(() => {
+    const savedSettings = localStorage.getItem('app-settings');
+    if (savedSettings) {
+      settings = { ...settings, ...JSON.parse(savedSettings) };
+    }
+  });
+</script>
+
+<div class="settings-panel">
+  <h3>应用设置</h3>
+  
+  <div class="setting-group">
+    <Switch 
+      label="深色模式"
+      bind:value={settings.darkMode}
+      onChange={updateSetting('darkMode')}
+    />
+    <p class="setting-description">启用深色主题以减少眼部疲劳</p>
+  </div>
+  
+  <div class="setting-group">
+    <Switch 
+      label="桌面通知"
+      bind:value={settings.notifications}
+      onChange={updateSetting('notifications')}
+    />
+    <p class="setting-description">允许显示桌面通知</p>
+  </div>
+  
+  <div class="setting-group">
+    <Switch 
+      label="自动保存"
+      size="small"
+      bind:value={settings.autoSave}
+      onChange={updateSetting('autoSave')}
+    />
+    <p class="setting-description">自动保存您的工作</p>
+  </div>
+</div>
+```
+
+## 最佳实践
+
+### 1. 提供即时反馈
+```svelte
+<script lang="ts">
+  let isOnline: boolean = true;
+  
+  const toggleOnlineStatus = (status: boolean): void => {
+    isOnline = status;
+    
+    // 显示状态变化提示
+    const message = status ? '已上线' : '已离线';
+    showToast(message);
+  };
+</script>
+
+<Switch 
+  label={`状态: ${isOnline ? '在线' : '离线'}`}
+  bind:value={isOnline}
+  onChange={toggleOnlineStatus}
+/>
+```
+
+### 2. 条件禁用
+```svelte
+<script lang="ts">
+  let isPremiumUser: boolean = false;
+  let advancedFeatures: boolean = false;
+  
+  $: canUseAdvancedFeatures = isPremiumUser;
+</script>
+
+<Switch 
+  label="高级功能"
+  disabled={!canUseAdvancedFeatures}
+  bind:value={advancedFeatures}
+/>
+{#if !canUseAdvancedFeatures}
+  <p class="upgrade-hint">升级到高级版以使用此功能</p>
+{/if}
+```

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

@@ -0,0 +1,142 @@
+# TextEditor 组件
+
+基础文本输入组件，支持单行和多行文本输入。
+
+## 属性
+
+| 属性 | 类型 | 默认值 | 描述 |
+|------|------|--------|------|
+| `variant` | `'' \| 'plain' \| 'outlined' \| 'filled'` | `''` | 外观变体 |
+| `disabled` | `boolean` | `false` | 是否禁用 |
+| `readonly` | `boolean` | `false` | 是否只读 |
+| `compact` | `boolean` | `false` | 是否紧凑模式 |
+| `value` | `string` | `''` | 输入值 |
+| `suffix` | `string` | `''` | 文本后缀 |
+| `prefix` | `string` | `''` | 文本前缀 |
+| `removable` | `boolean` | `true` | 显示清除按钮 |
+| `displayMode` | `DisplayMode` | `DisplayMode.Edit` | 显示模式 |
+| `style` | `string` | `''` | 自定义样式 |
+| `onChange` | `(value: string) => void` | - | 值变化回调 |
+
+## 事件
+
+- `onChange(value: string)` - 当输入值发生变化时触发
+
+## 使用示例
+
+```svelte
+<script lang="ts">
+  import TextEditor from '@ticatec/uniface-element/TextEditor';
+  
+  let inputValue = '';
+  
+  const handleChange = (value: string) => {
+    console.log('输入值：', value);
+    inputValue = value;
+  };
+</script>
+
+<!-- 基础输入 -->
+<TextEditor 
+  placeholder="请输入文本"
+  onChange={handleChange}
+  bind:value={inputValue}
+/>
+
+<!-- 带前缀和后缀的输入 -->
+<TextEditor 
+  prefix="¥"
+  suffix=".00"
+  placeholder="请输入金额"
+  onChange={handleChange}
+  bind:value={inputValue}
+/>
+
+<!-- 紧凑模式带清除按钮 -->
+<TextEditor 
+  compact={true}
+  removable={true}
+  placeholder="搜索..."
+  bind:value={inputValue}
+/>
+```
+
+## 最佳实践
+
+### 表单验证
+```svelte
+<script lang="ts">
+  let value = '';
+  let error = '';
+  
+  const validate = (inputValue) => {
+    if (!inputValue || inputValue.trim().length === 0) {
+      error = '此字段不能为空';
+    } else if (inputValue.length < 3) {
+      error = '至少需要3个字符';
+    } else {
+      error = '';
+    }
+  };
+  
+  const handleChange = (newValue) => {
+    value = newValue;
+    validate(newValue);
+  };
+</script>
+
+<TextEditor 
+  placeholder="请输入内容"
+  bind:value={value}
+  onChange={handleChange}
+/>
+{#if error}
+  <div class="error-message">{error}</div>
+{/if}
+```
+
+### 带样式的文本输入
+```svelte
+<script lang="ts">
+  let description = '';
+</script>
+
+<TextEditor 
+  variant="outlined"
+  placeholder="请输入描述信息..."
+  bind:value={description}
+  style="min-width: 300px;"
+/>
+<div class="char-count">{description.length} 个字符</div>
+```
+
+## 样式定制
+
+```css
+/* 自定义样式 */
+.custom-text-editor {
+  border-radius: 8px;
+  border: 2px solid #e1e5e9;
+  font-family: 'Inter', sans-serif;
+}
+
+.custom-text-editor:focus {
+  border-color: #007bff;
+  box-shadow: 0 0 0 3px rgba(0, 123, 255, 0.1);
+}
+```
+
+## 无障碍访问
+
+```svelte
+<label for="user-name">用户名称：</label>
+<TextEditor 
+  id="user-name"
+  placeholder="请输入用户名称"
+  aria-describedby="name-help"
+  bind:value={userName}
+/>
+<div id="name-help" class="form-help">
+  用户名称将用于系统显示，建议使用真实姓名
+</div>
+```