foggy-data-viewer 1.0.1-beta.0

package/src/examples/EnhancedTableExample.vue

@@ -0,0 +1,136 @@
+<script setup lang="ts">
+import { ref, onMounted, h } from 'vue'
+import DataTable from '@/components/DataTable.vue'
+import { fetchQueryMeta, fetchQueryData } from '@/api/viewer'
+import { buildTableColumns } from '@/utils/schemaHelper'
+import type { EnhancedColumnSchema, TableConfig } from '@/types'
+
+// 示例1: 显式指定列及顺序
+const tableConfig: TableConfig = {
+  visibleColumns: ['orderId', 'orderDate', 'customerName', 'amount', 'status', 'isPaid', 'metadata'],
+  customizations: [
+    {
+      name: 'orderId',
+      width: 150,
+      fixed: 'left'
+    },
+    {
+      name: 'orderDate',
+      width: 120
+    },
+    {
+      name: 'customerName',
+      width: 150
+    },
+    {
+      // formatter: 用于格式化数据（导出时使用）
+      name: 'amount',
+      width: 120,
+      formatter: (value) => `¥${Number(value).toFixed(2)}`
+    },
+    {
+      // render: 用于自定义显示（仅前端显示，不影响导出）
+      name: 'status',
+      width: 100,
+      render: ({ value }) => {
+        const statusMap: Record<string, { text: string; color: string }> = {
+          paid: { text: '已支付', color: '#67c23a' },
+          pending: { text: '待支付', color: '#e6a23c' },
+          cancelled: { text: '已取消', color: '#909399' }
+        }
+        const status = statusMap[value as string] || { text: value as string, color: '#909399' }
+        return h('span', { style: { color: status.color, fontWeight: 'bold' } }, status.text)
+      }
+    },
+    {
+      // render: 将 true 渲染成勾符号
+      name: 'isPaid',
+      width: 80,
+      render: ({ value }) => {
+        return h('span', {
+          style: { fontSize: '18px', color: value ? '#67c23a' : '#f56c6c' }
+        }, value ? '✓' : '✗')
+      }
+    },
+    {
+      // formatter: 将 JSON 对象转成文字（用于导出）
+      name: 'metadata',
+      width: 200,
+      formatter: (value) => {
+        if (!value) return ''
+        if (typeof value === 'object') {
+          return JSON.stringify(value)
+        }
+        return String(value)
+      }
+    }
+  ]
+}
+
+// 示例2: 显示所有列（按 QM schema 顺序）
+const tableConfigShowAll: TableConfig = {
+  showAll: true,
+  customizations: [
+    {
+      name: 'orderId',
+      width: 150,
+      fixed: 'left'
+    }
+  ]
+}
+
+const columns = ref<EnhancedColumnSchema[]>([])
+const data = ref<Record<string, unknown>[]>([])
+const total = ref(0)
+const loading = ref(false)
+
+async function loadData() {
+  try {
+    loading.value = true
+
+    // 1. 获取 QM schema
+    const meta = await fetchQueryMeta('your-query-id')
+
+    // 2. 合并 schema 和定制参数
+    columns.value = buildTableColumns(meta.schema, tableConfig)
+
+    // 3. 加载数据
+    const response = await fetchQueryData('your-query-id', {
+      start: 0,
+      limit: 50
+    })
+
+    data.value = response.items
+    total.value = response.total
+  } catch (error) {
+    console.error('Failed to load data:', error)
+  } finally {
+    loading.value = false
+  }
+}
+
+onMounted(() => {
+  loadData()
+})
+</script>
+
+<template>
+  <div class="example-container">
+    <h2>增强表格示例</h2>
+    <DataTable
+      :columns="columns"
+      :data="data"
+      :total="total"
+      :loading="loading"
+      @page-change="(page, size) => console.log('Page changed:', page, size)"
+      @sort-change="(field, order) => console.log('Sort changed:', field, order)"
+      @filter-change="(slices) => console.log('Filter changed:', slices)"
+    />
+  </div>
+</template>
+
+<style scoped>
+.example-container {
+  padding: 20px;
+}
+</style>

package/src/index.ts

