@ticatec/uniface-flexi-module 0.0.2

package/FLEXIDATATABLE_GUIDE_CN.md

@@ -0,0 +1,1650 @@
+# FlexiDataTable 完整使用指南
+
+在 Svelte 应用中构建强大、灵活数据表的 FlexiDataTable 综合指南。
+
+## 目录
+
+1. [概述](#概述)
+2. [基础用法](#基础用法)
+3. [Schema 结构](#schema-结构)
+4. [列类型和功能](#列类型和功能)
+5. [高级表格功能](#高级表格功能)
+6. [动态数据处理](#动态数据处理)
+7. [事件和交互](#事件和交互)
+8. [扩展 FlexiDataTable](#扩展-flexidatatable)
+9. [集成模式](#集成模式)
+10. [最佳实践](#最佳实践)
+
+## 概述
+
+FlexiDataTable 是一个强大的数据表组件，提供灵活的列配置、排序、过滤、分页和广泛的自定义选项。它构建在 uniface-element DataTable 基础上，具有增强的基于 schema 的配置功能。
+
+### 主要特性
+
+- **基于 Schema 的配置**：通过 JSON 配置定义表格
+- **灵活的列类型**：数据列、指示列和操作列
+- **自定义格式化器**：内置和自定义单元格格式化器
+- **排序和过滤**：高级数据操作
+- **行操作**：可配置的行级操作
+- **响应式设计**：适应不同屏幕尺寸的自适应布局
+- **可扩展架构**：自定义渲染器和格式化器
+
+## 基础用法
+
+### 1. 安装和设置
+
+```typescript
+import FlexiDataTable from '@ticatec/uniface-flexi-form/flexi-datatable';
+import DataTable from '@ticatec/uniface-element/DataTable';
+import '@ticatec/uniface-flexi-form/uniface-flexi-form.css';
+```
+
+### 2. 简单数据表
+
+```svelte
+<!-- SimpleDataTable.svelte -->
+<script lang="ts">
+  import DataTable from '@ticatec/uniface-element/DataTable';
+  import FlexiDataTable from '@ticatec/uniface-flexi-form/flexi-datatable';
+  
+  // 示例数据
+  let tableData = [
+    { id: 1, name: '张三', email: 'zhang@example.com', age: 30, status: 'active' },
+    { id: 2, name: '李四', email: 'li@example.com', age: 25, status: 'active' },
+    { id: 3, name: '王五', email: 'wang@example.com', age: 35, status: 'inactive' }
+  ];
+  
+  // 表格配置
+  const tableSchema = {
+    round: true,
+    indicatorColumn: {
+      width: 60,
+      displayNo: true,
+      selectable: true
+    },
+    actionsColumn: {
+      width: 120,
+      align: 'center',
+      getActions: 'getRowActions'
+    },
+    columns: [
+      {
+        text: '姓名',
+        field: 'name',
+        width: 150,
+        align: 'left',
+        resizable: true
+      },
+      {
+        text: '邮箱',
+        field: 'email',
+        width: 200,
+        align: 'left',
+        resizable: true
+      },
+      {
+        text: '年龄',
+        field: 'age',
+        width: 80,
+        align: 'center',
+        formatter: 'formatAge'
+      },
+      {
+        text: '状态',
+        field: 'status',
+        width: 100,
+        align: 'center',
+        formatter: 'formatStatus'
+      }
+    ]
+  };
+  
+  // 创建 FlexiDataTable 实例
+  class UserDataTable extends FlexiDataTable {
+    constructor(schema) {
+      super(schema);
+    }
+    
+    formatAge(value, row) {
+      return `${value} 岁`;
+    }
+    
+    formatStatus(value, row) {
+      const statusClass = value === 'active' ? 'status-active' : 'status-inactive';
+      return `<span class="${statusClass}">${value === 'active' ? '激活' : '未激活'}</span>`;
+    }
+    
+    getRowActions(row) {
+      return [
+        {
+          text: '编辑',
+          icon: 'edit',
+          handler: () => this.editUser(row)
+        },
+        {
+          text: '删除',
+          icon: 'delete',
+          handler: () => this.deleteUser(row),
+          confirm: '确定要删除这个用户吗？'
+        }
+      ];
+    }
+    
+    editUser(row) {
+      console.log('编辑用户:', row);
+    }
+    
+    deleteUser(row) {
+      console.log('删除用户:', row);
+    }
+  }
+  
+  let dataTable = new UserDataTable(tableSchema);
+  
+  onMount(async () => {
+    await dataTable.initialize();
+  });
+  
+  function handleRowSelect(event) {
+    console.log('选中的行:', event.detail.selectedRows);
+  }
+  
+  function handleSort(event) {
+    console.log('排序改变:', event.detail);
+  }
+</script>
+
+<div class="data-table-container">
+  <DataTable 
+    columns={dataTable.columns}
+    data={tableData}
+    indicatorColumn={dataTable.indicatorColumn}
+    actionsColumn={dataTable.actionsColumn}
+    round={dataTable.round}
+    on:rowSelect={handleRowSelect}
+    on:sort={handleSort}
+  />
+</div>
+
+<style>
+  .data-table-container {
+    padding: 16px;
+  }
+  
+  :global(.status-active) {
+    color: #28a745;
+    font-weight: bold;
+  }
+  
+  :global(.status-inactive) {
+    color: #dc3545;
+    font-weight: bold;
+  }
+</style>
+```
+
+## Schema 结构
+
+### FlexiDataTableSchema
+
+```typescript
+interface FlexiDataTableSchema {
+  round?: boolean;                    // 圆角边框
+  indicatorColumn: IndicatorColumnSchema; // 行号/选择
+  actionsColumn?: ActionsColumnSchema;    // 行操作
+  columns: Array<FlexiDataTableColumnSchema>; // 数据列
+}
+```
+
+### FlexiDataTableColumnSchema
+
+```typescript
+interface FlexiDataTableColumnSchema {
+  text: string;                       // 列标题文本
+  field?: string;                     // 数据字段名
+  frozen?: boolean;                   // 冻结列
+  align?: 'left' | 'center' | 'right'; // 文本对齐
+  width: number;                      // 列宽度
+  minWidth?: number;                  // 最小宽度
+  warp?: boolean;                     // 文本换行
+  formatter?: string;                 // 格式化器函数名
+  escapeHTML?: boolean;               // HTML转义
+  href?: string;                      // 链接函数名
+  hint?: string;                      // 提示函数名
+  render?: string;                    // 自定义渲染器名
+  visible?: boolean;                  // 列可见性
+  resizable?: boolean;                // 列大小调整
+  compareFunction?: string;           // 自定义排序函数名
+}
+```
+
+### IndicatorColumnSchema
+
+```typescript
+interface IndicatorColumnSchema {
+  width: number;                      // 列宽度
+  displayNo?: boolean;                // 显示行号
+  selectable?: boolean;               // 行选择
+}
+```
+
+### ActionsColumnSchema
+
+```typescript
+interface ActionsColumnSchema {
+  width: number;                      // 列宽度
+  align?: 'left' | 'center';         // 对齐方式
+  getActions: string;                 // 操作提供者函数名
+}
+```
+
+## 列类型和功能
+
+### 数据列
+
+```typescript
+// 基础数据列
+{
+  text: '产品名称',
+  field: 'name',
+  width: 200,
+  align: 'left',
+  resizable: true
+}
+
+// 格式化列
+{
+  text: '价格',
+  field: 'price',
+  width: 100,
+  align: 'right',
+  formatter: 'formatCurrency'
+}
+
+// 链接列
+{
+  text: '网站',
+  field: 'website',
+  width: 150,
+  href: 'buildWebsiteLink'
+}
+
+// 自定义渲染列
+{
+  text: '状态',
+  field: 'status',
+  width: 120,
+  render: 'renderStatusBadge'
+}
+```
+
+### 带实现的列示例
+
+```typescript
+class ProductDataTable extends FlexiDataTable {
+  constructor(schema: FlexiDataTableSchema) {
+    super(schema);
+  }
+  
+  // 货币格式化器
+  formatCurrency(value: number, row: any): string {
+    return new Intl.NumberFormat('zh-CN', {
+      style: 'currency',
+      currency: 'CNY'
+    }).format(value);
+  }
+  
+  // 日期格式化器
+  formatDate(value: string, row: any): string {
+    return new Date(value).toLocaleDateString('zh-CN');
+  }
+  
+  // 百分比格式化器
+  formatPercentage(value: number, row: any): string {
+    return `${(value * 100).toFixed(1)}%`;
+  }
+  
+  // 文件大小格式化器
+  formatFileSize(bytes: number, row: any): string {
+    const sizes = ['B', 'KB', 'MB', 'GB'];
+    if (bytes === 0) return '0 B';
+    const i = Math.floor(Math.log(bytes) / Math.log(1024));
+    return `${(bytes / Math.pow(1024, i)).toFixed(1)} ${sizes[i]}`;
+  }
+  
+  // 链接构建器
+  buildWebsiteLink(value: string, row: any): string {
+    return value.startsWith('http') ? value : `https://${value}`;
+  }
+  
+  // 产品链接构建器
+  buildProductLink(value: string, row: any): string {
+    return `/products/${row.id}`;
+  }
+  
+  // 提示提供者
+  getProductHint(value: string, row: any): string {
+    return `产品ID: ${row.id}\\n分类: ${row.category}\\n库存: ${row.stock}`;
+  }
+  
+  // 状态徽章渲染器
+  renderStatusBadge(value: string, row: any): any {
+    // 返回 Svelte 组件配置
+    return {
+      component: StatusBadge,
+      props: {
+        status: value,
+        size: 'small'
+      }
+    };
+  }
+  
+  // 图片渲染器
+  renderProductImage(value: string, row: any): any {
+    return {
+      component: ProductImage,
+      props: {
+        src: value,
+        alt: row.name,
+        size: 'thumbnail'
+      }
+    };
+  }
+  
+  // 自定义排序函数
+  compareProductNames(a: any, b: any): number {
+    // 产品名称的自定义排序逻辑
+    const nameA = a.name.toLowerCase();
+    const nameB = b.name.toLowerCase();
+    return this.compareStrings(nameA, nameB, { ignoreCase: true });
+  }
+  
+  // 带空值处理的数字排序
+  compareStock(a: any, b: any): number {
+    const stockA = a.stock || 0;
+    const stockB = b.stock || 0;
+    return stockA - stockB;
+  }
+  
+  // 行操作
+  getRowActions(row: any): any[] {
+    const actions = [
+      {
+        text: '查看',
+        icon: 'eye',
+        handler: () => this.viewProduct(row)
+      }
+    ];
+    
+    if (row.status === 'active') {
+      actions.push({
+        text: '编辑',
+        icon: 'edit',
+        handler: () => this.editProduct(row)
+      });
+    }
+    
+    if (row.stock === 0) {
+      actions.push({
+        text: '补货',
+        icon: 'plus',
+        handler: () => this.restockProduct(row)
+      });
+    }
+    
+    actions.push({
+      text: '删除',
+      icon: 'trash',
+      handler: () => this.deleteProduct(row),
+      confirm: '确定要删除这个产品吗？',
+      style: 'danger'
+    });
+    
+    return actions;
+  }
+  
+  viewProduct(row: any): void {
+    window.open(`/products/${row.id}`, '_blank');
+  }
+  
+  editProduct(row: any): void {
+    // 导航到编辑页面或打开模态框
+    console.log('编辑产品:', row);
+  }
+  
+  restockProduct(row: any): void {
+    // 打开补货对话框
+    console.log('补货产品:', row);
+  }
+  
+  deleteProduct(row: any): void {
+    // 执行删除操作
+    console.log('删除产品:', row);
+  }
+}
+```
+
+## 高级表格功能
+
+### 冻结列
+
+```typescript
+const tableSchemaWithFrozenColumns = {
+  round: true,
+  indicatorColumn: {
+    width: 60,
+    displayNo: true,
+    selectable: true
+  },
+  columns: [
+    {
+      text: 'ID',
+      field: 'id',
+      width: 80,
+      frozen: true,  // 此列保持固定
+      align: 'center'
+    },
+    {
+      text: '名称',
+      field: 'name',
+      width: 150,
+      frozen: true,  // 此列也保持固定
+      align: 'left'
+    },
+    {
+      text: '描述',
+      field: 'description',
+      width: 300,
+      align: 'left',
+      warp: true     // 允许文本换行
+    },
+    {
+      text: '价格',
+      field: 'price',
+      width: 100,
+      align: 'right',
+      formatter: 'formatCurrency'
+    }
+  ]
+};
+```
+
+### 条件列可见性
+
+```typescript
+class ConditionalColumnsTable extends FlexiDataTable {
+  private userRole: string;
+  
+  constructor(schema: FlexiDataTableSchema, userRole: string) {
+    super(schema);
+    this.userRole = userRole;
+  }
+  
+  async initialize(): Promise<void> {
+    // 在初始化之前根据用户角色修改 schema
+    this.applyRoleBasedVisibility();
+    await super.initialize();
+  }
+  
+  private applyRoleBasedVisibility(): void {
+    this.schema.columns.forEach(column => {
+      switch (column.field) {
+        case 'salary':
+          column.visible = this.userRole === 'admin' || this.userRole === 'hr';
+          break;
+        case 'ssn':
+          column.visible = this.userRole === 'admin';
+          break;
+        case 'internalNotes':
+          column.visible = this.userRole !== 'guest';
+          break;
+        default:
+          column.visible = column.visible !== false;
+      }
+    });
+  }
+}
+```
+
+### 动态列配置
+
+```typescript
+class DynamicColumnsTable extends FlexiDataTable {
+  constructor(schema: FlexiDataTableSchema) {
+    super(schema);
+  }
+  
+  updateColumnConfiguration(newConfig: any): void {
+    // 更新列宽度
+    if (newConfig.columnWidths) {
+      this.columns.forEach((column, index) => {
+        if (newConfig.columnWidths[index]) {
+          column.width = newConfig.columnWidths[index];
+        }
+      });
+    }
+    
+    // 更新列可见性
+    if (newConfig.visibleColumns) {
+      this.columns.forEach((column, index) => {
+        column.visible = newConfig.visibleColumns.includes(index);
+      });
+    }
+    
+    // 更新列顺序
+    if (newConfig.columnOrder) {
+      const reorderedColumns = newConfig.columnOrder.map(index => this.columns[index]);
+      this.#columns = reorderedColumns;
+    }
+  }
+  
+  getColumnConfiguration(): any {
+    return {
+      columnWidths: this.columns.map(col => col.width),
+      visibleColumns: this.columns
+        .map((col, index) => col.visible !== false ? index : null)
+        .filter(index => index !== null),
+      columnOrder: this.columns.map((_, index) => index)
+    };
+  }
+  
+  saveColumnConfiguration(): void {
+    const config = this.getColumnConfiguration();
+    localStorage.setItem('table-config', JSON.stringify(config));
+  }
+  
+  loadColumnConfiguration(): void {
+    try {
+      const config = JSON.parse(localStorage.getItem('table-config') || '{}');
+      this.updateColumnConfiguration(config);
+    } catch (error) {
+      console.error('加载列配置失败:', error);
+    }
+  }
+}
+```
+
+## 动态数据处理
+
+### 分页数据加载
+
+```typescript
+class PaginatedDataTable extends FlexiDataTable {
+  private currentPage = 1;
+  private pageSize = 20;
+  private totalRecords = 0;
+  private loading = false;
+  private searchCriteria: any = {};
+  
+  constructor(schema: FlexiDataTableSchema) {
+    super(schema);
+  }
+  
+  async loadData(page: number = 1, criteria: any = {}): Promise<any[]> {
+    this.loading = true;
+    this.currentPage = page;
+    this.searchCriteria = criteria;
+    
+    try {
+      const queryParams = new URLSearchParams({
+        page: page.toString(),
+        limit: this.pageSize.toString(),
+        ...this.flattenCriteria(criteria)
+      });
+      
+      const response = await fetch(`/api/data?${queryParams}`);
+      const result = await response.json();
+      
+      this.totalRecords = result.total;
+      return result.data;
+    } catch (error) {
+      console.error('加载数据失败:', error);
+      return [];
+    } finally {
+      this.loading = false;
+    }
+  }
+  
+  async refreshData(): Promise<any[]> {
+    return this.loadData(this.currentPage, this.searchCriteria);
+  }
+  
+  async nextPage(): Promise<any[]> {
+    if (this.hasNextPage()) {
+      return this.loadData(this.currentPage + 1, this.searchCriteria);
+    }
+    return [];
+  }
+  
+  async previousPage(): Promise<any[]> {
+    if (this.hasPreviousPage()) {
+      return this.loadData(this.currentPage - 1, this.searchCriteria);
+    }
+    return [];
+  }
+  
+  hasNextPage(): boolean {
+    return this.currentPage * this.pageSize < this.totalRecords;
+  }
+  
+  hasPreviousPage(): boolean {
+    return this.currentPage > 1;
+  }
+  
+  getCurrentPageInfo(): any {
+    const startRecord = (this.currentPage - 1) * this.pageSize + 1;
+    const endRecord = Math.min(this.currentPage * this.pageSize, this.totalRecords);
+    
+    return {
+      currentPage: this.currentPage,
+      pageSize: this.pageSize,
+      totalRecords: this.totalRecords,
+      totalPages: Math.ceil(this.totalRecords / this.pageSize),
+      startRecord,
+      endRecord,
+      loading: this.loading
+    };
+  }
+  
+  private flattenCriteria(criteria: any): Record<string, string> {
+    const flattened: Record<string, string> = {};
+    for (const [key, value] of Object.entries(criteria)) {
+      if (value !== null && value !== undefined && value !== '') {
+        flattened[key] = String(value);
+      }
+    }
+    return flattened;
+  }
+}
+```
+
+### 实时数据更新
+
+```typescript
+class RealtimeDataTable extends FlexiDataTable {
+  private websocket: WebSocket | null = null;
+  private updateCallback: ((data: any[]) => void) | null = null;
+  
+  constructor(schema: FlexiDataTableSchema) {
+    super(schema);
+  }
+  
+  connectRealtime(wsUrl: string, onUpdate: (data: any[]) => void): void {
+    this.updateCallback = onUpdate;
+    this.websocket = new WebSocket(wsUrl);
+    
+    this.websocket.onopen = () => {
+      console.log('WebSocket 已连接');
+    };
+    
+    this.websocket.onmessage = (event) => {
+      try {
+        const message = JSON.parse(event.data);
+        this.handleRealtimeUpdate(message);
+      } catch (error) {
+        console.error('解析 WebSocket 消息失败:', error);
+      }
+    };
+    
+    this.websocket.onclose = () => {
+      console.log('WebSocket 已断开');
+      // 尝试重新连接
+      setTimeout(() => this.connectRealtime(wsUrl, onUpdate), 5000);
+    };
+    
+    this.websocket.onerror = (error) => {
+      console.error('WebSocket 错误:', error);
+    };
+  }
+  
+  private handleRealtimeUpdate(message: any): void {
+    switch (message.type) {
+      case 'data_updated':
+        this.updateCallback?.(message.data);
+        break;
+      case 'record_added':
+        this.handleRecordAdded(message.record);
+        break;
+      case 'record_updated':
+        this.handleRecordUpdated(message.record);
+        break;
+      case 'record_deleted':
+        this.handleRecordDeleted(message.recordId);
+        break;
+    }
+  }
+  
+  private handleRecordAdded(record: any): void {
+    // 将记录添加到当前数据并通知
+    console.log('新记录添加:', record);
+  }
+  
+  private handleRecordUpdated(record: any): void {
+    // 更新现有记录并通知
+    console.log('记录更新:', record);
+  }
+  
+  private handleRecordDeleted(recordId: string): void {
+    // 从当前数据中移除记录并通知
+    console.log('记录删除:', recordId);
+  }
+  
+  disconnect(): void {
+    if (this.websocket) {
+      this.websocket.close();
+      this.websocket = null;
+    }
+  }
+}
+```
+
+## 事件和交互
+
+### 表格事件
+
+```svelte
+<script>
+  function handleRowSelect(event) {
+    const { selectedRows, isAllSelected } = event.detail;
+    console.log('选中的行:', selectedRows);
+    console.log('全部选中:', isAllSelected);
+  }
+  
+  function handleRowClick(event) {
+    const { row, rowIndex } = event.detail;
+    console.log('点击的行:', row, '索引:', rowIndex);
+  }
+  
+  function handleRowDoubleClick(event) {
+    const { row, rowIndex } = event.detail;
+    console.log('双击的行:', row);
+    // 打开编辑对话框或导航到详情视图
+    openEditDialog(row);
+  }
+  
+  function handleSort(event) {
+    const { column, direction } = event.detail;
+    console.log('排序改变:', column.field, direction);
+    
+    // 执行排序
+    if (direction === 'asc') {
+      tableData.sort((a, b) => a[column.field] > b[column.field] ? 1 : -1);
+    } else if (direction === 'desc') {
+      tableData.sort((a, b) => a[column.field] < b[column.field] ? 1 : -1);
+    }
+    
+    // 触发响应性
+    tableData = [...tableData];
+  }
+  
+  function handleColumnResize(event) {
+    const { column, newWidth } = event.detail;
+    console.log('列调整大小:', column.field, '新宽度:', newWidth);
+    
+    // 保存列配置
+    dataTable.saveColumnConfiguration();
+  }
+  
+  function handlePageChange(event) {
+    const { page, pageSize } = event.detail;
+    console.log('页面改变:', page, '大小:', pageSize);
+    
+    // 加载新页面数据
+    loadPageData(page, pageSize);
+  }
+</script>
+
+<DataTable 
+  columns={dataTable.columns}
+  data={tableData}
+  indicatorColumn={dataTable.indicatorColumn}
+  actionsColumn={dataTable.actionsColumn}
+  on:rowSelect={handleRowSelect}
+  on:rowClick={handleRowClick}
+  on:rowDoubleClick={handleRowDoubleClick}
+  on:sort={handleSort}
+  on:columnResize={handleColumnResize}
+  on:pageChange={handlePageChange}
+/>
+```
+
+### 批量操作
+
+```typescript
+class BulkOperationsTable extends FlexiDataTable {
+  private selectedRows: Set<any> = new Set();
+  
+  constructor(schema: FlexiDataTableSchema) {
+    super(schema);
+  }
+  
+  handleRowSelection(selectedRows: any[]): void {
+    this.selectedRows = new Set(selectedRows);
+  }
+  
+  getBulkActions(): any[] {
+    if (this.selectedRows.size === 0) {
+      return [];
+    }
+    
+    return [
+      {
+        text: `删除 ${this.selectedRows.size} 项`,
+        icon: 'trash',
+        handler: () => this.bulkDelete(),
+        confirm: `确定要删除 ${this.selectedRows.size} 项吗？`,
+        style: 'danger'
+      },
+      {
+        text: `导出 ${this.selectedRows.size} 项`,
+        icon: 'download',
+        handler: () => this.bulkExport()
+      },
+      {
+        text: '更新状态',
+        icon: 'edit',
+        handler: () => this.bulkUpdateStatus()
+      }
+    ];
+  }
+  
+  async bulkDelete(): Promise<void> {
+    try {
+      const ids = Array.from(this.selectedRows).map(row => row.id);
+      await fetch('/api/bulk/delete', {
+        method: 'POST',
+        headers: { 'Content-Type': 'application/json' },
+        body: JSON.stringify({ ids })
+      });
+      
+      console.log('批量删除成功');
+      this.selectedRows.clear();
+    } catch (error) {
+      console.error('批量删除失败:', error);
+    }
+  }
+  
+  async bulkExport(): Promise<void> {
+    try {
+      const data = Array.from(this.selectedRows);
+      const csv = this.convertToCSV(data);
+      this.downloadCSV(csv, 'export.csv');
+    } catch (error) {
+      console.error('批量导出失败:', error);
+    }
+  }
+  
+  async bulkUpdateStatus(): Promise<void> {
+    const newStatus = prompt('请输入新状态:');
+    if (!newStatus) return;
+    
+    try {
+      const ids = Array.from(this.selectedRows).map(row => row.id);
+      await fetch('/api/bulk/update-status', {
+        method: 'POST',
+        headers: { 'Content-Type': 'application/json' },
+        body: JSON.stringify({ ids, status: newStatus })
+      });
+      
+      console.log('批量状态更新成功');
+    } catch (error) {
+      console.error('批量状态更新失败:', error);
+    }
+  }
+  
+  private convertToCSV(data: any[]): string {
+    if (data.length === 0) return '';
+    
+    const headers = Object.keys(data[0]);
+    const csvContent = [
+      headers.join(','),
+      ...data.map(row => headers.map(header => `"${row[header]}"`).join(','))
+    ].join('\\n');
+    
+    return csvContent;
+  }
+  
+  private downloadCSV(csv: string, filename: string): void {
+    const blob = new Blob([csv], { type: 'text/csv' });
+    const url = window.URL.createObjectURL(blob);
+    const link = document.createElement('a');
+    link.href = url;
+    link.download = filename;
+    link.click();
+    window.URL.revokeObjectURL(url);
+  }
+}
+```
+
+## 扩展 FlexiDataTable
+
+### 自定义单元格渲染器
+
+```svelte
+<!-- StatusBadge.svelte -->
+<script lang="ts">
+  export let status: string;
+  export let size: 'small' | 'medium' | 'large' = 'medium';
+  
+  $: statusConfig = getStatusConfig(status);
+  
+  function getStatusConfig(status: string) {
+    const configs = {
+      active: { color: '#28a745', background: '#d4edda', text: '激活' },
+      inactive: { color: '#6c757d', background: '#e2e3e5', text: '未激活' },
+      pending: { color: '#ffc107', background: '#fff3cd', text: '待处理' },
+      error: { color: '#dc3545', background: '#f8d7da', text: '错误' }
+    };
+    return configs[status] || configs.inactive;
+  }
+</script>
+
+<span 
+  class="status-badge {size}"
+  style="color: {statusConfig.color}; background-color: {statusConfig.background};"
+>
+  {statusConfig.text}
+</span>
+
+<style>
+  .status-badge {
+    display: inline-block;
+    padding: 4px 8px;
+    border-radius: 12px;
+    font-weight: 600;
+    text-align: center;
+    white-space: nowrap;
+  }
+  
+  .status-badge.small {
+    font-size: 0.75rem;
+    padding: 2px 6px;
+  }
+  
+  .status-badge.medium {
+    font-size: 0.875rem;
+    padding: 4px 8px;
+  }
+  
+  .status-badge.large {
+    font-size: 1rem;
+    padding: 6px 12px;
+  }
+</style>
+```
+
+```svelte
+<!-- ProgressBar.svelte -->
+<script lang="ts">
+  export let value: number;
+  export let max: number = 100;
+  export let color: string = '#007bff';
+  export let showText: boolean = true;
+  
+  $: percentage = Math.round((value / max) * 100);
+</script>
+
+<div class="progress-container">
+  <div class="progress-bar">
+    <div 
+      class="progress-fill"
+      style="width: {percentage}%; background-color: {color};"
+    ></div>
+  </div>
+  {#if showText}
+    <span class="progress-text">{percentage}%</span>
+  {/if}
+</div>
+
+<style>
+  .progress-container {
+    display: flex;
+    align-items: center;
+    gap: 8px;
+    width: 100%;
+  }
+  
+  .progress-bar {
+    flex: 1;
+    height: 8px;
+    background-color: #e9ecef;
+    border-radius: 4px;
+    overflow: hidden;
+  }
+  
+  .progress-fill {
+    height: 100%;
+    transition: width 0.3s ease;
+  }
+  
+  .progress-text {
+    font-size: 0.75rem;
+    color: #6c757d;
+    min-width: 35px;
+  }
+</style>
+```
+
+### 自定义表格类
+
+```typescript
+class AdvancedProductTable extends FlexiDataTable {
+  private productCategories: any[] = [];
+  private userPermissions: string[] = [];
+  
+  constructor(schema: FlexiDataTableSchema, userPermissions: string[]) {
+    super(schema);
+    this.userPermissions = userPermissions;
+  }
+  
+  async initialize(): Promise<void> {
+    await this.loadProductCategories();
+    this.setupPermissionBasedActions();
+    await super.initialize();
+  }
+  
+  private async loadProductCategories(): Promise<void> {
+    try {
+      const response = await fetch('/api/product-categories');
+      this.productCategories = await response.json();
+    } catch (error) {
+      console.error('加载产品分类失败:', error);
+    }
+  }
+  
+  private setupPermissionBasedActions(): void {
+    // 根据用户权限修改 schema
+    if (!this.userPermissions.includes('edit_products')) {
+      // 移除编辑相关的列或操作
+      this.schema.columns = this.schema.columns.filter(col => 
+        col.field !== 'editActions'
+      );
+    }
+  }
+  
+  // 高级格式化器
+  formatProductCategory(categoryId: string, row: any): string {
+    const category = this.productCategories.find(cat => cat.id === categoryId);
+    return category ? category.name : '未知分类';
+  }
+  
+  formatInventoryStatus(stock: number, row: any): string {
+    if (stock === 0) {
+      return '<span class="text-danger">缺货</span>';
+    } else if (stock < row.minimumStock) {
+      return '<span class="text-warning">库存不足</span>';
+    } else {
+      return '<span class="text-success">有库存</span>';
+    }
+  }
+  
+  formatPriceWithDiscount(price: number, row: any): string {
+    if (row.discount > 0) {
+      const discountedPrice = price * (1 - row.discount);
+      return `
+        <span class="original-price">￥${price.toFixed(2)}</span>
+        <span class="discounted-price">￥${discountedPrice.toFixed(2)}</span>
+      `;
+    }
+    return `￥${price.toFixed(2)}`;
+  }
+  
+  // 高级渲染器
+  renderProductImage(imageUrl: string, row: any): any {
+    return {
+      component: ProductImage,
+      props: {
+        src: imageUrl,
+        alt: row.name,
+        size: 'thumbnail',
+        lazy: true,
+        fallback: '/images/product-placeholder.png'
+      }
+    };
+  }
+  
+  renderStockLevel(stock: number, row: any): any {
+    const percentage = Math.min((stock / row.maximumStock) * 100, 100);
+    let color = '#28a745'; // 绿色
+    
+    if (percentage < 20) {
+      color = '#dc3545'; // 红色
+    } else if (percentage < 50) {
+      color = '#ffc107'; // 黄色
+    }
+    
+    return {
+      component: ProgressBar,
+      props: {
+        value: stock,
+        max: row.maximumStock,
+        color,
+        showText: true
+      }
+    };
+  }
+  
+  renderRating(rating: number, row: any): any {
+    return {
+      component: StarRating,
+      props: {
+        rating,
+        maxRating: 5,
+        readonly: true,
+        size: 'small'
+      }
+    };
+  }
+  
+  // 高级操作
+  getRowActions(row: any): any[] {
+    const actions = [];
+    
+    // 始终可用的操作
+    actions.push({
+      text: '查看详情',
+      icon: 'eye',
+      handler: () => this.viewProductDetails(row)
+    });
+    
+    // 基于权限的操作
+    if (this.userPermissions.includes('edit_products')) {
+      actions.push({
+        text: '编辑',
+        icon: 'edit',
+        handler: () => this.editProduct(row)
+      });
+    }
+    
+    if (this.userPermissions.includes('manage_inventory')) {
+      if (row.stock === 0) {
+        actions.push({
+          text: '补货',
+          icon: 'plus-circle',
+          handler: () => this.restockProduct(row)
+        });
+      }
+      
+      actions.push({
+        text: '调整库存',
+        icon: 'warehouse',
+        handler: () => this.adjustStock(row)
+      });
+    }
+    
+    if (this.userPermissions.includes('delete_products')) {
+      actions.push({
+        text: '删除',
+        icon: 'trash',
+        handler: () => this.deleteProduct(row),
+        confirm: '确定要删除这个产品吗？',
+        style: 'danger'
+      });
+    }
+    
+    return actions;
+  }
+  
+  // 操作实现
+  viewProductDetails(row: any): void {
+    window.open(`/products/${row.id}`, '_blank');
+  }
+  
+  editProduct(row: any): void {
+    // 打开编辑模态框或导航到编辑页面
+    const editEvent = new CustomEvent('edit-product', { detail: row });
+    document.dispatchEvent(editEvent);
+  }
+  
+  restockProduct(row: any): void {
+    // 打开补货对话框
+    const restockEvent = new CustomEvent('restock-product', { detail: row });
+    document.dispatchEvent(restockEvent);
+  }
+  
+  adjustStock(row: any): void {
+    // 打开库存调整对话框
+    const adjustEvent = new CustomEvent('adjust-stock', { detail: row });
+    document.dispatchEvent(adjustEvent);
+  }
+  
+  deleteProduct(row: any): void {
+    // 执行删除操作
+    fetch(`/api/products/${row.id}`, { method: 'DELETE' })
+      .then(() => {
+        const deleteEvent = new CustomEvent('product-deleted', { detail: row });
+        document.dispatchEvent(deleteEvent);
+      })
+      .catch(error => {
+        console.error('删除失败:', error);
+      });
+  }
+  
+  // 高级排序
+  compareProductNames(a: any, b: any): number {
+    return this.compareStrings(a.name, b.name, { ignoreCase: true });
+  }
+  
+  compareByCategory(a: any, b: any): number {
+    const catA = this.formatProductCategory(a.categoryId, a);
+    const catB = this.formatProductCategory(b.categoryId, b);
+    return this.compareStrings(catA, catB);
+  }
+  
+  compareByStockLevel(a: any, b: any): number {
+    const levelA = a.stock / a.maximumStock;
+    const levelB = b.stock / b.maximumStock;
+    return levelA - levelB;
+  }
+}
+```
+
+## 集成模式
+
+### 与搜索集成的表格
+
+```svelte
+<!-- ProductManagement.svelte -->
+<script lang="ts">
+  import CriteriaPanel from '@ticatec/uniface-flexi-form/criteria-panel';
+  import DataTable from '@ticatec/uniface-element/DataTable';
+  import { AdvancedProductTable } from './AdvancedProductTable';
+  
+  let searchCriteria = {};
+  let tableData = [];
+  let totalRecords = 0;
+  let currentPage = 1;
+  let pageSize = 20;
+  let loading = false;
+  
+  const searchSchema = {
+    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'
+      },
+      {
+        type: 'option-select-search',
+        name: 'status',
+        label: '状态',
+        keys: { field: 'status' },
+        dictName: 'product-status',
+        size: 'x15'
+      }
+    ]
+  };
+  
+  const tableSchema = {
+    round: true,
+    indicatorColumn: {
+      width: 60,
+      displayNo: true,
+      selectable: true
+    },
+    actionsColumn: {
+      width: 150,
+      align: 'center',
+      getActions: 'getRowActions'
+    },
+    columns: [
+      {
+        text: '图片',
+        field: 'imageUrl',
+        width: 80,
+        align: 'center',
+        render: 'renderProductImage'
+      },
+      {
+        text: '名称',
+        field: 'name',
+        width: 200,
+        align: 'left',
+        resizable: true,
+        compareFunction: 'compareProductNames'
+      },
+      {
+        text: '分类',
+        field: 'categoryId',
+        width: 150,
+        formatter: 'formatProductCategory',
+        compareFunction: 'compareByCategory'
+      },
+      {
+        text: '价格',
+        field: 'price',
+        width: 120,
+        align: 'right',
+        formatter: 'formatPriceWithDiscount'
+      },
+      {
+        text: '库存',
+        field: 'stock',
+        width: 100,
+        align: 'center',
+        render: 'renderStockLevel',
+        compareFunction: 'compareByStockLevel'
+      },
+      {
+        text: '评分',
+        field: 'rating',
+        width: 120,
+        align: 'center',
+        render: 'renderRating'
+      },
+      {
+        text: '状态',
+        field: 'status',
+        width: 100,
+        align: 'center',
+        formatter: 'formatInventoryStatus'
+      }
+    ]
+  };
+  
+  let productTable = new AdvancedProductTable(tableSchema, ['edit_products', 'manage_inventory']);
+  
+  onMount(async () => {
+    await productTable.initialize();
+    await loadData();
+  });
+  
+  async function loadData() {
+    loading = true;
+    try {
+      const queryParams = new URLSearchParams({
+        page: currentPage.toString(),
+        limit: pageSize.toString(),
+        ...flattenCriteria(searchCriteria)
+      });
+      
+      const response = await fetch(`/api/products?${queryParams}`);
+      const result = await response.json();
+      
+      tableData = result.data;
+      totalRecords = result.total;
+    } catch (error) {
+      console.error('加载产品失败:', error);
+    } 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 handleCriteriaChange(event) {
+    searchCriteria = event.detail.criteria;
+    currentPage = 1;
+    loadData();
+  }
+  
+  function handlePageChange(event) {
+    currentPage = event.detail.page;
+    pageSize = event.detail.pageSize;
+    loadData();
+  }
+  
+  function handleSort(event) {
+    console.log('排序:', event.detail);
+    loadData();
+  }
+  
+  // 监听表格操作的自定义事件
+  onMount(() => {
+    document.addEventListener('edit-product', handleEditProduct);
+    document.addEventListener('restock-product', handleRestockProduct);
+    document.addEventListener('product-deleted', handleProductDeleted);
+    
+    return () => {
+      document.removeEventListener('edit-product', handleEditProduct);
+      document.removeEventListener('restock-product', handleRestockProduct);
+      document.removeEventListener('product-deleted', handleProductDeleted);
+    };
+  });
+  
+  function handleEditProduct(event) {
+    console.log('编辑产品:', event.detail);
+    // 打开编辑模态框或导航到编辑页面
+  }
+  
+  function handleRestockProduct(event) {
+    console.log('补货产品:', event.detail);
+    // 打开补货模态框
+  }
+  
+  function handleProductDeleted(event) {
+    console.log('产品已删除:', event.detail);
+    // 刷新表格数据
+    loadData();
+  }
+</script>
+
+<div class="product-management">
+  <div class="search-section">
+    <h3>产品搜索</h3>
+    <CriteriaPanel 
+      schema={searchSchema}
+      bind:criteria={searchCriteria}
+      on:change={handleCriteriaChange}
+    />
+  </div>
+  
+  <div class="table-section">
+    <div class="table-header">
+      <h3>产品 ({totalRecords} 项)</h3>
+      {#if loading}
+        <div class="loading">加载中...</div>
+      {/if}
+    </div>
+    
+    <DataTable 
+      columns={productTable.columns}
+      data={tableData}
+      indicatorColumn={productTable.indicatorColumn}
+      actionsColumn={productTable.actionsColumn}
+      round={productTable.round}
+      {totalRecords}
+      {currentPage}
+      {pageSize}
+      on:pageChange={handlePageChange}
+      on:sort={handleSort}
+    />
+  </div>
+</div>
+
+<style>
+  .product-management {
+    display: flex;
+    flex-direction: column;
+    gap: 24px;
+    padding: 16px;
+  }
+  
+  .search-section {
+    background: #f8f9fa;
+    padding: 16px;
+    border-radius: 8px;
+    border: 1px solid #dee2e6;
+  }
+  
+  .table-section {
+    flex: 1;
+  }
+  
+  .table-header {
+    display: flex;
+    justify-content: space-between;
+    align-items: center;
+    margin-bottom: 16px;
+  }
+  
+  .loading {
+    color: #6c757d;
+    font-style: italic;
+  }
+</style>
+```
+
+## 最佳实践
+
+### 1. 性能优化
+
+```typescript
+// 使用虚拟滚动优化大数据集
+class VirtualizedTable extends FlexiDataTable {
+  private virtualItemHeight = 40;
+  private visibleItemCount = 20;
+  
+  getVirtualizedProps() {
+    return {
+      itemHeight: this.virtualItemHeight,
+      visibleCount: this.visibleItemCount,
+      overscan: 5
+    };
+  }
+}
+
+// 防抖搜索和过滤操作
+class OptimizedTable extends FlexiDataTable {
+  private searchDebounce = 300;
+  
+  createDebouncedSearch(searchFn: Function) {
+    let timeoutId: number;
+    return (...args: any[]) => {
+      clearTimeout(timeoutId);
+      timeoutId = setTimeout(() => searchFn(...args), this.searchDebounce);
+    };
+  }
+}
+```
+
+### 2. 可访问性
+
+```typescript
+const accessibleTableSchema = {
+  round: true,
+  indicatorColumn: {
+    width: 60,
+    displayNo: true,
+    selectable: true
+  },
+  columns: [
+    {
+      text: '产品名称',
+      field: 'name',
+      width: 200,
+      // 为屏幕阅读器添加 ARIA 属性
+      'aria-label': '产品名称，可排序列',
+      'aria-sort': 'none'
+    }
+  ]
+};
+```
+
+### 3. 错误处理
+
+```typescript
+class RobustDataTable extends FlexiDataTable {
+  handleError(error: any, context: string): void {
+    console.error(`表格在 ${context} 中发生错误:`, error);
+    
+    // 显示用户友好的错误消息
+    this.showErrorMessage(`${context} 失败。请重试。`);
+    
+    // 记录错误用于监控
+    this.logError(error, context);
+  }
+  
+  private showErrorMessage(message: string): void {
+    // 实现用户通知
+    console.log('用户消息:', message);
+  }
+  
+  private logError(error: any, context: string): void {
+    // 发送错误到监控服务
+    fetch('/api/errors', {
+      method: 'POST',
+      headers: { 'Content-Type': 'application/json' },
+      body: JSON.stringify({
+        error: error.message,
+        context,
+        timestamp: new Date().toISOString()
+      })
+    });
+  }
+}
+```
+
+### 4. 状态管理
+
+```typescript
+class StatefulDataTable extends FlexiDataTable {
+  private state = {
+    sortColumn: null,
+    sortDirection: 'asc',
+    selectedRows: [],
+    columnWidths: {},
+    hiddenColumns: []
+  };
+  
+  saveState(): void {
+    localStorage.setItem('table-state', JSON.stringify(this.state));
+  }
+  
+  loadState(): void {
+    try {
+      const saved = localStorage.getItem('table-state');
+      if (saved) {
+        this.state = { ...this.state, ...JSON.parse(saved) };
+        this.applyState();
+      }
+    } catch (error) {
+      console.error('加载表格状态失败:', error);
+    }
+  }
+  
+  private applyState(): void {
+    // 应用保存的列宽度
+    this.columns.forEach((column, index) => {
+      if (this.state.columnWidths[index]) {
+        column.width = this.state.columnWidths[index];
+      }
+    });
+    
+    // 应用列可见性
+    this.state.hiddenColumns.forEach(index => {
+      if (this.columns[index]) {
+        this.columns[index].visible = false;
+      }
+    });
+  }
+}
+```
+
+这个综合指南提供了有效使用和扩展 FlexiDataTable 构建复杂数据管理界面所需的一切。示例展示了如何创建强大、交互式的表格，具有实时更新、自定义渲染和复杂数据操作等高级功能。