@ticatec/uniface-flexi-module 0.0.2

package/FLEXICRITERIASET_GUIDE_CN.md

@@ -0,0 +1,1133 @@
+# FlexiCriteriaSet 完整使用指南
+
+在 Svelte 应用中构建动态搜索和过滤面板的 FlexiCriteriaSet 综合指南。
+
+## 目录
+
+1. [概述](#概述)
+2. [基础用法](#基础用法)
+3. [Schema 结构](#schema-结构)
+4. [搜索字段类型](#搜索字段类型)
+5. [高级搜索模式](#高级搜索模式)
+6. [动态搜索生成](#动态搜索生成)
+7. [事件和交互](#事件和交互)
+8. [扩展 FlexiCriteriaSet](#扩展-flexicriteriaset)
+9. [集成模式](#集成模式)
+10. [最佳实践](#最佳实践)
+
+## 概述
+
+FlexiCriteriaSet 是一个强大的搜索条件构建器，允许用户通过直观的界面构建复杂的搜索查询。它支持各种字段类型、操作符，并为自定义搜索组件提供可扩展的架构。
+
+### 主要特性
+
+- **灵活的搜索字段**：支持文本、数字、日期、选择和范围搜索
+- **动态操作符**：针对不同字段类型的上下文相关操作符
+- **基于 Schema 的配置**：JSON 驱动的搜索面板设置
+- **可扩展架构**：自定义字段类型和搜索逻辑
+- **类型安全**：完整的 TypeScript 支持
+- **实时更新**：即时搜索条件生成
+
+## 基础用法
+
+### 1. 安装和设置
+
+```typescript
+import CriteriaPanel, { FlexiCriteriaSet } from '@ticatec/uniface-flexi-module/criteria-panel';
+import {registerCriteriaFieldBuilder} from '@ticatec/uniface-flexi-module/criteria-panel';
+import '@ticatec/uniface-flexi-form/uniface-flexi-module.css';
+```
+
+### 2. 简单搜索面板
+
+```ts
+import {FlexiCriteriaSet} from '@ticatec/uniface-flexi-module/criteria-panel';
+
+const userSearchSchema = {
+    arrangement: 'vertical',
+    variant: 'outlined',
+    fields: [
+        {
+            type: 'text-editor',
+            name: 'userName',
+            label: '用户名',
+            keys: {keyField: 'userName'},
+            size: 'x25',
+            props: {
+                placeholder: '请输入用户名'
+            }
+        },
+        {
+            type: 'options-selector',
+            name: 'status',
+            label: '状态',
+            keys: {keyField: 'status'},
+            dictName: 'user-status',
+            size: 'x20',
+            props: {
+                placeholder: '请选择状态'
+            }
+        },
+        {
+            type: 'date-range',
+            name: 'registrationDate',
+            label: '注册日期',
+            keys: {
+                fromField: 'registeredFrom',
+                toField: 'registeredTo'
+            },
+            size: 'x30'
+        },
+        {
+            type: 'number-range',
+            name: 'age',
+            label: '年龄范围',
+            keys: {
+                formField: 'ageMin',
+                toField: 'ageMax'
+            },
+            size: 'x25'
+        }
+    ]
+};
+
+class UserSearchCriteriaSet extends FlexiCriteriaSet {
+    constructor() {
+        super(userSearchSchema);
+    }
+}
+
+```
+
+```svelte
+<script lang="ts">
+    
+    import CriteriaFieldsPanel from "$lib/criteria-panel";
+    import PagingListPage from "@ticatec/uniface-app-component/data-table/PagingListPage";
+    import {onMount} from "svelte";
+    import type {PageAttrs, PageInitialize} from "@ticatec/uniface-micro-frame/common";
+    import type {ActionsColumn, DataColumn, IndicatorColumn} from "@ticatec/uniface-element/DataTable";
+    import type {ButtonActions} from "@ticatec/uniface-element/ActionBar";
+    import FilterPanel from "@ticatec/uniface-filter-panel";
+    import {CustomDataTable} from "./CustomHome";
+    import Sandbox from "$lib/Sandbox";
+    import FlexiContext from "$lib";
+
+    const criteriaCode = `
+    const criteriaSchema = {
+    variant: "outlined",
+    fields: [
+        {
+            type: "text-editor",
+            name: "name",
+            keys: {valueField: "name"},
+            label: "姓名",
+            size: "x15",
+            props: {
+                input$placeholder: "*替代所有字符"
+            }
+        },
+        {
+            type: "text-editor",
+            name: "code",
+            keys: {valueField: "code"},
+            label: "编码",
+            size: "x15",
+            props: {
+                input$placeholder: "*替代所有字符"
+            }
+        },
+        {
+            type: "options-selector",
+            keys: {valueField: "gender"},
+            name: "gender",
+            label: "性别",
+            size: "x15",
+            props: {
+                emptyText: "所有",
+                options: [
+                    {code: "M", text: "男"},
+                    {code: "F", text: "女"}
+                ]
+            }
+        },
+        {
+            type: "number-range",
+            name: "age",
+            keys: {fromField: "fromAge", toField: "toAge"},
+            size: "x30",
+            label: "年龄范围",
+            props: {
+                emptyText: "所有"
+            }
+        }
+    ]
+}
+
+class CustomCriteriaSet extends FlexiCriteriaSet {
+
+    constructor() {
+        super(criteriaSchema);
+    }
+}
+
+return {CustomCriteriaSet}
+
+    `
+    let criteriaSet: any;
+
+    let criteria: any = {};
+    let dataTable;
+
+    onMount(async () => {
+        FlexiContext.initialize(async (dicNames)=> ({}))
+        let sandbox = Sandbox.initialize({}, []);
+        console.log("sandbox", sandbox);
+        const {CustomCriteriaSet} = await sandbox.createFormClass(criteriaCode);
+        console.log("CustomCriteriaSet", CustomCriteriaSet);
+        const set = new CustomCriteriaSet();
+        set.initialize();
+        criteriaSet = set;
+        console.log(set);
+        dataTable = new CustomDataTable();
+        await dataTable.initialize();
+        columns = dataTable.columns;
+        indicatorColumn = dataTable.indicatorColumn;
+        actionsColumn = dataTable.actionsColumn;
+        console.log('表格列：', columns, indicatorColumn, actionsColumn);
+        loaded = true;
+    })
+
+
+    $: console.log('当前查询条件：', criteria);
+
+    let page$attrs: PageAttrs = {
+        title: "演示页面"
+    };
+
+
+    let list: Array<any> =  [{name:"我的数据1", status: 0}, {name:"我的数据2", status: 2}];
+
+    let indicatorColumn: IndicatorColumn;
+
+    let columns: Array<DataColumn> = [];
+    let actionsColumn: ActionsColumn | null = null;
+
+    let total: number = 125;
+    let pageCount: number = 5;
+    let pageNo: number = 3;
+    const onRowCountChanged = () => {
+
+    }
+    const onPageChange = () => {
+
+    }
+
+
+    const actions: ButtonActions = [];
+
+    const doSearch = async (reset: boolean = false) => {
+
+    }
+
+    let loaded: boolean = false;
+
+
+</script>
+{#if loaded}
+    <PagingListPage {page$attrs} {columns} {indicatorColumn} {actionsColumn} bind:list {onRowCountChanged} {onPageChange} {total}
+                    {pageCount} {pageNo}>
+        <div slot="search-panel" style="padding: 8px 0">
+            <FilterPanel {actions} resetClickHandler={()=>doSearch(true)} searchClickHandler={()=>doSearch()}>
+                {#if criteriaSet}
+                    <CriteriaFieldsPanel bind:criteria {criteriaSet}>
+                    </CriteriaFieldsPanel>
+                {/if}
+            </FilterPanel>
+        </div>
+    </PagingListPage>
+{/if}
+```
+
+## Schema 结构
+
+### FlexiCriteriaSetSchema
+
+```typescript
+interface FlexiCriteriaSetSchema {
+  variant?: 'outlined' | 'filled';  // 字段变体
+  arrangement?: 'vertical' | 'horizontal'; // 布局方向
+  label$style?: string;              // 标签样式
+  fields: Array<FlexiCriteriaFieldSchema>; // 搜索字段
+}
+```
+
+### FlexiCriteriaFieldSchema
+
+```typescript
+interface FlexiCriteriaFieldSchema {
+  type: string;                      // 字段类型标识符
+  keys: { [key: string]: string };  // 数据绑定键
+  name: string;                     // 字段名称
+  dictName?: string;                 // 选项字典
+  visible?: boolean;                 // 字段可见性
+  label: string;                     // 显示标签
+  events?: Record<string, string>;   // 事件处理器
+  size?: 'x15' | 'x20' | 'x25' | 'x30' | 'x35' | 'x40'; // 字段宽度
+  props?: any;                       // 字段特定属性
+}
+```
+
+## 搜索字段类型
+
+### 内置字段类型
+
+| 类型 | 描述 | keys                    | 常用属性                   |
+|------|-------------|------------------------|------------------------|
+| `cascade-options` | 级联选择搜索 | `keyField`, `textField` | `dictName`, `levels`   |
+| `date-range` | 日期范围搜索 | `fromField`, `toField` | `min`, `max`, `format` |
+| `date-picker` | 日期搜索字段 | `keyField`                | `min`, `max`, `format` |
+| `datetime-picker` | 日期时间搜索 | `keyField`                | `min`, `max`, `format` |
+| `input-options-selector` | 可搜索选择 | `keyField`                | `getOptions`           |
+| `number-range` | 数字范围搜索 | `fromField`, `toField` |                        |
+| `number-editor` | 数字搜索字段 | `keyField`                | `min`, `max`, `operators` |
+| `options-multi-selector` | 多选搜索 | `keyField`                | `dictName`             |
+| `options-selector` | 单选搜索 | `keyField`                | `dictName`, `emptyText` |
+| `text-editor` | 文本搜索字段 | `keyField`                | `placeholder` |
+
+### 字段示例
+
+```typescript
+// 带操作符的文本搜索
+{
+  type: 'text-search',
+  name: 'productName',
+  label: '产品名称',
+  keys: { keyField: 'name' },
+  size: 'x30',
+  props: {
+    placeholder: '请输入产品名称',
+    operators: ['contains', 'startsWith', 'endsWith', 'equals']
+  }
+}
+
+// 数字范围搜索
+{
+  type: 'number-range',
+  name: 'priceRange',
+  label: '价格范围',
+  keys: { 
+    minField: 'priceMin', 
+    maxField: 'priceMax' 
+  },
+  size: 'x25',
+  props: {
+    min: 0,
+    max: 10000,
+    step: 10,
+    currency: 'CNY'
+  }
+}
+
+// 带约束的日期范围
+{
+  type: 'date-range',
+  name: 'orderDate',
+  label: '订单日期',
+  keys: { 
+    fromField: 'orderDateFrom', 
+    toField: 'orderDateTo' 
+  },
+  size: 'x30',
+  props: {
+    min: '2020-01-01',
+    max: new Date().toISOString().split('T')[0],
+    format: 'YYYY-MM-DD'
+  }
+}
+
+// 带字典的多选
+{
+  type: 'option-multi-select-search',
+  name: 'categories',
+  label: '分类',
+  keys: { field: 'categoryIds' },
+  dictName: 'product-categories',
+  size: 'x25',
+  props: {
+    placeholder: '请选择分类'
+  }
+}
+
+// 动态可搜索选择
+{
+  type: 'input-option-select-search',
+  name: 'assignee',
+  label: '分配给',
+  keys: { field: 'assigneeId' },
+  size: 'x25',
+  props: {
+    getOptions: 'loadUserSuggestions',
+    minLength: 2,
+    debounce: 300,
+    placeholder: '输入搜索用户'
+  }
+}
+```
+
+## 事件和交互
+
+### 搜索条件变化事件
+
+```svelte
+<script>
+  function handleCriteriaChange(event) {
+    const { criteria, field, value } = event.detail;
+    console.log(`字段 ${field} 改变为:`, value);
+    console.log('完整条件:', criteria);
+    
+    // 触发实时搜索
+    debouncedSearch(criteria);
+  }
+  
+  function handleFieldFocus(event) {
+    const { field } = event.detail;
+    console.log(`字段 ${field} 获得焦点`);
+    
+    // 为此字段加载建议
+    loadFieldSuggestions(field);
+  }
+  
+  function handleOperatorChange(event) {
+    const { field, operator } = event.detail;
+    console.log(`字段 ${field} 操作符改变为:`, operator);
+  }
+  
+  // 防抖搜索函数
+  const debouncedSearch = debounce((criteria) => {
+    performSearch(criteria);
+  }, 300);
+  
+  function debounce(func, wait) {
+    let timeout;
+    return function executedFunction(...args) {
+      const later = () => {
+        clearTimeout(timeout);
+        func(...args);
+      };
+      clearTimeout(timeout);
+      timeout = setTimeout(later, wait);
+    };
+  }
+</script>
+
+<CriteriaPanel 
+  {schema}
+  bind:criteria={searchCriteria}
+  on:change={handleCriteriaChange}
+  on:fieldFocus={handleFieldFocus}
+  on:operatorChange={handleOperatorChange}
+  on:search={handleSearch}
+  on:reset={handleReset}
+/>
+```
+
+## 扩展 FlexiCriteriaSet
+
+### 创建自定义搜索字段类型
+
+#### 1. 自定义范围滑块字段
+
+```svelte
+<!-- CustomRangeSliderField.svelte -->
+<script lang="ts">
+  import type FlexiCriteriaField from "$lib/criteria-panel/lib/FlexiCriteriaField";
+  
+  export let field: FlexiCriteriaField;
+  export let readonly: boolean = false;
+  export let disabled: boolean = false;
+  
+  $: props = field.props;
+  $: keys = field.keys;
+  
+  let minValue = props.min || 0;
+  let maxValue = props.max || 100;
+  let currentMin = minValue;
+  let currentMax = maxValue;
+  
+  // 从数据初始化
+  if (field.data) {
+    currentMin = field.data[keys.minField] || minValue;
+    currentMax = field.data[keys.maxField] || maxValue;
+  }
+  
+  function updateRange() {
+    if (!field.data) field.data = {};
+    field.data[keys.minField] = currentMin;
+    field.data[keys.maxField] = currentMax;
+    
+    // 触发变化事件
+    field.events.change?.({ min: currentMin, max: currentMax });
+  }
+  
+  $: if (currentMin !== undefined && currentMax !== undefined) {
+    updateRange();
+  }
+</script>
+
+<div class="range-slider-field" class:readonly class:disabled>
+  <label>{field.label}</label>
+  
+  <div class="range-inputs">
+    <input
+      type="number"
+      bind:value={currentMin}
+      min={minValue}
+      max={currentMax}
+      {disabled}
+      {readonly}
+      class="range-input"
+    />
+    <span class="range-separator">至</span>
+    <input
+      type="number"
+      bind:value={currentMax}
+      min={currentMin}
+      max={maxValue}
+      {disabled}
+      {readonly}
+      class="range-input"
+    />
+  </div>
+  
+  <div class="slider-container">
+    <input
+      type="range"
+      bind:value={currentMin}
+      min={minValue}
+      max={maxValue}
+      step={props.step || 1}
+      {disabled}
+      {readonly}
+      class="slider slider-min"
+    />
+    <input
+      type="range"
+      bind:value={currentMax}
+      min={minValue}
+      max={maxValue}
+      step={props.step || 1}
+      {disabled}
+      {readonly}
+      class="slider slider-max"
+    />
+  </div>
+  
+  <div class="range-display">
+    {props.prefix || ''}{currentMin} - {currentMax}{props.suffix || ''}
+  </div>
+</div>
+
+<style>
+  .range-slider-field {
+    display: flex;
+    flex-direction: column;
+    gap: 8px;
+  }
+  
+  .range-inputs {
+    display: flex;
+    align-items: center;
+    gap: 8px;
+  }
+  
+  .range-input {
+    width: 80px;
+    padding: 4px 8px;
+    border: 1px solid #ddd;
+    border-radius: 4px;
+  }
+  
+  .range-separator {
+    color: #666;
+  }
+  
+  .slider-container {
+    position: relative;
+    height: 20px;
+  }
+  
+  .slider {
+    position: absolute;
+    width: 100%;
+    height: 20px;
+    -webkit-appearance: none;
+    background: transparent;
+    outline: none;
+  }
+  
+  .slider::-webkit-slider-track {
+    height: 4px;
+    background: #ddd;
+    border-radius: 2px;
+  }
+  
+  .slider::-webkit-slider-thumb {
+    -webkit-appearance: none;
+    width: 16px;
+    height: 16px;
+    background: #007bff;
+    border-radius: 50%;
+    cursor: pointer;
+  }
+  
+  .range-display {
+    text-align: center;
+    font-weight: bold;
+    color: #333;
+  }
+  
+  .readonly, .disabled {
+    opacity: 0.6;
+    pointer-events: none;
+  }
+</style>
+```
+
+#### 2. 注册自定义字段类型
+
+```typescript
+import CriteriaComponentBuilder from '@ticatec/uniface-flexi-form/criteria-panel/lib/CriteriaComponentBuilder';
+import CustomRangeSliderField from './CustomRangeSliderField.svelte';
+
+// 创建构建器函数
+const buildRangeSliderField = (schema: FlexiCriteriaFieldSchema, dictLoader: DictionaryLoader) => {
+  return {
+    component: CustomRangeSliderField,
+    props: schema.props,
+    keyFields: schema.keys
+  };
+};
+
+// 注册自定义字段类型
+const componentBuilder = CriteriaComponentBuilder.getInstance();
+componentBuilder.register('range-slider', buildRangeSliderField);
+
+// 在 schema 中使用
+const schemaWithRangeSlider = {
+  arrangement: 'vertical',
+  fields: [
+    {
+      type: 'range-slider',
+      name: 'priceRange',
+      label: '价格范围',
+      keys: { 
+        minField: 'priceMin', 
+        maxField: 'priceMax' 
+      },
+      size: 'x30',
+      props: {
+        min: 0,
+        max: 1000,
+        step: 10,
+        prefix: '￥',
+        suffix: ' 元'
+      }
+    }
+  ]
+};
+```
+
+### 创建自定义搜索集合
+
+```typescript
+class AdvancedProductCriteriaSet extends FlexiCriteriaSet {
+  private productCategories: any[] = [];
+  private priceHistory: any[] = [];
+  
+  constructor(schema: FlexiCriteriaSetSchema) {
+    super(schema);
+    this.setupAdvancedFeatures();
+  }
+  
+  private async setupAdvancedFeatures(): Promise<void> {
+    await this.loadProductCategories();
+    await this.loadPriceHistory();
+    this.setupSmartDefaults();
+    this.setupAdvancedValidation();
+  }
+  
+  private async loadProductCategories(): Promise<void> {
+    try {
+      const response = await fetch('/api/products/categories/tree');
+      this.productCategories = await response.json();
+    } catch (error) {
+      console.error('加载产品分类失败:', error);
+    }
+  }
+  
+  private async loadPriceHistory(): Promise<void> {
+    try {
+      const response = await fetch('/api/products/price-history');
+      this.priceHistory = await response.json();
+    } catch (error) {
+      console.error('加载价格历史失败:', error);
+    }
+  }
+  
+  private setupSmartDefaults(): void {
+    // 根据用户历史或热门搜索设置智能默认值
+    const categoryField = this.field['category'];
+    const priceField = this.field['priceRange'];
+    
+    if (categoryField && this.productCategories.length > 0) {
+      // 设置最受欢迎的分类为默认值
+      const popularCategory = this.getMostPopularCategory();
+      categoryField.data = popularCategory?.id;
+    }
+    
+    if (priceField && this.priceHistory.length > 0) {
+      // 设置常见价格范围为默认值
+      const commonRange = this.getCommonPriceRange();
+      priceField.data = commonRange;
+    }
+  }
+  
+  private setupAdvancedValidation(): void {
+    // 添加跨字段验证
+    this.addValidator('priceRange', (value: any) => {
+      if (value.min > value.max) {
+        return '最小价格不能大于最大价格';
+      }
+      return null;
+    });
+    
+    this.addValidator('dateRange', (value: any) => {
+      if (new Date(value.from) > new Date(value.to)) {
+        return '开始日期不能晚于结束日期';
+      }
+      return null;
+    });
+  }
+  
+  private getMostPopularCategory(): any {
+    // 实现确定最受欢迎分类的逻辑
+    return this.productCategories[0];
+  }
+  
+  private getCommonPriceRange(): any {
+    // 实现确定常见价格范围的逻辑
+    return { min: 10, max: 100 };
+  }
+  
+  private addValidator(fieldName: string, validator: (value: any) => string | null): void {
+    const field = this.field[fieldName];
+    if (field) {
+      const originalChange = field.events.change;
+      field.events.change = (value: any) => {
+        const error = validator(value);
+        if (error) {
+          console.error(`${fieldName} 验证错误:`, error);
+          // 处理验证错误
+        } else {
+          originalChange?.(value);
+        }
+      };
+    }
+  }
+  
+  // 公共 API 方法
+  getCriteriaQuery(): any {
+    const criteria = {};
+    
+    for (const field of this.fields) {
+      if (field.data !== null && field.data !== undefined) {
+        // 将字段数据转换为查询格式
+        const queryPart = this.convertFieldToQuery(field);
+        Object.assign(criteria, queryPart);
+      }
+    }
+    
+    return criteria;
+  }
+  
+  private convertFieldToQuery(field: FlexiCriteriaField): any {
+    const query = {};
+    
+    switch (field.component.name) {
+      case 'TextSearchField':
+        query[field.keys.field] = {
+          operator: field.props.selectedOperator || 'contains',
+          value: field.data
+        };
+        break;
+        
+      case 'RangeSliderField':
+        if (field.data.min !== undefined) {
+          query[field.keys.minField] = {
+            operator: 'gte',
+            value: field.data.min
+          };
+        }
+        if (field.data.max !== undefined) {
+          query[field.keys.maxField] = {
+            operator: 'lte',
+            value: field.data.max
+          };
+        }
+        break;
+        
+      // 处理其他字段类型...
+    }
+    
+    return query;
+  }
+  
+  exportCriteria(): string {
+    return JSON.stringify(this.getCriteriaQuery(), null, 2);
+  }
+  
+  importCriteria(jsonString: string): void {
+    try {
+      const criteria = JSON.parse(jsonString);
+      this.applyCriteria(criteria);
+    } catch (error) {
+      console.error('导入搜索条件失败:', error);
+    }
+  }
+  
+  private applyCriteria(criteria: any): void {
+    // 将导入的条件应用到字段
+    for (const [key, value] of Object.entries(criteria)) {
+      const field = this.findFieldByKey(key);
+      if (field) {
+        field.data = value;
+      }
+    }
+    this.invalidate();
+  }
+  
+  private findFieldByKey(key: string): FlexiCriteriaField | null {
+    for (const field of this.fields) {
+      if (Object.values(field.keys).includes(key)) {
+        return field;
+      }
+    }
+    return null;
+  }
+}
+```
+
+## 集成模式
+
+### 与数据表集成
+
+```svelte
+<!-- ProductSearchAndTable.svelte -->
+<script lang="ts">
+  import CriteriaPanel from '@ticatec/uniface-flexi-form/criteria-panel';
+  import DataTable from '@ticatec/uniface-element/DataTable';
+  
+  let searchCriteria = {};
+  let tableData = [];
+  let loading = false;
+  let totalRecords = 0;
+  let currentPage = 1;
+  let pageSize = 20;
+  
+  const criteriaSchema = {
+    arrangement: 'horizontal',
+    fields: [
+      {
+        type: 'text-search',
+        name: 'name',
+        label: '产品名称',
+        keys: { field: 'name' },
+        size: 'x25'
+      },
+      {
+        type: 'option-select-search',
+        name: 'category',
+        label: '分类',
+        keys: { field: 'categoryId' },
+        dictName: 'categories',
+        size: 'x20'
+      },
+      {
+        type: 'number-range',
+        name: 'price',
+        label: '价格范围',
+        keys: { minField: 'priceMin', maxField: 'priceMax' },
+        size: 'x25'
+      }
+    ]
+  };
+  
+  const tableColumns = [
+    { field: 'name', text: '产品名称', width: 200 },
+    { field: 'category', text: '分类', width: 150 },
+    { field: 'price', text: '价格', width: 100, formatter: 'currency' },
+    { field: 'stock', text: '库存', width: 100 },
+    { field: 'status', text: '状态', width: 120 }
+  ];
+  
+  // 当搜索条件改变时响应式搜索
+  $: if (searchCriteria) {
+    performSearch();
+  }
+  
+  async function performSearch() {
+    loading = true;
+    try {
+      const queryParams = new URLSearchParams({
+        page: currentPage.toString(),
+        limit: pageSize.toString(),
+        ...flattenCriteria(searchCriteria)
+      });
+      
+      const response = await fetch(`/api/products/search?${queryParams}`);
+      const result = await response.json();
+      
+      tableData = result.data;
+      totalRecords = result.total;
+    } catch (error) {
+      console.error('搜索失败:', error);
+      tableData = [];
+    } finally {
+      loading = false;
+    }
+  }
+  
+  function flattenCriteria(criteria) {
+    const flattened = {};
+    for (const [key, value] of Object.entries(criteria)) {
+      if (value !== null && value !== undefined && value !== '') {
+        flattened[key] = value;
+      }
+    }
+    return flattened;
+  }
+  
+  function handlePageChange(event) {
+    currentPage = event.detail.page;
+    performSearch();
+  }
+  
+  function handleCriteriaChange(event) {
+    searchCriteria = event.detail.criteria;
+    currentPage = 1; // 新搜索时重置到第一页
+  }
+  
+  function handleReset() {
+    searchCriteria = {};
+    currentPage = 1;
+  }
+</script>
+
+<div class="search-and-table">
+  <div class="search-panel">
+    <h3>产品搜索</h3>
+    <CriteriaPanel 
+      schema={criteriaSchema}
+      bind:criteria={searchCriteria}
+      on:change={handleCriteriaChange}
+      on:reset={handleReset}
+    />
+  </div>
+  
+  <div class="results-panel">
+    <div class="results-header">
+      <h3>搜索结果 ({totalRecords} 项)</h3>
+      {#if loading}
+        <div class="loading">搜索中...</div>
+      {/if}
+    </div>
+    
+    <DataTable 
+      columns={tableColumns}
+      data={tableData}
+      {totalRecords}
+      {currentPage}
+      {pageSize}
+      on:pageChange={handlePageChange}
+    />
+  </div>
+</div>
+
+<style>
+  .search-and-table {
+    display: flex;
+    flex-direction: column;
+    gap: 20px;
+  }
+  
+  .search-panel {
+    background: #f8f9fa;
+    padding: 16px;
+    border-radius: 8px;
+    border: 1px solid #dee2e6;
+  }
+  
+  .results-panel {
+    flex: 1;
+  }
+  
+  .results-header {
+    display: flex;
+    justify-content: space-between;
+    align-items: center;
+    margin-bottom: 16px;
+  }
+  
+  .loading {
+    color: #6c757d;
+    font-style: italic;
+  }
+</style>
+```
+
+## 最佳实践
+
+### 1. Schema 组织
+
+```typescript
+// 好的：使用常量的有组织 schema
+const FIELD_SIZES = {
+  SMALL: 'x15',
+  MEDIUM: 'x25',
+  LARGE: 'x35',
+  FULL: 'x40'
+} as const;
+
+const COMMON_FIELDS = {
+  NAME_SEARCH: {
+    type: 'text-search',
+    keys: { field: 'name' },
+    size: FIELD_SIZES.MEDIUM,
+    props: {
+      placeholder: '请输入名称',
+      operators: ['contains', 'startsWith', 'equals']
+    }
+  },
+  
+  STATUS_SELECT: {
+    type: 'option-select-search',
+    keys: { field: 'status' },
+    dictName: 'status-options',
+    size: FIELD_SIZES.SMALL
+  }
+} as const;
+
+const PRODUCT_SEARCH_SCHEMA = {
+  arrangement: 'horizontal' as const,
+  variant: 'outlined' as const,
+  fields: [
+    {
+      ...COMMON_FIELDS.NAME_SEARCH,
+      name: 'productName',
+      label: '产品名称'
+    },
+    {
+      ...COMMON_FIELDS.STATUS_SELECT,
+      name: 'status',
+      label: '状态'
+    }
+  ]
+};
+```
+
+### 2. 性能优化
+
+```typescript
+// 针对实时过滤的防抖搜索
+class OptimizedCriteriaHandler {
+  private searchDebounceTime = 300;
+  private dictionaryCache = new Map();
+  
+  createDebouncedSearch(searchFunction: Function) {
+    let timeoutId: number;
+    
+    return (criteria: any) => {
+      clearTimeout(timeoutId);
+      timeoutId = setTimeout(() => {
+        searchFunction(criteria);
+      }, this.searchDebounceTime);
+    };
+  }
+  
+  async getCachedDictionary(dictName: string): Promise<any[]> {
+    if (this.dictionaryCache.has(dictName)) {
+      return this.dictionaryCache.get(dictName);
+    }
+    
+    const dictionary = await this.loadDictionary(dictName);
+    this.dictionaryCache.set(dictName, dictionary);
+    return dictionary;
+  }
+  
+  private async loadDictionary(dictName: string): Promise<any[]> {
+    const response = await fetch(`/api/dictionaries/${dictName}`);
+    return await response.json();
+  }
+}
+```
+
+### 3. 错误处理
+
+```typescript
+class CriteriaErrorHandler {
+  static handleCriteriaError(error: any, criteriaSet: FlexiCriteriaSet): void {
+    if (error.fieldErrors) {
+      this.displayFieldErrors(error.fieldErrors, criteriaSet);
+    } else if (error.networkError) {
+      this.displayNetworkError();
+    } else {
+      this.displayGenericError(error);
+    }
+  }
+  
+  private static displayFieldErrors(errors: Record<string, string>, criteriaSet: FlexiCriteriaSet): void {
+    for (const [fieldName, errorMessage] of Object.entries(errors)) {
+      const field = criteriaSet.field[fieldName];
+      if (field) {
+        // 在字段附近显示错误
+        console.error(`字段 ${fieldName}: ${errorMessage}`);
+      }
+    }
+  }
+  
+  private static displayNetworkError(): void {
+    console.error('搜索时发生网络错误');
+  }
+  
+  private static displayGenericError(error: any): void {
+    console.error('搜索错误:', error);
+  }
+}
+```
+
+### 4. 可访问性
+
+```typescript
+const accessibleCriteriaSchema = {
+  arrangement: 'vertical',
+  fields: [
+    {
+      type: 'text-editor',
+      name: 'search',
+      label: '搜索产品',
+      keys: { field: 'query' },
+      props: {
+        placeholder: '请输入搜索词',
+        'aria-label': '按名称或描述搜索产品',
+        'aria-describedby': 'search-help'
+      }
+    }
+  ]
+};
+
+// 添加帮助文本和 ARIA 属性
+const helpText = {
+  'search-help': '使用关键词搜索产品名称和描述'
+};
+```