@lowcodex/gen-report-design

用来设计报表的包：搭表样、选数据集 / 层级、绑定单元格，产出可落盘的页面稿子。

预览 / 发布请用 @lowcodex/gen-report-view。

安装和使用

1. 安装：pnpm add @lowcodex/gen-report-design
2. 引入编辑器样式（主题 + editor.scss）
3. 传 schema / onChange，以及目录、字段说明、queryData

字段说明可以放在 datasetDetails / hierarchyDetails 里；没有的话也可以走 queryData 里的 load* 方法按需补。

import '@lowcodex/gen-ui/scss/themes/cxd.scss'; // 按你们主题路径调整
import '@lowcodex/gen-editor-core/scss/editor.scss';

queryData 方法

设计期只补元数据（字段、参数说明），不做运行取数。

| 方法 | 要不要实现 | 干什么 | |---|---|---| | loadDatasetDetail | 没预传齐 datasetDetails 时要写 | 按数据集 id 补字段列表、SQL 参数定义等，供面板选字段、绑参数 | | loadHierarchyDetail | 没预传齐 hierarchyDetails 时要写 | 按层级 id 补字段、层级、mapping 等 |

外面已经传全 datasetDetails / hierarchyDetails 时，load* 可以不写，queryData 传 {} 即可。

对接例子

import {useRef, useState} from 'react';
import {
  ReportDesigner,
  type ReportDesignerHandle,
  type ReportQueryData
} from '@lowcodex/gen-report-design';
import type {SchemaObject} from '@lowcodex/gen-renderer';

const catalog = {
  datasets: [{id: 'ds_expense', name: '支出明细'}],
  hierarchies: [{id: 'h_func', name: '功能分类'}]
};

const datasetDetails = {
  ds_expense: {
    id: 'ds_expense',
    name: '支出明细',
    fields: [
      {name: 'ORG_NAME', label: '部门'},
      {name: 'ACOUNT', label: '金额'}
    ],
    parameters: [{key: 'ORG_NAME', name: '部门'}]
  }
};

const hierarchyDetails = {
  h_func: {
    id: 'h_func',
    name: '功能分类',
    fields: [
      {name: 'EXP_FUNC_CODE', label: '功能分类编码'},
      {name: 'EXP_FUNC_NAME', label: '功能分类名称'}
    ],
    parameters: [],
    levels: [{level: 1, nodeCount: 2}],
    mapping: {labelField: 'EXP_FUNC_NAME', valueField: 'EXP_FUNC_CODE'}
  }
};

const queryData: ReportQueryData = {
  // 外面已传 datasetDetails / hierarchyDetails 时可不开
  // async loadDatasetDetail(datasetId) {
  //   return api.fetchDatasetMeta(datasetId);
  // },
  // async loadHierarchyDetail(hierarchyId) {
  //   return api.fetchHierarchyMeta(hierarchyId);
  // }
};

function DesignApp() {
  const designerRef = useRef<ReportDesignerHandle>(null);
  const [schema, setSchema] = useState<SchemaObject>(/* 初始页面稿子 */);

  return (
    <ReportDesigner
      ref={designerRef}
      schema={schema}
      onChange={setSchema}
      catalog={catalog}
      datasetDetails={datasetDetails}
      hierarchyDetails={hierarchyDetails}
      queryData={queryData}
      className="is-fixed"
    />
  );
}

// 保存：提取设计器源码即可
async function saveReport(designerRef: {current: ReportDesignerHandle | null}) {
  const source = designerRef.current?.getSchema();
  if (!source) return;
  await api.saveReport(source);
}

参数

| 名字 | 白话 | |---|---| | schema / onChange | 整页稿子双向绑定 | | catalog | 左侧可选的数据集 / 层级目录 | | datasetDetails / hierarchyDetails | 字段、参数等说明；没有时可靠 load* 补 | | queryData | 按需补元数据的方法集合 | | className | 常用 is-fixed 铺满编辑器区域 | | ref.getSchema() | 提取当前页面源码，可直接保存 |

单元格 ${变量} 怎么用

设计器里在单元格直接写占位文案，例如：

• ${ORG_NAME}
• 制表单位：${ORG_NAME}

保存源码后，预览端把同名值放进 params：

<ReportView
  schema={savedSchema}
  queryData={queryData}
  params={{ORG_NAME: '第一幼儿园', EXP_FUNC_CODE: '205'}}
/>

预览展开时会把单元格里的 ${ORG_NAME} 换成 第一幼儿园。
数据集 SQL 参数若写成 '${ORG_NAME}'，也会先用 params 解析，再交给 executeDataset。

设计态一般只显示占位符本身；换成真实内容发生在预览 / 发布。

和预览怎么配合

• 设计应用里用本包改稿、保存 schema
• 预览 / 发布应用里用 @lowcodex/gen-report-view 读 schema、按预览端自己的 queryData（含 execute*）出表

两个包会抢同一个组件注册名，所以设计页和预览页不要打在同一个页面里一起加载。常见做法是拆两个应用，或切换时整页刷新。