@@ -0,0 +1,32 @@
+// 统一引入所有依赖样式（用户只需引入一次）
+import 'vxe-table/lib/style.css'
+import 'element-plus/dist/index.css'
+
+// 导出组件
+export { default as DataTable } from './components/DataTable.vue'
+export { default as DataViewer } from './components/DataViewer.vue'
+export { default as SearchToolbar } from './components/SearchToolbar.vue'
+export { default as DataTableWithSearch } from './components/DataTableWithSearch.vue'
+
+// 导出过滤器组件
+export * from './components/filters'
+
+// 导出 Composables
+export * from './components/composables'
+
+// 导出工具函数
+export { buildTableColumns } from './utils/schemaHelper'
+
+// 导出类型定义
+export type {
+  ColumnSchema,
+  EnhancedColumnSchema,
+  TableConfig,
+  ColumnCustomization,
+  QueryMetaResponse,
+  ViewerQueryRequest,
+  ViewerDataResponse,
+  SliceRequestDef,
+  OrderRequestDef,
+  FilterOption
+} from './types'

package/src/main.ts

@@ -0,0 +1,14 @@
+import { createApp } from 'vue'
+import VXETable from 'vxe-table'
+import 'vxe-table/lib/style.css'
+import ElementPlus from 'element-plus'
+import 'element-plus/dist/index.css'
+import zhCn from 'element-plus/dist/locale/zh-cn.mjs'
+import App from './App.vue'
+
+const app = createApp(App)
+
+app.use(VXETable)
+app.use(ElementPlus, { locale: zhCn })
+
+app.mount('#app')

package/src/types/index.ts

@@ -0,0 +1,159 @@
+/**
+ * 字典项
+ */
+export interface DictItem {
+  value: string | number
+  label: string
+}
+
+/**
+ * 列定义类型
+ */
+export interface ColumnSchema {
+  name: string
+  type: string
+  title?: string
+  filterable?: boolean
+  aggregatable?: boolean
+
+  // 过滤器元数据
+  filterType?: 'text' | 'number' | 'date' | 'datetime' | 'dict' | 'dimension' | 'bool' | 'custom'
+  dictId?: string
+  dictItems?: DictItem[]
+  dimensionRef?: string
+  format?: string
+  measure?: boolean
+  uiConfig?: Record<string, unknown>
+}
+
+/**
+ * DSL 过滤条件 (SliceRequestDef)
+ * 直接对应后端 DSL 格式
+ */
+export interface SliceRequestDef {
+  field: string
+  op: string  // =, !=, >, >=, <, <=, in, like, right_like, [], [), is null, is not null 等
+  value?: unknown
+  link?: 1 | 2  // 1=AND, 2=OR
+  children?: SliceRequestDef[]
+}
+
+/**
+ * DSL 排序条件 (OrderRequestDef)
+ */
+export interface OrderRequestDef {
+  field: string
+  order: 'asc' | 'desc'
+}
+
+/**
+ * 查询元数据响应（重构后的版本）
+ */
+export interface QueryMetaResponse {
+  title: string
+  tableConfig: TableConfig  // 改为 tableConfig
+  estimatedRowCount: number | null
+  expiresAt: string
+  /** 初始过滤条件（来自缓存） */
+  initialSlice?: SliceRequestDef[]
+}
+
+/**
+ * 数据查询请求 (使用 DSL 格式)
+ */
+export interface ViewerQueryRequest {
+  start?: number
+  limit?: number
+  /** 过滤条件 (DSL slice 格式) */
+  slice?: SliceRequestDef[]
+  /** 排序条件 (DSL orderBy 格式) */
+  orderBy?: OrderRequestDef[]
+}
+
+/**
+ * 过滤选项（用于下拉）
+ */
+export interface FilterOption {
+  value: string | number
+  label: string
+}
+
+/**
+ * 过滤选项响应
+ */
+export interface FilterOptionsResponse {
+  options: FilterOption[]
+  total: number
+  error?: string
+}
+
+/**
+ * 数据响应
+ */
+export interface ViewerDataResponse {
+  success: boolean
+  items: Record<string, unknown>[]
+  total: number
+  start: number
+  limit: number
+  errorMessage?: string
+  expired?: boolean
+  /** 全量数据汇总（包含总记录数和度量合计） */
+  totalData?: Record<string, unknown>
+}
+
+/**
+ * 分页状态
+ */
+export interface PaginationState {
+  currentPage: number
+  pageSize: number
+  total: number
+}
+
+/**
+ * 排序状态
+ */
+export interface SortState {
+  field: string | null
+  order: 'asc' | 'desc' | null
+}
+
+/**
+ * 列定制配置
+ */
+export interface ColumnCustomization {
+  name: string
+  width?: number
+  minWidth?: number
+  fixed?: 'left' | 'right'
+  render?: (params: { row: Record<string, unknown>; value: unknown }) => unknown
+  filterComponent?: unknown
+  formatter?: (value: unknown) => string
+}
+
+/**
+ * 增强的列配置（合并 QM schema 和前端定制）
+ */
+export interface EnhancedColumnSchema extends ColumnSchema {
+  width?: number
+  minWidth?: number
+  fixed?: 'left' | 'right'
+  customRender?: (params: { row: Record<string, unknown>; value: unknown }) => unknown
+  customFilterComponent?: unknown
+  customFormatter?: (value: unknown) => string
+}
+
+/**
+ * 表格配置
+ */
+export interface TableConfig {
+  /** QM 模型名称 */
+  qmModel: string
+  /** 显式指定显示的列及顺序（必填，除非 showAll=true） */
+  visibleColumns?: string[]
+  /** 显示所有列 */
+  showAll?: boolean
+  /** 列定制配置 */
+  customizations?: ColumnCustomization[]
+}

