@ticatec/uniface-element 0.2.0 → 0.2.2

package/docs/form-components/cn/input-options-select.md

@@ -0,0 +1,250 @@
+# InputOptionsSelect 组件
+
+带输入和异步搜索功能的选择组件。
+
+## 类型定义
+
+```typescript
+interface LoaderResult<T = any> {
+  list: T[];
+  hasMore: boolean;
+}
+
+type LazyLoader<T = any> = (keyword: string, pageNo: number) => Promise<LoaderResult<T>>;
+```
+
+## 属性
+
+| 属性 | 类型 | 默认值 | 描述 |
+|------|------|--------|------|
+| `variant` | `'' \| 'plain' \| 'outlined' \| 'filled'` | `''` | 外观变体 |
+| `disabled` | `boolean` | `false` | 是否禁用 |
+| `readonly` | `boolean` | `false` | 是否只读 |
+| `compact` | `boolean` | `false` | 是否紧凑模式 |
+| `text` | `string` | `''` | 显示文本 |
+| `value` | `T | null` | `null` | 选中的值 |
+| `keyField` | `string` | `'code'` | 值字段名 |
+| `textField` | `string` | `'text'` | 显示字段名 |
+| `menu$height` | `number` | `0` | 下拉菜单高度 |
+| `placeholder` | `string` | `''` | 占位符文本 |
+| `displayMode` | `DisplayMode` | `DisplayMode.Edit` | 显示模式 |
+| `itemRender` | `ComponentType` | `null` | 自定义选项渲染组件 |
+| `lazyLoader` | `LazyLoader<T>` | - | 异步数据加载器 |
+| `style` | `string` | `''` | 自定义样式 |
+| `onChange` | `OnChangeHandler<T | null>` | - | 值变化回调 |
+
+## 使用示例
+
+```svelte
+<script lang="ts">
+  import InputOptionsSelect, { type LazyLoader } from '@ticatec/uniface-element/InputOptionsSelect';
+  
+  interface User {
+    id: string;
+    name: string;
+    email: string;
+    department: string;
+  }
+  
+  interface Product {
+    code: string;
+    text: string;
+    category: string;
+    price: number;
+  }
+  
+  let selectedUser: User | null = null;
+  let selectedProduct: Product | null = null;
+  
+  // 用户搜索
+  const searchUsers: LazyLoader<User> = async (keyword: string, pageNo: number): Promise<LoaderResult<User>> => {
+    const response: Response = await fetch(`/api/users/search?q=${encodeURIComponent(keyword)}&page=${pageNo}`);
+    const data = await response.json();
+    return {
+      list: data.users,
+      hasMore: data.hasMore
+    };
+  };
+  
+  // 产品搜索
+  const searchProducts: LazyLoader<Product> = async (keyword: string, pageNo: number): Promise<LoaderResult<Product>> => {
+    // 模拟API延迟
+    await new Promise<void>(resolve => setTimeout(resolve, 300));
+    
+    const mockProducts: Product[] = [
+      { code: 'P001', text: 'iPhone 15 Pro', category: '手机', price: 7999 },
+      { code: 'P002', text: 'MacBook Air M2', category: '笔记本', price: 8999 },
+      { code: 'P003', text: 'iPad Pro 12.9', category: '平板', price: 6999 }
+    ].filter((p: Product): boolean => p.text.toLowerCase().includes(keyword.toLowerCase()));
+    
+    return {
+      list: mockProducts,
+      hasMore: false
+    };
+  };
+  
+  const handleUserChange = (user: User): void => {
+    selectedUser = user;
+    console.log('选择的用户：', user);
+  };
+  
+  const handleProductChange = (product: Product): void => {
+    selectedProduct = product;
+    console.log('选择的产品：', product);
+  };
+</script>
+
+<!-- 用户搜索选择 -->
+<InputOptionsSelect 
+  placeholder="请输入用户名搜索"
+  lazyLoader={searchUsers}
+  keyField="id"
+  textField="name"
+  onChange={handleUserChange}
+/>
+
+<!-- 产品搜索选择 -->
+<InputOptionsSelect 
+  placeholder="请输入产品名称搜索"
+  lazyLoader={searchProducts}
+  keyField="code"
+  textField="text"
+  onChange={handleProductChange}
+/>
+```
+
+## 高级用法
+
+### 自定义选项渲染
+```svelte
+<script lang="ts">
+  import type { ComponentType } from 'svelte';
+  import UserItemRenderer from './UserItemRenderer.svelte';
+  
+  const searchUsersWithDetails: LazyLoader<User> = async (keyword: string, pageNo: number): Promise<LoaderResult<User>> => {
+    const response: Response = await fetch(`/api/users/search-detailed?q=${keyword}&page=${pageNo}`);
+    return await response.json();
+  };
+</script>
+
+<InputOptionsSelect 
+  placeholder="搜索用户"
+  lazyLoader={searchUsersWithDetails}
+  keyField="id"
+  textField="name"
+  itemRender={UserItemRenderer}
+  onChange={handleUserChange}
+/>
+
+<!-- UserItemRenderer.svelte -->
+<script lang="ts">
+  interface User {
+    id: string;
+    name: string;
+    email: string;
+    department: string;
+    avatar: string;
+  }
+  
+  export let item: User;
+</script>
+
+<div class="user-item">
+  <div class="user-avatar">
+    <img src={item.avatar} alt={item.name} />
+  </div>
+  <div class="user-info">
+    <div class="user-name">{item.name}</div>
+    <div class="user-email">{item.email}</div>
+    <div class="user-department">{item.department}</div>
+  </div>
+</div>
+```
+
+### 带缓存的搜索
+```svelte
+<script lang="ts">
+  interface SearchCache {
+    [key: string]: {
+      data: any[];
+      timestamp: number;
+    };
+  }
+  
+  let searchCache: SearchCache = {};
+  const cacheTimeout: number = 5 * 60 * 1000; // 5分钟缓存
+  
+  const cachedSearchLoader: LazyLoader = async (keyword: string, pageNo: number): Promise<LoaderResult> => {
+    const cacheKey: string = `${keyword}-${pageNo}`;
+    const cached = searchCache[cacheKey];
+    
+    // 检查缓存
+    if (cached && Date.now() - cached.timestamp < cacheTimeout) {
+      console.log('使用缓存数据');
+      return {
+        list: cached.data,
+        hasMore: false
+      };
+    }
+    
+    // 从API获取数据
+    const response: Response = await fetch(`/api/search?q=${keyword}&page=${pageNo}`);
+    const result: LoaderResult = await response.json();
+    
+    // 缓存结果
+    searchCache[cacheKey] = {
+      data: result.list,
+      timestamp: Date.now()
+    };
+    
+    return result;
+  };
+</script>
+```
+
+## 最佳实践
+
+### 1. 防抖搜索
+组件内部已经实现了防抖机制，默认延迟500ms后执行搜索。
+
+### 2. 错误处理
+```svelte
+<script lang="ts">
+  const robustSearchLoader: LazyLoader = async (keyword: string, pageNo: number): Promise<LoaderResult> => {
+    try {
+      const response: Response = await fetch(`/api/search?q=${keyword}&page=${pageNo}`);
+      
+      if (!response.ok) {
+        throw new Error(`搜索失败: ${response.status}`);
+      }
+      
+      return await response.json();
+    } catch (error: unknown) {
+      console.error('搜索出错：', error);
+      return {
+        list: [],
+        hasMore: false
+      };
+    }
+  };
+</script>
+```
+
+### 3. 分页加载
+```svelte
+<script lang="ts">
+  const paginatedLoader: LazyLoader = async (keyword: string, pageNo: number): Promise<LoaderResult> => {
+    const pageSize: number = 20;
+    const response: Response = await fetch(
+      `/api/search?q=${keyword}&page=${pageNo}&size=${pageSize}`
+    );
+    
+    const data = await response.json();
+    
+    return {
+      list: data.items,
+      hasMore: data.total > pageNo * pageSize
+    };
+  };
+</script>
+```

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

