@ticatec/uniface-flexi-module 0.0.2

package/FLEXIFORM_GUIDE_CN.md

@@ -0,0 +1,1068 @@
+# FlexiForm 完整使用指南
+
+在 Svelte 应用中构建动态、灵活表单的 FlexiForm 综合指南。
+
+## 目录
+
+1. [概述](#概述)
+2. [基础用法](#基础用法)
+3. [Schema 结构](#schema-结构)
+4. [字段类型](#字段类型)
+5. [布局和排列](#布局和排列)
+6. [动态表单生成](#动态表单生成)
+7. [事件和交互](#事件和交互)
+8. [扩展 FlexiForm](#扩展-flexiform)
+9. [高级模式](#高级模式)
+10. [最佳实践](#最佳实践)
+
+## 概述
+
+FlexiForm 是一个强大的表单框架，可以从 JSON 配置生成动态表单。它支持多种布局模式、各种字段类型，并为自定义组件提供可扩展的架构。
+
+### 主要特性
+
+- **动态基于 Schema**：从 JSON 配置生成表单
+- **灵活布局**：支持 flex 和 grid 布局
+- **可扩展字段类型**：内置字段 + 自定义字段支持
+- **事件系统**：丰富的表单交互事件处理
+- **类型安全**：完整的 TypeScript 支持
+- **模块化架构**：即插即用组件
+
+## 基础用法
+
+### 1. 安装和设置
+
+```typescript
+import { FlexiFormPage, registerFormFieldBuilder } from '@ticatec/uniface-flexi-form/flexi-form';
+import '@ticatec/uniface-flexi-form/uniface-flexi-form.css';
+
+// 注册所有字段构建器（必需）
+registerFormFieldBuilder();
+```
+
+### 2. 简单表单示例
+
+```svelte
+<!-- SimpleForm.svelte -->
+<script lang="ts">
+  import { FlexiFormPage } from '@ticatec/uniface-flexi-form/flexi-form';
+  
+  // 表单数据
+  let userData = {
+    name: '',
+    email: '',
+    age: null,
+    birthDate: null
+  };
+  
+  // 表单配置
+  const userFormSchema = {
+    mode: 'flex',
+    arrangement: 'vertical',
+    variant: 'outlined',
+    elements: {
+      'user-info': {
+        title: '用户信息',
+        fields: [
+          {
+            type: 'text-editor',
+            keyField: 'name',
+            name: 'name',
+            label: '全名',
+            required: true,
+            props: {
+              placeholder: '请输入您的全名'
+            }
+          },
+          {
+            type: 'text-editor',
+            keyField: 'email',
+            name: 'email',
+            label: '邮箱地址',
+            required: true,
+            props: {
+              type: 'email',
+              placeholder: '请输入您的邮箱'
+            }
+          },
+          {
+            type: 'number-editor',
+            keyField: 'age',
+            name: 'age',
+            label: '年龄',
+            props: {
+              min: 0,
+              max: 120
+            }
+          },
+          {
+            type: 'date-picker',
+            keyField: 'birthDate',
+            name: 'birthDate',
+            label: '出生日期'
+          }
+        ]
+      }
+    }
+  };
+  
+  function handleFormChange(event) {
+    console.log('表单数据改变:', event.detail);
+  }
+  
+  function handleSubmit() {
+    console.log('提交表单:', userData);
+  }
+</script>
+
+<FlexiFormPage 
+  schema={userFormSchema}
+  bind:data={userData}
+  on:change={handleFormChange}
+/>
+
+<button on:click={handleSubmit}>提交</button>
+```
+
+## Schema 结构
+
+### FlexiFormSchema
+
+```typescript
+interface FlexiFormSchema {
+  mode?: 'flex' | 'grid';           // 布局模式
+  arrangement?: 'vertical' | 'horizontal'; // 布局方向
+  props?: any;                      // 布局特定属性
+  elements: FormElements;           // 表单卡片/部分
+  label$style?: string;             // 标签样式
+  variant?: 'filled' | 'outlined' | ''; // 字段变体
+  actions?: Array<FormActionSchema>; // 表单操作
+  style?: string;                   // 自定义 CSS
+}
+
+type FormElements = {
+  [cardKey: string]: FlexiCardSchema | FlexiBlockSchema;
+}
+```
+
+### FlexiCardSchema
+
+```typescript
+interface FlexiCardSchema {
+  title?: string;                   // 卡片标题
+  mode?: 'flex' | 'grid';          // 卡片布局模式
+  props?: any;                      // 布局属性
+  arrangement?: 'vertical' | 'horizontal'; // 布局方向
+  fields: Array<FlexiFieldSchema>; // 此卡片中的字段
+  readonly?: boolean;               // 使卡片只读
+  disabled?: boolean;               // 禁用卡片
+  variant?: 'filled' | 'outlined' | ''; // 字段变体
+  foldable?: boolean;               // 允许折叠
+  actions?: Array<ActionSchema>;    // 卡片操作
+}
+```
+
+### FlexiCompositeSchema
+
+```typescript
+interface FlexiCompositeSchema {
+  type?: 'block';                   // 块类型标识符
+  title?: string;                   // 块标题
+  fields: Array<FlexiFieldSchema>; // 此组合块中的字段
+  readonly?: boolean;               // 使块只读
+  disabled?: boolean;               // 禁用块
+  label$style?: string;             // 标签样式
+  variant?: string;                 // 字段变体
+  mode?: LayoutMode;                // 布局模式
+  props?: any;                      // 布局属性
+  arrangement?: Arrangement;        // 布局方向
+}
+```
+
+### FlexiCompositeFieldSchema
+
+```typescript
+interface FlexiCompositeFieldSchema {
+  type: "composite";                // 类型标识符
+  keyField?: string;                // 嵌套对象的数据绑定路径
+  name: string;                     // 字段名称
+  composite: string;                // 引用的组合配置名称
+  cell?: any;                       // 单元格属性
+}
+```
+
+### FlexiFieldSchema
+
+```typescript
+interface FlexiFieldSchema {
+  type: string;                     // 字段类型标识符
+  keyField: string;                 // 数据绑定路径
+  name: string;                     // 字段名称
+  label: string;                    // 显示标签
+  dictName?: string;                // 选项字典
+  variant?: 'filled' | 'outlined' | ''; // 字段变体
+  readonly?: boolean;               // 字段只读状态
+  disabled?: boolean;               // 字段禁用状态
+  required?: boolean;               // 字段必填状态
+  events?: Record<string, string>;  // 事件处理器
+  cell?: any;                       // 单元格属性
+  props?: any;                      // 字段特定属性
+}
+```
+
+## 字段类型
+
+### 内置字段类型
+
+| 类型 | 描述 | 常用属性 |
+|------|-------------|--------------|
+| `text-editor` | 单行文本输入 | `placeholder`, `maxLength`, `pattern` |
+| `memo-editor` | 多行文本区域 | `rows`, `placeholder`, `maxLength` |
+| `number-editor` | 数字输入 | `min`, `max`, `step`, `precision` |
+| `unit-number-editor` | 带单位数字输入 | `min`, `max`, `step`, `unit`, `precision` |
+| `date-picker` | 日期选择 | `min`, `max`, `format` |
+| `datetime-picker` | 日期时间选择 | `min`, `max`, `format` |
+| `options-selector` | 单选下拉框 | `dictName`, `placeholder` |
+| `options-multi-selector` | 多选下拉框 | `dictName`, `maxSelections` |
+| `cascade-options-selector` | 级联选择 | `dictName`, `levels` |
+| `input-options-selector` | 可搜索选择 | `getOptions`, `minLength` |
+| `-` | 分隔线/换行符 | 视觉分隔符 |
+
+### 字段示例
+
+```typescript
+// 带验证的文本字段
+{
+  type: 'text-editor',
+  keyField: 'username',
+  name: 'username',
+  label: '用户名',
+  required: true,
+  props: {
+    placeholder: '请输入用户名',
+    maxLength: 50,
+    pattern: '^[a-zA-Z0-9_]+$'
+  }
+}
+
+// 带范围的数字字段
+{
+  type: 'number-editor',
+  keyField: 'price',
+  name: 'price',
+  label: '价格',
+  props: {
+    min: 0,
+    max: 9999.99,
+    step: 0.01,
+    prefix: '￥'
+  }
+}
+
+// 带约束的日期字段
+{
+  type: 'date-picker',
+  keyField: 'startDate',
+  name: 'startDate',
+  label: '开始日期',
+  props: {
+    min: '2024-01-01',
+    max: '2024-12-31',
+    format: 'YYYY-MM-DD'
+  }
+}
+
+// 带字典的选择字段
+{
+  type: 'options-selector',
+  keyField: 'category',
+  name: 'category',
+  label: '分类',
+  dictName: 'product-categories',
+  required: true,
+  props: {
+    placeholder: '请选择分类'
+  }
+}
+```
+
+## 布局和排列
+
+### Flex 布局
+
+```typescript
+const flexFormSchema = {
+  mode: 'flex',
+  arrangement: 'vertical',
+  elements: {
+    'main-card': {
+      mode: 'flex',
+      arrangement: 'horizontal', // 字段并排
+      fields: [
+        {
+          type: 'text-editor',
+          keyField: 'firstName',
+          name: 'firstName',
+          label: '名字',
+          cell: { flex: 1 } // 等宽
+        },
+        {
+          type: 'text-editor',
+          keyField: 'lastName',
+          name: 'lastName',
+          label: '姓氏',
+          cell: { flex: 1 } // 等宽
+        }
+      ]
+    }
+  }
+};
+```
+
+### Grid 布局
+
+```typescript
+const gridFormSchema = {
+  mode: 'grid',
+  props: {
+    columns: 3, // 3列网格
+    gap: '16px'
+  },
+  elements: {
+    'contact-info': {
+      mode: 'grid',
+      props: {
+        columns: 2 // 此卡片2列网格
+      },
+      fields: [
+        {
+          type: 'text-editor',
+          keyField: 'email',
+          name: 'email',
+          label: '邮箱',
+          cell: { colspan: 2 } // 跨2列
+        },
+        {
+          type: 'text-editor',
+          keyField: 'phone',
+          name: 'phone',
+          label: '电话'
+        },
+        {
+          type: 'text-editor',
+          keyField: 'mobile',
+          name: 'mobile',
+          label: '手机'
+        }
+      ]
+    }
+  }
+};
+```
+
+## 动态表单生成
+
+### 从 API 加载 Schema
+
+```typescript
+class DynamicFormLoader {
+  async loadFormSchema(formId: string): Promise<FlexiFormSchema> {
+    const response = await fetch(`/api/forms/${formId}/schema`);
+    return await response.json();
+  }
+  
+  async loadFormData(formId: string, recordId?: string): Promise<any> {
+    const url = recordId 
+      ? `/api/forms/${formId}/data/${recordId}`
+      : `/api/forms/${formId}/data/new`;
+    const response = await fetch(url);
+    return await response.json();
+  }
+}
+
+// 在组件中使用
+const loader = new DynamicFormLoader();
+let formSchema = null;
+let formData = {};
+
+onMount(async () => {
+  formSchema = await loader.loadFormSchema('user-profile');
+  formData = await loader.loadFormData('user-profile', userId);
+});
+```
+
+### Schema 构建器模式
+
+```typescript
+class FormSchemaBuilder {
+  private schema: FlexiFormSchema;
+  
+  constructor() {
+    this.schema = {
+      mode: 'flex',
+      arrangement: 'vertical',
+      variant: 'outlined',
+      elements: {}
+    };
+  }
+  
+  addCard(key: string, title?: string): CardBuilder {
+    const cardBuilder = new CardBuilder(title);
+    this.schema.elements[key] = cardBuilder.getSchema();
+    return cardBuilder;
+  }
+  
+  setLayout(mode: 'flex' | 'grid', arrangement?: 'vertical' | 'horizontal') {
+    this.schema.mode = mode;
+    this.schema.arrangement = arrangement;
+    return this;
+  }
+  
+  build(): FlexiFormSchema {
+    return this.schema;
+  }
+}
+
+class CardBuilder {
+  private card: FlexiCardSchema;
+  
+  constructor(title?: string) {
+    this.card = {
+      title,
+      fields: []
+    };
+  }
+  
+  addTextField(keyField: string, label: string, options: any = {}) {
+    this.card.fields.push({
+      type: 'text-editor',
+      keyField,
+      name: keyField,
+      label,
+      ...options
+    });
+    return this;
+  }
+  
+  addSelectField(keyField: string, label: string, dictName: string, options: any = {}) {
+    this.card.fields.push({
+      type: 'options-selector',
+      keyField,
+      name: keyField,
+      label,
+      dictName,
+      ...options
+    });
+    return this;
+  }
+  
+  getSchema(): FlexiCardSchema {
+    return this.card;
+  }
+}
+
+// 使用方法
+const schema = new FormSchemaBuilder()
+  .setLayout('flex', 'vertical')
+  .addCard('personal', '个人信息')
+    .addTextField('name', '全名', { required: true })
+    .addTextField('email', '邮箱', { required: true })
+    .addSelectField('country', '国家', 'countries')
+  .build();
+```
+
+## 事件和交互
+
+### 表单级事件
+
+```svelte
+<script>
+  function handleFormChange(event) {
+    const { data, field, value } = event.detail;
+    console.log(`字段 ${field} 改变为:`, value);
+    console.log('完整表单数据:', data);
+  }
+  
+  function handleFormSubmit(event) {
+    const { data, isValid } = event.detail;
+    if (isValid) {
+      submitForm(data);
+    } else {
+      console.error('表单验证失败');
+    }
+  }
+  
+  function handleFormReset(event) {
+    console.log('表单已重置');
+  }
+</script>
+
+<FlexiFormPage 
+  {schema}
+  bind:data={formData}
+  on:change={handleFormChange}
+  on:submit={handleFormSubmit}
+  on:reset={handleFormReset}
+/>
+```
+
+### 字段级事件
+
+```typescript
+// 在 schema 定义中
+{
+  type: 'text-editor',
+  keyField: 'email',
+  name: 'email',
+  label: '邮箱',
+  events: {
+    change: 'onEmailChange',
+    blur: 'onEmailBlur',
+    focus: 'onEmailFocus'
+  }
+}
+
+// 在表单实现类中
+class UserForm extends FlexiForm {
+  onEmailChange(value: string) {
+    console.log('邮箱改变:', value);
+    // 触发邮箱验证
+    this.validateEmail(value);
+  }
+  
+  onEmailBlur(event: FocusEvent) {
+    console.log('邮箱字段失去焦点');
+    // 检查邮箱重复
+    this.checkEmailUniqueness(event.target.value);
+  }
+  
+  onEmailFocus(event: FocusEvent) {
+    console.log('邮箱字段获得焦点');
+  }
+}
+```
+
+## 扩展 FlexiForm
+
+### 创建自定义字段类型
+
+#### 1. 创建自定义字段组件
+
+```svelte
+<!-- CustomRatingField.svelte -->
+<script lang="ts">
+  import type FlexiField from "$lib/flexi-form/flexi_field/FlexiField";
+  
+  export let field: FlexiField;
+  export let readonly: boolean;
+  export let disabled: boolean;
+  export let variant: "" | "outlined" | "filled";
+  
+  $: props = field.props;
+  $: data = field.data;
+  $: events = field.events;
+  
+  const maxRating = props.maxRating || 5;
+  let currentRating = data[field.keyField] || 0;
+  
+  function setRating(rating: number) {
+    if (readonly || disabled) return;
+    currentRating = rating;
+    data[field.keyField] = rating;
+    events.change?.(rating);
+  }
+</script>
+
+<div class="rating-field" class:readonly class:disabled>
+  <label>{field.label}</label>
+  <div class="stars">
+    {#each Array(maxRating) as _, i}
+      <button
+        type="button"
+        class="star"
+        class:filled={i < currentRating}
+        {disabled}
+        on:click={() => setRating(i + 1)}
+      >
+        ⭐
+      </button>
+    {/each}
+  </div>
+</div>
+
+<style>
+  .rating-field {
+    display: flex;
+    flex-direction: column;
+    gap: 8px;
+  }
+  
+  .stars {
+    display: flex;
+    gap: 4px;
+  }
+  
+  .star {
+    background: none;
+    border: none;
+    font-size: 24px;
+    cursor: pointer;
+    opacity: 0.3;
+    transition: opacity 0.2s;
+  }
+  
+  .star.filled {
+    opacity: 1;
+  }
+  
+  .star:hover:not(:disabled) {
+    opacity: 0.7;
+  }
+  
+  .readonly .star, .disabled .star {
+    cursor: default;
+  }
+</style>
+```
+
+#### 2. 注册自定义字段类型
+
+```typescript
+import { ComponentBuilder } from '@ticatec/uniface-flexi-form/flexi-form/lib/ComponentBuilder';
+import CustomRatingField from './CustomRatingField.svelte';
+
+// 创建构建器函数
+const buildRatingField = (schema: FlexiFieldSchema, dictLoader: DictionaryLoader) => {
+  return {
+    component: CustomRatingField,
+    props: schema.props
+  };
+};
+
+// 注册自定义字段类型
+const componentBuilder = ComponentBuilder.getInstance();
+componentBuilder.register('rating-field', buildRatingField);
+
+// 在 schema 中使用
+const schemaWithRating = {
+  mode: 'flex',
+  elements: {
+    'review-card': {
+      title: '产品评价',
+      fields: [
+        {
+          type: 'rating-field',
+          keyField: 'rating',
+          name: 'rating',
+          label: '产品评分',
+          props: {
+            maxRating: 5
+          }
+        },
+        {
+          type: 'memo-editor',
+          keyField: 'comment',
+          name: 'comment',
+          label: '评价意见'
+        }
+      ]
+    }
+  }
+};
+```
+
+### 创建自定义表单类
+
+```typescript
+import FlexiForm, { type FlexiFormSchema } from '@ticatec/uniface-flexi-form/flexi-form';
+
+class UserProfileForm extends FlexiForm {
+  private userId: string;
+  
+  constructor(userId: string, data: any, schema: FlexiFormSchema) {
+    super(data, schema);
+    this.userId = userId;
+  }
+  
+  protected buildCards(): void {
+    // 自定义卡片构建逻辑
+    for (const [key, element] of Object.entries(this.elements)) {
+      if (element.type === 'block') {
+        // 处理块元素
+      } else {
+        // 使用自定义逻辑创建卡片
+        const card = new CustomUserCard(this, element as FlexiCardSchema);
+        this.cards.push(card);
+      }
+    }
+  }
+  
+  getTitle(): string {
+    return `用户资料 - ${this.data.name || '新用户'}`;
+  }
+  
+  // 自定义方法
+  async saveProfile(): Promise<void> {
+    try {
+      await fetch(`/api/users/${this.userId}`, {
+        method: 'PUT',
+        headers: { 'Content-Type': 'application/json' },
+        body: JSON.stringify(this.data)
+      });
+      console.log('资料保存成功');
+    } catch (error) {
+      console.error('保存资料失败:', error);
+    }
+  }
+  
+  validateEmail(email: string): boolean {
+    const emailRegex = /^[^\s@]+@[^\s@]+\.[^\s@]+$/;
+    return emailRegex.test(email);
+  }
+  
+  // 事件处理器（从字段事件调用）
+  onEmailChange(value: string): void {
+    if (!this.validateEmail(value)) {
+      console.warn('邮箱格式无效');
+    }
+  }
+  
+  onPhoneChange(value: string): void {
+    // 格式化电话号码
+    const formatted = this.formatPhoneNumber(value);
+    this.data.phone = formatted;
+    this.invalidate(); // 触发 UI 更新
+  }
+  
+  private formatPhoneNumber(phone: string): string {
+    const cleaned = phone.replace(/\D/g, '');
+    if (cleaned.length === 11) {
+      return `${cleaned.slice(0, 3)}-${cleaned.slice(3, 7)}-${cleaned.slice(7)}`;
+    }
+    return phone;
+  }
+}
+
+// 使用方法
+const userForm = new UserProfileForm(userId, userData, formSchema);
+await userForm.initialize();
+```
+
+## 高级模式
+
+### 条件字段显示
+
+```typescript
+class ConditionalFormCard extends FlexiCard {
+  protected createFromSchema(): void {
+    super.createFromSchema();
+    
+    // 添加条件逻辑
+    this.setupConditionalFields();
+  }
+  
+  private setupConditionalFields(): void {
+    const typeField = this.field['userType'];
+    const companyField = this.field['company'];
+    
+    if (typeField && companyField) {
+      typeField.events.change = (value: string) => {
+        companyField.visibility = value === 'business' 
+          ? Visibility.View 
+          : Visibility.Hidden;
+        this.invalidate();
+      };
+    }
+  }
+}
+```
+
+### 动态字段依赖
+
+```typescript
+class DependentFieldsHandler {
+  private form: FlexiForm;
+  private dependencies: Map<string, string[]> = new Map();
+  
+  constructor(form: FlexiForm) {
+    this.form = form;
+    this.setupDependencies();
+  }
+  
+  setupDependencies(): void {
+    // 定义字段依赖关系
+    this.dependencies.set('country', ['state', 'city']);
+    this.dependencies.set('state', ['city']);
+    
+    // 设置变化处理器
+    for (const [parentField, dependentFields] of this.dependencies) {
+      this.setupFieldHandler(parentField, dependentFields);
+    }
+  }
+  
+  private setupFieldHandler(parentField: string, dependentFields: string[]): void {
+    const field = this.findField(parentField);
+    if (field) {
+      const originalHandler = field.events.change;
+      field.events.change = async (value: any) => {
+        // 调用原始处理器
+        originalHandler?.(value);
+        
+        // 更新依赖字段
+        await this.updateDependentFields(parentField, value, dependentFields);
+      };
+    }
+  }
+  
+  private async updateDependentFields(
+    parentField: string, 
+    value: any, 
+    dependentFields: string[]
+  ): Promise<void> {
+    for (const fieldName of dependentFields) {
+      const field = this.findField(fieldName);
+      if (field) {
+        // 清除当前值
+        this.form.data[fieldName] = null;
+        
+        // 加载新选项
+        const options = await this.loadOptions(fieldName, { [parentField]: value });
+        field.props.options = options;
+      }
+    }
+    
+    this.form.invalidate();
+  }
+  
+  private async loadOptions(fieldName: string, context: any): Promise<any[]> {
+    const response = await fetch(`/api/options/${fieldName}`, {
+      method: 'POST',
+      headers: { 'Content-Type': 'application/json' },
+      body: JSON.stringify(context)
+    });
+    return await response.json();
+  }
+  
+  private findField(fieldName: string): FlexiField | null {
+    for (const card of this.form.cards) {
+      if (card.field[fieldName]) {
+        return card.field[fieldName];
+      }
+    }
+    return null;
+  }
+}
+```
+
+### 表单向导模式
+
+```typescript
+class WizardFormManager {
+  private steps: FlexiFormSchema[] = [];
+  private currentStep = 0;
+  private stepData: any[] = [];
+  
+  constructor(steps: FlexiFormSchema[]) {
+    this.steps = steps;
+    this.stepData = new Array(steps.length).fill({});
+  }
+  
+  getCurrentSchema(): FlexiFormSchema {
+    return this.steps[this.currentStep];
+  }
+  
+  getCurrentData(): any {
+    return this.stepData[this.currentStep];
+  }
+  
+  nextStep(): boolean {
+    if (this.currentStep < this.steps.length - 1) {
+      this.currentStep++;
+      return true;
+    }
+    return false;
+  }
+  
+  previousStep(): boolean {
+    if (this.currentStep > 0) {
+      this.currentStep--;
+      return true;
+    }
+    return false;
+  }
+  
+  getFinalData(): any {
+    return this.stepData.reduce((acc, stepData) => ({
+      ...acc,
+      ...stepData
+    }), {});
+  }
+  
+  isFirstStep(): boolean {
+    return this.currentStep === 0;
+  }
+  
+  isLastStep(): boolean {
+    return this.currentStep === this.steps.length - 1;
+  }
+  
+  getProgress(): number {
+    return ((this.currentStep + 1) / this.steps.length) * 100;
+  }
+}
+
+// 在 Svelte 组件中使用
+let wizardManager = new WizardFormManager([
+  personalInfoSchema,
+  contactInfoSchema,
+  preferencesSchema
+]);
+
+function handleNext() {
+  if (wizardManager.nextStep()) {
+    currentSchema = wizardManager.getCurrentSchema();
+    currentData = wizardManager.getCurrentData();
+  } else {
+    // 提交最终表单
+    submitWizardData(wizardManager.getFinalData());
+  }
+}
+```
+
+## 最佳实践
+
+### 1. Schema 组织
+
+```typescript
+// 好的：有组织的 schema 结构
+const FORM_SCHEMAS = {
+  userProfile: {
+    mode: 'flex',
+    arrangement: 'vertical',
+    elements: {
+      personal: USER_PERSONAL_CARD,
+      contact: USER_CONTACT_CARD,
+      preferences: USER_PREFERENCES_CARD
+    }
+  }
+};
+
+const USER_PERSONAL_CARD: FlexiCardSchema = {
+  title: '个人信息',
+  fields: [
+    FIELDS.firstName,
+    FIELDS.lastName,
+    FIELDS.birthDate
+  ]
+};
+
+const FIELDS = {
+  firstName: {
+    type: 'text-editor',
+    keyField: 'firstName',
+    name: 'firstName',
+    label: '名字',
+    required: true,
+    props: { maxLength: 50 }
+  },
+  // ... 更多字段定义
+};
+```
+
+### 2. 类型安全
+
+```typescript
+// 为你的 schema 定义严格类型
+interface UserFormData {
+  firstName: string;
+  lastName: string;
+  email: string;
+  birthDate: Date;
+  preferences: UserPreferences;
+}
+
+interface UserPreferences {
+  newsletter: boolean;
+  language: string;
+  timezone: string;
+}
+
+// 使用类型化表单创建
+class TypedUserForm extends FlexiForm {
+  protected data: UserFormData;
+  
+  constructor(data: UserFormData, schema: FlexiFormSchema) {
+    super(data, schema);
+  }
+  
+  getData(): UserFormData {
+    return this.data;
+  }
+}
+```
+
+### 3. 错误处理
+
+```typescript
+class FormErrorHandler {
+  static handleFormError(error: any, form: FlexiForm): void {
+    if (error.validationErrors) {
+      this.displayValidationErrors(error.validationErrors, form);
+    } else if (error.networkError) {
+      this.displayNetworkError(error.networkError);
+    } else {
+      this.displayGenericError(error);
+    }
+  }
+  
+  private static displayValidationErrors(
+    errors: Record<string, string>, 
+    form: FlexiForm
+  ): void {
+    for (const [fieldName, errorMessage] of Object.entries(errors)) {
+      const field = this.findFieldInForm(fieldName, form);
+      if (field) {
+        field.error = errorMessage;
+      }
+    }
+    form.invalidate();
+  }
+}
+```
+
+### 4. 性能优化
+
+```typescript
+// 延迟加载大型表单
+class LazyFormLoader {
+  private formCache = new Map<string, FlexiFormSchema>();
+  
+  async loadForm(formId: string): Promise<FlexiFormSchema> {
+    if (this.formCache.has(formId)) {
+      return this.formCache.get(formId)!;
+    }
+    
+    const schema = await fetch(`/api/forms/${formId}`).then(r => r.json());
+    this.formCache.set(formId, schema);
+    return schema;
+  }
+  
+  preloadForms(formIds: string[]): void {
+    formIds.forEach(id => this.loadForm(id));
+  }
+}
+
+// 防抖表单变化
+function createDebouncedFormHandler(delay = 300) {
+  let timeoutId: number;
+  
+  return function(handler: Function) {
+    return function(...args: any[]) {
+      clearTimeout(timeoutId);
+      timeoutId = setTimeout(() => handler(...args), delay);
+    };
+  };
+}
+```
+
+这个综合指南提供了有效使用和扩展 FlexiForm 所需的一切。示例从基础用法逐步发展到高级模式，展示了如何使用 FlexiForm 的灵活架构构建复杂的表单系统。