package/src/utils/README.md

@@ -0,0 +1,140 @@
+# Schema Helper 使用说明
+
+## 核心概念
+
+### formatter vs render
+
+- **formatter**: 用于数据格式化，影响**导出**和**显示**
+  - 返回值：`string`
+  - 使用场景：格式化金额、日期、将 JSON 转文字等
+  - 示例：`formatter: (v) => '¥' + v`
+  - **不会修改原始数据**
+
+- **render**: 用于自定义渲染，仅影响**前端显示**
+  - 返回值：`VNode | string`
+  - 使用场景：添加图标、颜色、特殊样式等
+  - 示例：`render: ({ value }) => h('span', { style: { color: 'red' } }, value)`
+  - **不会修改原始数据**
+
+> **重要**：
+> - formatter 和 render 都只影响显示/导出，**不会修改 data 中的原始数据**
+> - 有 formatter 一般不需要 render，但不绝对
+> - 如果同时存在，render 用于显示，formatter 用于导出
+
+## 基本用法
+
+```typescript
+import { buildTableColumns } from '@/utils/schemaHelper'
+import type { TableConfig } from '@/types'
+
+// 1. 定义表格配置
+const config: TableConfig = {
+  // 必须指定显示的列及顺序
+  visibleColumns: ['id', 'name', 'amount', 'status'],
+
+  // 或者显示所有列
+  // showAll: true,
+
+  // 列定制
+  customizations: [
+    {
+      name: 'id',
+      width: 150,
+      fixed: 'left'
+    },
+    {
+      name: 'amount',
+      formatter: (v) => `¥${Number(v).toFixed(2)}`
+    },
+    {
+      name: 'status',
+      render: ({ value }) => h('span', {
+        style: { color: value === 'active' ? 'green' : 'red' }
+      }, value)
+    }
+  ]
+}
+
+// 2. 合并 QM schema 和定制配置
+const columns = buildTableColumns(qmSchema, config)
+
+// 3. 传给 DataTable 组件
+<DataTable :columns="columns" :data="data" />
+```
+
+## 常见场景
+
+### 场景1: 布尔值渲染成符号
+
+```typescript
+{
+  name: 'isPaid',
+  render: ({ value }) => h('span', {
+    style: { fontSize: '18px', color: value ? '#67c23a' : '#f56c6c' }
+  }, value ? '✓' : '✗')
+}
+```
+
+### 场景2: JSON 导出为文字
+
+```typescript
+{
+  name: 'metadata',
+  formatter: (value) => {
+    if (typeof value === 'object') {
+      return JSON.stringify(value)
+    }
+    return String(value)
+  }
+}
+```
+
+### 场景3: 状态带颜色显示
+
+```typescript
+{
+  name: 'status',
+  render: ({ value }) => {
+    const colors = { success: '#67c23a', warning: '#e6a23c', error: '#f56c6c' }
+    return h('span', { style: { color: colors[value] } }, value)
+  }
+}
+```
+
+### 场景4: 同时使用 formatter 和 render
+
+```typescript
+{
+  name: 'price',
+  // 导出时格式化为文字
+  formatter: (v) => `¥${Number(v).toFixed(2)}`,
+  // 显示时添加样式
+  render: ({ value }) => h('span', {
+    style: { fontWeight: 'bold', color: '#e6a23c' }
+  }, `¥${Number(value).toFixed(2)}`)
+}
+```
+
+## 配置选项
+
+### TableConfig
+
+| 属性 | 类型 | 必填 | 说明 |
+|------|------|------|------|
+| visibleColumns | string[] | 是* | 显示的列及顺序 |
+| showAll | boolean | 是* | 显示所有列 |
+| customizations | ColumnCustomization[] | 否 | 列定制配置 |
+
+*注：`visibleColumns` 和 `showAll` 必须二选一
+
+### ColumnCustomization
+
+| 属性 | 类型 | 说明 |
+|------|------|------|
+| name | string | 列名（必填） |
+| width | number | 列宽 |
+| minWidth | number | 最小列宽 |
+| fixed | 'left' \| 'right' | 固定列 |
+| formatter | (value) => string | 格式化函数（用于导出） |
+| render | ({ row, value }) => VNode \| string | 渲染函数（用于显示） |
+| filterComponent | Component | 自定义过滤器组件 |

