foggy-data-viewer 1.0.1-beta.26 → 1.0.1-beta.28

package/README.md

@@ -8,7 +8,7 @@
 - 📊 **动态列配置** - 基于 QM Schema + TableConfig 的灵活列配置
 - 🔍 **高级筛选** - 支持多种数据类型的筛选器（表头过滤 + 独立搜索工具栏）
 - 📈 **汇总行** - 自动计算选中行和全量汇总
-- 🎨 **自定义渲染** - 支持自定义格式化和渲染函数
+- 🎨 **自定义渲染** - 支持 `column-*` 插槽、自定义格式化和渲染函数
 - 🔧 **组合组件** - 提供 SearchToolbar + DataTable 的组合组件
 - ✅ **高测试覆盖** - 核心组件覆盖率 90%+
 - 📦 **按需引入** - ES Module 支持
@@ -184,43 +184,119 @@ function buildTableColumns(
   - `showAll?: boolean` - 是否显示所有列
   - `customizations?: ColumnCustomization[]` - 列自定义配置
 
-**返回：**
-- `EnhancedColumnSchema[]` - 增强的列配置数组
-
-## 类型定义
-
-```typescript
-interface ColumnSchema {
-  name: string
-  type: string
-  title: string
-}
-
-interface ColumnCustomization {
-  name: string
-  width?: number
-  minWidth?: number
-  fixed?: 'left' | 'right'
-  formatter?: (value: any) => string
-  render?: (params: any) => VNode
-  filterComponent?: Component
-}
-
-interface TableConfig {
+**返回：**
+- `EnhancedColumnSchema[]` - 增强的列配置数组
+
+## 列内容自定义
+
+### `column-*` 插槽（推荐用于交互）
+
+当业务列需要渲染成链接、按钮，或点击后交给上游页面打开详情、编辑弹窗时，推荐使用 `#column-{field}` 插槽。插槽参数为 `{ row, value, column }`。
+
+```vue
+<script setup lang="ts">
+function openDetail(row: Record<string, unknown>) {
+  // 由业务系统决定跳转、弹窗或其他处理方式
+}
+</script>
+
+<template>
+  <DataTableWithSearch
+    :columns="columns"
+    :data="data"
+    :total="total"
+    :loading="loading"
+  >
+    <template #column-name="{ row, value }">
+      <button type="button" class="link-cell" @click.stop="openDetail(row)">
+        {{ value || '-' }}
+      </button>
+    </template>
+  </DataTableWithSearch>
+</template>
+```
+
+`foggy-gen` 生成的 QueryTable wrapper 也会透传 `column-*` / `filter-*` 动态插槽，因此业务页可以直接在生成组件上写同样的插槽：
+
+```vue
+<VehicleCapacityProfileManagementQueryTable>
+  <template #column-profileName="{ row, value }">
+    <button type="button" class="link-cell" @click.stop="openProfile(row)">
+      {{ value || '-' }}
+    </button>
+  </template>
+</VehicleCapacityProfileManagementQueryTable>
+```
+
+### `render` 函数（适合纯展示）
+
+如果只是添加颜色、图标、标签等展示效果，也可以通过 `ColumnCustomization.render` 或生成组件的 `columnOverrides[field].render` 配置渲染函数：
+
+```typescript
+import { h } from 'vue'
+import { buildTableColumns } from 'foggy-data-viewer'
+
+const columns = buildTableColumns(qmSchema, {
+  visibleColumns: ['name', 'status'],
+  customizations: [
+    {
+      name: 'status',
+      render: ({ value, column }) => h(
+        'span',
+        { class: value === 'active' ? 'status-ok' : 'status-muted' },
+        `${column.title}: ${String(value ?? '-')}`
+      )
+    }
+  ]
+})
+```
+
+选择原则：需要绑定业务事件时优先用 `column-*` 插槽；只改显示内容时使用 `render` 更轻。
+
+## 类型定义
+
+```typescript
+import type { Component } from 'vue'
+
+interface ColumnSchema {
+  name: string
+  type: string
+  title: string
+}
+
+interface CellRenderContext {
+  row: Record<string, unknown>
+  value: unknown
+  column: EnhancedColumnSchema
+}
+
+type CellRenderFn = (params: CellRenderContext) => unknown
+
+interface ColumnCustomization {
+  name: string
+  width?: number
+  minWidth?: number
+  fixed?: 'left' | 'right'
+  formatter?: (value: unknown) => string
+  render?: CellRenderFn
+  filterComponent?: Component | unknown
+}
+
+interface TableConfig {
   visibleColumns?: string[]
   showAll?: boolean
   customizations?: ColumnCustomization[]
 }
 
 interface EnhancedColumnSchema extends ColumnSchema {
-  width?: number
-  minWidth?: number
-  fixed?: 'left' | 'right'
-  customFormatter?: (value: any) => string
-  customRender?: (params: any) => VNode
-  customFilterComponent?: Component
-}
-```
+  width?: number
+  minWidth?: number
+  fixed?: 'left' | 'right'
+  customFormatter?: (value: unknown) => string
+  customRender?: CellRenderFn
+  customFilterComponent?: Component | unknown
+}
+```
 
 ## 开发
 

package/dist/api/viewer.d.ts

@@ -1,4 +1,4 @@
-import type { QueryMetaResponse, ViewerQueryRequest, ViewerDataResponse, FilterOptionsResponse, ColumnSchema, FrontendMeta, MemberQueryRequest, MemberQueryResponse } from '@/types';
+import type { QueryMetaResponse, ViewerQueryRequest, ViewerDataResponse, FilterOptionsResponse, ColumnSchema, FrontendMeta, MemberQueryRequest, MemberQueryResponse, OrderRequestDef } from '@/types';
 /**
  * 查询 payload（与 dataset.query_model 格式一致）
  */
@@ -14,10 +14,7 @@ export interface QueryPayload {
         field: string;
         agg?: string;
     }>;
-    orderBy?: Array<{
-        field: string;
-        order: 'asc' | 'desc';
-    }>;
+    orderBy?: OrderRequestDef[];
     calculatedFields?: Array<{
         name: string;
         expression: string;

package/dist/components/QueryPanel.vue.d.ts

@@ -3,7 +3,7 @@ import type { SliceRequestDef, MemberQueryRequest, MemberQueryResponse } from '@
  * QueryPanel - 传统查询区组件
  *
  * 根据 QuerySchema 渲染表格上方的查询表单区域。
- * 支持响应式 grid 布局、折叠/展开、查询/重置。
+ * 支持响应式 grid 布局、查询/重置。
  * 只处理 placement='form' 的查询字段。
  */
 export interface QueryFieldSchema {

package/dist/components/list-preset/ListPresetManager.vue.d.ts

@@ -74,7 +74,10 @@ declare const _default: import("vue").DefineComponent<Props, {
             }[];
             orderBy: {
                 field: string;
-                order: "asc" | "desc";
+                dir?: import("@/types").SortDirection;
+                order?: import("@/types").SortDirection;
+                nullLast?: boolean;
+                nullFirst?: boolean;
             }[];
         };
         pageSize?: number;

package/dist/index.d.ts

@@ -26,4 +26,4 @@ export { saveQuery, listSavedQueries, getSavedQuery, updateSavedQuery, deleteSav
 export type { SavedQueryDef, SaveQueryRequest, QueryVisibility } from './api/savedQuery';
 export { listPresets, getDefaultListPreset, createListPreset, getListPreset, updateListPreset, deleteListPreset, setDefaultListPreset, clearDefaultListPreset } from './api/listPreset';
 export type { ListPresetScope, SaveListPresetRequest, UpdateListPresetRequest } from './api/listPreset';
-export type { ColumnSchema, EnhancedColumnSchema, TableConfig, TableSchema, CellCopyConfig, QueryMode, ColumnCustomization, QueryMetaResponse, ViewerQueryRequest, ViewerDataResponse, SliceRequestDef, OrderRequestDef, FilterOption, FetchDataParams, FetchDataResult, FetchDataFn, DictItem, PaginationState, SortState, QueryHooks, QueryHookContext, QueryTrigger, QueryHookName, BeforeQueryHookFn, AfterQueryHookFn, ErrorQueryHookFn, MaybePromise, PivotAxisField, PivotAxisPage, PivotAxisPageScope, PivotAxisRole, PivotHeaderNode, PivotHeaderRole, PivotMetric, PivotRawAxisMember, PivotRawCell, PivotRawPayload, PivotShape, PivotViewMode, PivotViewModel, ListPresetVisibility, ListPresetPlacement, ListPresetConfig, ColumnViewSetting, QueryConditionPreset, ListViewState, ListPresetDef, FrontendMeta, FieldMeta, FieldCategory, MemberLookupMeta, UiHintsMeta, DefaultsMeta, CapabilitiesMeta, ParamsMeta, MemberQueryRequest, MemberOption, MemberQueryResponse } from './types';
+export type { ColumnSchema, EnhancedColumnSchema, TableConfig, TableSchema, CellRenderContext, CellRenderFn, CellCopyConfig, QueryMode, ColumnCustomization, QueryMetaResponse, ViewerQueryRequest, ViewerDataResponse, SliceRequestDef, OrderRequestDef, FilterOption, FetchDataParams, FetchDataResult, FetchDataFn, DictItem, PaginationState, SortState, QueryHooks, QueryHookContext, QueryTrigger, QueryHookName, BeforeQueryHookFn, AfterQueryHookFn, ErrorQueryHookFn, MaybePromise, PivotAxisField, PivotAxisPage, PivotAxisPageScope, PivotAxisRole, PivotHeaderNode, PivotHeaderRole, PivotMetric, PivotRawAxisMember, PivotRawCell, PivotRawPayload, PivotShape, PivotViewMode, PivotViewModel, ListPresetVisibility, ListPresetPlacement, ListPresetConfig, ColumnViewSetting, QueryConditionPreset, ListViewState, ListPresetDef, FrontendMeta, FieldMeta, FieldCategory, MemberLookupMeta, UiHintsMeta, DefaultsMeta, CapabilitiesMeta, ParamsMeta, MemberQueryRequest, MemberOption, MemberQueryResponse } from './types';