@@ -0,0 +1,406 @@
+# LookupEditor 组件
+
+查找编辑器组件，通过模态对话框进行复杂的查找和选择操作。
+
+## 类型定义
+
+```typescript
+type OnActionHandler = () => void;
+```
+
+## 属性
+
+| 属性 | 类型 | 默认值 | 描述 |
+|------|------|--------|------|
+| `variant` | `'' \| 'plain' \| 'outlined' \| 'filled'` | `''` | 外观变体 |
+| `disabled` | `boolean` | `false` | 是否禁用 |
+| `readonly` | `boolean` | `false` | 是否只读 |
+| `compact` | `boolean` | `false` | 是否紧凑模式 |
+| `mandatory` | `boolean` | `false` | 是否必填 |
+| `value` | `T | null` | `null` | 选中的值 |
+| `text` | `string` | `''` | 显示文本 |
+| `placeholder` | `string` | `''` | 占位符文本 |
+| `displayMode` | `DisplayMode` | `DisplayMode.Edit` | 显示模式 |
+| `style` | `string` | `''` | 自定义样式 |
+| `onChange` | `OnChangeHandler<T | null>` | - | 值变化回调 |
+| `onAction` | `OnActionHandler` | - | 查找动作回调 |
+
+## 使用示例
+
+```svelte
+<script lang="ts">
+  import LookupEditor from '@ticatec/uniface-element/LookupEditor';
+  import CustomerLookupModal from './CustomerLookupModal.svelte';
+  import ProductLookupModal from './ProductLookupModal.svelte';
+  
+  interface Customer {
+    id: string;
+    name: string;
+    code: string;
+    email: string;
+  }
+  
+  interface Product {
+    id: string;
+    name: string;
+    price: number;
+    category: string;
+  }
+  
+  let selectedCustomer: string | null = null;
+  let customerText: string = '';
+  let selectedProduct: string | null = null;
+  let productText: string = '';
+  let showCustomerModal: boolean = false;
+  let showProductModal: boolean = false;
+  
+  // 客户查找
+  const handleCustomerLookup = (): void => {
+    showCustomerModal = true;
+  };
+  
+  const handleCustomerSelect = (customer: Customer): void => {
+    selectedCustomer = customer.id;
+    customerText = `${customer.name} (${customer.code})`;
+    showCustomerModal = false;
+  };
+  
+  const handleCustomerChange = (value: string | null): void => {
+    selectedCustomer = value;
+  };
+  
+  // 产品查找
+  const handleProductLookup = (): void => {
+    showProductModal = true;
+  };
+  
+  const handleProductSelect = (product: Product): void => {
+    selectedProduct = product.id;
+    productText = `${product.name} - ¥${product.price}`;
+    showProductModal = false;
+  };
+  
+  const handleProductChange = (value: string | null): void => {
+    selectedProduct = value;
+  };
+</script>
+
+<!-- 客户查找 -->
+<LookupEditor 
+  placeholder="请选择客户"
+  bind:value={selectedCustomer}
+  bind:text={customerText}
+  onAction={handleCustomerLookup}
+  onChange={handleCustomerChange}
+/>
+
+<!-- 产品查找 -->
+<LookupEditor 
+  placeholder="请选择产品"
+  mandatory={true}
+  bind:value={selectedProduct}
+  bind:text={productText}
+  onAction={handleProductLookup}
+  onChange={handleProductChange}
+/>
+
+<!-- 客户查找模态框 -->
+{#if showCustomerModal}
+  <CustomerLookupModal 
+    onSelect={handleCustomerSelect}
+    onClose={() => showCustomerModal = false}
+  />
+{/if}
+
+<!-- 产品查找模态框 -->
+{#if showProductModal}
+  <ProductLookupModal 
+    onSelect={handleProductSelect}
+    onClose={() => showProductModal = false}
+  />
+{/if}
+```
+
+## 高级用法
+
+### 多步骤查找流程
+```svelte
+<script lang="ts">
+  interface Supplier {
+    id: string;
+    name: string;
+    country: string;
+  }
+  
+  interface SupplierProduct {
+    id: string;
+    name: string;
+    supplier_id: string;
+    price: number;
+  }
+  
+  let selectedSupplier: string | null = null;
+  let supplierText: string = '';
+  let selectedSupplierProduct: string | null = null;
+  let supplierProductText: string = '';
+  let showSupplierModal: boolean = false;
+  let showSupplierProductModal: boolean = false;
+  
+  const handleSupplierLookup = (): void => {
+    showSupplierModal = true;
+  };
+  
+  const handleSupplierSelect = (supplier: Supplier): void => {
+    selectedSupplier = supplier.id;
+    supplierText = `${supplier.name} (${supplier.country})`;
+    showSupplierModal = false;
+    
+    // 重置供应商产品选择
+    selectedSupplierProduct = null;
+    supplierProductText = '';
+  };
+  
+  const handleSupplierProductLookup = (): void => {
+    if (!selectedSupplier) {
+      alert('请先选择供应商');
+      return;
+    }
+    showSupplierProductModal = true;
+  };
+  
+  const handleSupplierProductSelect = (product: SupplierProduct): void => {
+    selectedSupplierProduct = product.id;
+    supplierProductText = `${product.name} - ¥${product.price}`;
+    showSupplierProductModal = false;
+  };
+</script>
+
+<div class="lookup-flow">
+  <div class="form-field">
+    <label>供应商：</label>
+    <LookupEditor 
+      placeholder="请选择供应商"
+      bind:value={selectedSupplier}
+      bind:text={supplierText}
+      onAction={handleSupplierLookup}
+    />
+  </div>
+  
+  <div class="form-field">
+    <label>供应商产品：</label>
+    <LookupEditor 
+      placeholder="请选择产品"
+      disabled={!selectedSupplier}
+      bind:value={selectedSupplierProduct}
+      bind:text={supplierProductText}
+      onAction={handleSupplierProductLookup}
+    />
+  </div>
+</div>
+```
+
+### 带缓存的查找
+```svelte
+<script lang="ts">
+  interface CacheEntry<T> {
+    data: T;
+    timestamp: number;
+  }
+  
+  class LookupCache {
+    private cache = new Map<string, CacheEntry<any>>();
+    private ttl = 5 * 60 * 1000; // 5分钟缓存
+    
+    get<T>(key: string): T | null {
+      const entry = this.cache.get(key);
+      if (!entry) return null;
+      
+      if (Date.now() - entry.timestamp > this.ttl) {
+        this.cache.delete(key);
+        return null;
+      }
+      
+      return entry.data;
+    }
+    
+    set<T>(key: string, data: T): void {
+      this.cache.set(key, {
+        data,
+        timestamp: Date.now()
+      });
+    }
+    
+    clear(): void {
+      this.cache.clear();
+    }
+  }
+  
+  const cache = new LookupCache();
+  
+  let selectedUser: string | null = null;
+  let userText: string = '';
+  let showUserModal: boolean = false;
+  
+  const handleUserLookup = (): void => {
+    // 检查缓存
+    const cachedUsers = cache.get('users');
+    if (cachedUsers) {
+      console.log('使用缓存的用户数据');
+    }
+    
+    showUserModal = true;
+  };
+  
+  interface User {
+    id: string;
+    name: string;
+    email: string;
+  }
+  
+  const handleUserSelect = (user: User): void => {
+    selectedUser = user.id;
+    userText = `${user.name} (${user.email})`;
+    
+    // 缓存用户数据
+    cache.set(`user:${user.id}`, user);
+    
+    showUserModal = false;
+  };
+</script>
+```
+
+### 外部API集成
+```svelte
+<script lang="ts">
+  interface ApiResponse<T> {
+    data: T[];
+    total: number;
+    page: number;
+  }
+  
+  interface ApiUser {
+    id: number;
+    name: string;
+    email: string;
+    department: string;
+  }
+  
+  let selectedApiUser: number | null = null;
+  let apiUserText: string = '';
+  let showApiUserModal: boolean = false;
+  let isLoading: boolean = false;
+  
+  const searchUsers = async (query: string, page: number = 1): Promise<ApiResponse<ApiUser>> => {
+    const response: Response = await fetch(`/api/users/search?q=${encodeURIComponent(query)}&page=${page}`);
+    if (!response.ok) {
+      throw new Error('搜索用户失败');
+    }
+    return await response.json();
+  };
+  
+  const handleApiUserLookup = (): void => {
+    showApiUserModal = true;
+  };
+  
+  const handleApiUserSelect = async (userId: number): Promise<void> => {
+    isLoading = true;
+    try {
+      const response: Response = await fetch(`/api/users/${userId}`);
+      const user: ApiUser = await response.json();
+      
+      selectedApiUser = user.id;
+      apiUserText = `${user.name} - ${user.department}`;
+      showApiUserModal = false;
+    } catch (error: unknown) {
+      console.error('获取用户详情失败：', error);
+    } finally {
+      isLoading = false;
+    }
+  };
+</script>
+
+<LookupEditor 
+  placeholder="请选择API用户"
+  disabled={isLoading}
+  bind:value={selectedApiUser}
+  bind:text={apiUserText}
+  onAction={handleApiUserLookup}
+/>
+
+{#if isLoading}
+  <div class="loading-indicator">加载中...</div>
+{/if}
+```
+
+## 最佳实践
+
+### 1. 提供清晰的显示文本
+```typescript
+interface DisplayItem {
+  name: string;
+  code: string;
+  category: string;
+}
+
+const formatDisplayText = (item: DisplayItem): string => {
+  return `${item.name} (${item.code}) - ${item.category}`;
+};
+```
+
+### 2. 处理必填验证
+```svelte
+<script lang="ts">
+  let value: string | null = null;
+  let error: string = '';
+  
+  const validate = (): boolean => {
+    if (!value) {
+      error = '此字段为必填项';
+      return false;
+    }
+    error = '';
+    return true;
+  };
+</script>
+
+<LookupEditor 
+  mandatory={true}
+  bind:value={value}
+  onAction={handleLookup}
+/>
+{#if error}
+  <div class="error-message">{error}</div>
+{/if}
+```
+
+### 3. 响应式模态框
+```svelte
+<script lang="ts">
+  import { onMount } from 'svelte';
+  
+  let isMobile: boolean = false;
+  let showModal: boolean = false;
+  
+  const checkMobile = (): void => {
+    isMobile = window.innerWidth < 768;
+  };
+  
+  const handleSelect = (item: any): void => {
+    // Handle selection logic
+  };
+  
+  onMount((): (() => void) => {
+    checkMobile();
+    window.addEventListener('resize', checkMobile);
+    return (): void => window.removeEventListener('resize', checkMobile);
+  });
+</script>
+
+{#if showModal}
+  <LookupModal 
+    fullscreen={isMobile}
+    onSelect={handleSelect}
+    onClose={() => showModal = false}
+  />
+{/if}
+```