基础用法 ​

本文说明如何在宿主中挂载 GrowDataPrepDesigner，以及界面上的完整操作细节（工具栏、左轨、画布、预览 / 保存）。数据模型与公式见专页。

演示模块接入 ​

演示包 @grow-admin-cornerstone/apps-designer 同时提供四个设计器 playground。数据准备菜单标题为 数据准备，路由 path：data-prep-playground。

宿主（如 sample）需：

1. workspace 依赖 @grow-admin-rock/data-prep 与 @grow-admin-cornerstone/apps-designer
2. IOC 中 .use(appsDesignerLib)
3. apps-home 动态路由合并菜单
4. 开发环境启用 Mock：sample/mock/dataPrep.ts

Mock 路径（相对 mock 前缀，常见为 /mock）：

装配细节见 业务模块开发、DesignCornerstone、低代码设计器。

在页面中使用 ​

<template>
  <div class="data-prep-playground">
    <GrowDataPrepDesigner v-model="dataset" @save="onSaved" />
  </div>
</template>

<script setup lang="ts">
import { ref } from 'vue'
import {
  GrowDataPrepDesigner,
  createDataPrepDataset,
  ensureDemoDataset,
  type DataPrepDataset,
} from '@grow-admin-rock/data-prep'

const seeded = ensureDemoDataset()

const dataset = ref<DataPrepDataset>(
  seeded[0] ||
    createDataPrepDataset({
      name: '未命名数据集',
      schemaRefs: [{ schemaId: 'schema_demo_sales', schemaName: 'demo_sales' }],
    }),
)

const onSaved = (value: DataPrepDataset) => {
  dataset.value = value
  // 可在此同步到后端或 Pinia
}
</script>

<style scoped>
.data-prep-playground {
  position: relative;
  width: 100%;
  height: 100%;
  min-height: 0;
  overflow: hidden;
}
</style>

Props / Events ​

组件没有 defineExpose。需要快照时用 v-model 或监听 update:modelValue。

外部改写 modelValue 时，设计器会按新对象回填画布（注意保持 id 稳定，避免无谓重建）。

界面总览 ​

┌──────────────────────────────────────────────────────────────┐
│ [数据集名称________]              [预览数据] [保存]            │
├────┬───────────────┬─────────────────────────────────────────┤
│轨  │ 侧栏 320px     │ Vue Flow 画布                            │
│道  │ 添加表/度量/…  │ SourceTableNode + JoinEdge + MiniMap    │
└────┴───────────────┴─────────────────────────────────────────┘
         └─ 编辑度量时另开配置浮层；预览为底部 Drawer

工具栏 ​

左侧轨道 ​

点击切换面板，再点同一项关闭。默认打开「维度 / 度量」。

添加表 ​

1. 顶部搜索框：placeholder「搜索表名 / 注释」，按名称 / 注释过滤
2. 按建模分组展示；中间表 isJunction、已添加的表不会出现在可选列表
3. 行内「添加」：写入 sources，更新 schemaRefs；第一张表自动设为 primarySourceId
4. 空态文案：
   • 「暂无可用建模」
   • 「无匹配的表」
   • 「该建模下的表已全部添加」

跨建模混加是支持的（例如销售库 orders + 区域库 regions）。

维度 / 度量 ​

• 列表空态：「暂无维度 / 度量」「点击右上角「添加」创建第一条配置」
• 「添加 / 编辑」打开侧扩展配置面板，标题为「添加维度 / 度量」或「编辑维度 / 度量」
• 保存校验（不通过则静默不关面板，无 toast）：
  • 至少一个维度字段
  • 度量名称非空
  • 公式非空
  • outputKey 经 ensureUniqueMeasureOutputKey 保证唯一

配置面板字段：

删除配置会同步从 outputFields 中剔除对应度量 key（实现侧会 prune）。

数据输出 ​

• 说明文案大意：勾选要输出的字段，并在已选区拖拽调整列顺序
• 分区通常包括：
  • 明细字段：按表折叠，键为 alias.column
  • 度量字段：键为各配置的 outputKey
  • 已选字段：可拖拽排序，即最终 outputFields
• 空态：「请先添加表或配置度量」

预览与 queryDatasetLocal 只输出 outputFields 中的列；未勾选的维度 / 度量不会出现在结果里。

数据集信息 ​

画布交互 ​

Join 抽屉字段 ​

详见 表关联。

预览抽屉 ​

预览默认 limit: 100。

推荐操作流程（逐步） ​

1. 添加表：左轨「添加表」→ 选建模下的表连续添加；确认主表
2. 多表则配 Join：画布拖线 → 选类型与等值字段 → 确定
3. 配度量：左轨「维度 / 度量」→ 添加 → 选维度、填名称 / Key、编辑公式 → 保存
4. 勾选输出：左轨「数据输出」勾选维度列与度量 Key，并排好顺序
5. 预览数据：工具栏预览，确认列与行
6. 保存：写入 Mock + localStorage（key 见 数据模型）

Demo 数据 ​

ensureDemoDataset()：本地尚无数据集时写入「订单区域汇总」（按区域 SUM 金额与数量）。若预览按钮仍禁用，打开「数据输出」勾选对应字段。

与页面 / 报表对接（详细） ​

数据准备不向图表暴露「选 Dataset」控件。推荐链路：

保存 DataPrepDataset
    → 展示侧 apiOutlined 请求 POST …/data-prep/query
    → fit / didFetch 把 { columns, rows } 写入 state
    → 页面绑定 props / 报表 dataBinding 读 state.xxx

宿主也可直接调用：

import {
  queryDataPrepDataset,
  queryDatasetLocal,
  toCartesianSeriesPayload,
} from '@grow-admin-rock/data-prep'

// HTTP（走 Mock / 真实后端）
const result = await queryDataPrepDataset({ datasetId: 'dataset_demo_orders_region' })

// 纯前端（自备 tableRows）
const local = queryDatasetLocal(dataset, tableRows, { limit: 200 })

// 整理成笛卡尔图轴 / 系列，再赋给 state
const payload = toCartesianSeriesPayload(local, 'orders.region', ['amount'])

页面侧绑定示例思路：

• 数据源或计算属性：state.chartCategories = rows.map(r => r['orders.region'])
• 报表 xAxisData：state.chartCategories；seriesData[0]：对应数值数组

完整协同说明见 协同工作。

相关文档 ​

• 数据模型
• 公式度量
• 表关联
• 报表 · 数据绑定
• 数据库建模
• Mock 数据