package/src/utils/schemaHelper.test.ts

@@ -0,0 +1,215 @@
+import { describe, it, expect, vi } from 'vitest'
+import { buildTableColumns } from './schemaHelper'
+import type { ColumnSchema, TableConfig } from '@/types'
+
+describe('schemaHelper', () => {
+  const mockQMSchema: ColumnSchema[] = [
+    { name: 'id', type: 'INTEGER', title: 'ID' },
+    { name: 'name', type: 'TEXT', title: '名称' },
+    { name: 'amount', type: 'MONEY', title: '金额' },
+    { name: 'status', type: 'TEXT', title: '状态' }
+  ]
+
+  describe('buildTableColumns', () => {
+    it('should return all columns when config is empty (defaults to showAll)', () => {
+      const config: TableConfig = {}
+      const result = buildTableColumns(mockQMSchema, config)
+
+      // 空配置时默认显示所有列
+      expect(result).toHaveLength(4)
+      expect(result[0].name).toBe('id')
+      expect(result[1].name).toBe('name')
+      expect(result[2].name).toBe('amount')
+      expect(result[3].name).toBe('status')
+    })
+
+    it('should return all columns when showAll is true', () => {
+      const config: TableConfig = { showAll: true }
+      const result = buildTableColumns(mockQMSchema, config)
+
+      expect(result).toHaveLength(4)
+      expect(result[0].name).toBe('id')
+      expect(result[1].name).toBe('name')
+      expect(result[2].name).toBe('amount')
+      expect(result[3].name).toBe('status')
+    })
+
+    it('should return columns in specified order', () => {
+      const config: TableConfig = {
+        visibleColumns: ['amount', 'name', 'id']
+      }
+      const result = buildTableColumns(mockQMSchema, config)
+
+      expect(result).toHaveLength(3)
+      expect(result[0].name).toBe('amount')
+      expect(result[1].name).toBe('name')
+      expect(result[2].name).toBe('id')
+    })
+
+    it('should apply width customization', () => {
+      const config: TableConfig = {
+        visibleColumns: ['id', 'name'],
+        customizations: [
+          { name: 'id', width: 150 },
+          { name: 'name', width: 200 }
+        ]
+      }
+      const result = buildTableColumns(mockQMSchema, config)
+
+      expect(result[0].width).toBe(150)
+      expect(result[1].width).toBe(200)
+    })
+
+    it('should apply minWidth customization with default fallback', () => {
+      const config: TableConfig = {
+        visibleColumns: ['id', 'name'],
+        customizations: [
+          { name: 'id', minWidth: 100 }
+        ]
+      }
+      const result = buildTableColumns(mockQMSchema, config)
+
+      expect(result[0].minWidth).toBe(100)
+      expect(result[1].minWidth).toBe(120) // default
+    })
+
+    it('should apply fixed column customization', () => {
+      const config: TableConfig = {
+        visibleColumns: ['id', 'name', 'amount'],
+        customizations: [
+          { name: 'id', fixed: 'left' },
+          { name: 'amount', fixed: 'right' }
+        ]
+      }
+      const result = buildTableColumns(mockQMSchema, config)
+
+      expect(result[0].fixed).toBe('left')
+      expect(result[1].fixed).toBeUndefined()
+      expect(result[2].fixed).toBe('right')
+    })
+
+    it('should apply formatter customization', () => {
+      const formatter = (v: unknown) => `¥${v}`
+      const config: TableConfig = {
+        visibleColumns: ['amount'],
+        customizations: [
+          { name: 'amount', formatter }
+        ]
+      }
+      const result = buildTableColumns(mockQMSchema, config)
+
+      expect(result[0].customFormatter).toBe(formatter)
+    })
+
+    it('should apply render customization', () => {
+      const render = ({ value }: { value: unknown }) => String(value)
+      const config: TableConfig = {
+        visibleColumns: ['status'],
+        customizations: [
+          { name: 'status', render }
+        ]
+      }
+      const result = buildTableColumns(mockQMSchema, config)
+
+      expect(result[0].customRender).toBe(render)
+    })
+
+    it('should apply filterComponent customization', () => {
+      const filterComponent = {}
+      const config: TableConfig = {
+        visibleColumns: ['status'],
+        customizations: [
+          { name: 'status', filterComponent }
+        ]
+      }
+      const result = buildTableColumns(mockQMSchema, config)
+
+      expect(result[0].customFilterComponent).toBe(filterComponent)
+    })
+
+    it('should warn when column not found in schema', () => {
+      const consoleSpy = vi.spyOn(console, 'warn').mockImplementation(() => {})
+
+      const config: TableConfig = {
+        visibleColumns: ['id', 'nonexistent', 'name']
+      }
+      const result = buildTableColumns(mockQMSchema, config)
+
+      expect(result).toHaveLength(2)
+      expect(result[0].name).toBe('id')
+      expect(result[1].name).toBe('name')
+      expect(consoleSpy).toHaveBeenCalledWith(
+        'Column "nonexistent" not found in QM schema'
+      )
+
+      consoleSpy.mockRestore()
+    })
+
+    it('should handle empty visibleColumns (defaults to showAll)', () => {
+      const config: TableConfig = {
+        visibleColumns: []
+      }
+      const result = buildTableColumns(mockQMSchema, config)
+
+      // 空的 visibleColumns 时默认显示所有列
+      expect(result).toHaveLength(4)
+    })
+
+    it('should merge multiple customizations correctly', () => {
+      const formatter = (v: unknown) => `¥${v}`
+      const render = ({ value }: { value: unknown }) => String(value)
+
+      const config: TableConfig = {
+        visibleColumns: ['id', 'amount'],
+        customizations: [
+          {
+            name: 'id',
+            width: 150,
+            minWidth: 100,
+            fixed: 'left'
+          },
+          {
+            name: 'amount',
+            width: 120,
+            formatter,
+            render
+          }
+        ]
+      }
+      const result = buildTableColumns(mockQMSchema, config)
+
+      expect(result[0]).toMatchObject({
+        name: 'id',
+        width: 150,
+        minWidth: 100,
+        fixed: 'left'
+      })
+
+      expect(result[1]).toMatchObject({
+        name: 'amount',
+        width: 120
+      })
+      expect(result[1].customFormatter).toBe(formatter)
+      expect(result[1].customRender).toBe(render)
+    })
+
+    it('should preserve original schema properties', () => {
+      const config: TableConfig = {
+        visibleColumns: ['id', 'amount']
+      }
+      const result = buildTableColumns(mockQMSchema, config)
+
+      expect(result[0]).toMatchObject({
+        name: 'id',
+        type: 'INTEGER',
+        title: 'ID'
+      })
+
+      expect(result[1]).toMatchObject({
+        name: 'amount',
+        type: 'MONEY',
+        title: '金额'
+      })
+    })
+  })
+})