916 lines
26 KiB
Markdown
916 lines
26 KiB
Markdown
# Web Report Designer 初期架构设计方案 V1
|
||
|
||
> 文档状态：初期架构设计
|
||
>
|
||
> 本版本目标是先建立稳定的文档模型、布局管线和编辑器边界，不在第一阶段一次性实现所有复杂报表能力。
|
||
|
||
## 1. 项目定位
|
||
|
||
项目暂定名称：
|
||
|
||
~~~text
|
||
Web Report Designer
|
||
~~~
|
||
|
||
包名暂定：
|
||
|
||
~~~text
|
||
@xxx/report-core
|
||
@xxx/report-expression
|
||
@xxx/report-layout
|
||
@xxx/report-renderer
|
||
@xxx/report-designer
|
||
@xxx/report-designer-vue
|
||
~~~
|
||
|
||
项目定位：
|
||
|
||
> 一个面向业务系统的、纯 Web 的、可嵌入、可扩展、插件式的报表设计与渲染平台。
|
||
|
||
重点解决：
|
||
|
||
- 固定版式业务报表
|
||
- 打印单据
|
||
- A4/A5/自定义纸张
|
||
- 主表 + 子表
|
||
- 动态明细
|
||
- 多页打印
|
||
- 页眉页脚
|
||
- 基础分组和合计
|
||
- 数据绑定
|
||
- 受限表达式
|
||
- HTML、SVG 和浏览器打印
|
||
- 可扩展的 PDF 输出接口
|
||
|
||
明确不包含：
|
||
|
||
~~~text
|
||
BI
|
||
Dashboard
|
||
OLAP
|
||
数据分析
|
||
数据立方体
|
||
指标体系
|
||
大屏
|
||
~~~
|
||
|
||
### 1.1 V1 初期范围
|
||
|
||
V1 优先保证以下能力可用：
|
||
|
||
1. 文本、图片、线条、矩形等固定元素。
|
||
2. A4、A5 和自定义纸张。
|
||
3. 基础数据绑定和明细表。
|
||
4. 页眉、页脚和基础分页。
|
||
5. HTML、SVG 预览以及浏览器打印。
|
||
6. 文档序列化、校验和版本迁移。
|
||
7. 可注册的元素插件接口。
|
||
|
||
以下能力先预留模型和接口，放到后续迭代：
|
||
|
||
- 行列合并、跨页合计的分页级精细控制。
|
||
- 图表、条码、二维码等插件实现。
|
||
- 服务端 PDF 的具体实现。
|
||
- 协同编辑、权限体系和 BI 能力。
|
||
|
||
> 实现进度补充：基础分组（group-header / group-footer、多级分组、组内聚合）
|
||
> 已提前完成，详见 §16 阶段 3。
|
||
|
||
## 2. 总体架构
|
||
|
||
整体采用 Monorepo。
|
||
|
||
~~~text
|
||
report-designer/
|
||
│
|
||
├── apps/
|
||
│ └── report-designer/
|
||
│
|
||
├── packages/
|
||
│ ├── report-core/
|
||
│ ├── report-expression/
|
||
│ ├── report-layout/
|
||
│ ├── report-renderer/
|
||
│ │ └── src/
|
||
│ │ ├── html/
|
||
│ │ ├── svg/
|
||
│ │ └── pdf/
|
||
│ ├── report-designer/
|
||
│ ├── report-designer-vue/
|
||
│ └── plugins/
|
||
│ ├── qrcode/
|
||
│ ├── barcode/
|
||
│ ├── chart/
|
||
│ └── ...
|
||
│
|
||
├── examples/
|
||
├── pnpm-workspace.yaml
|
||
├── package.json
|
||
└── README.md
|
||
~~~
|
||
|
||
### 2.1 依赖方向
|
||
|
||
~~~text
|
||
report-expression ──> report-core
|
||
report-layout ──> report-core + report-expression
|
||
report-renderer ──> report-core + report-layout
|
||
report-designer ──> report-core + report-layout
|
||
report-designer-vue ──> report-designer
|
||
~~~
|
||
|
||
上图箭头表示“依赖”。Core 不依赖上述任何实现包。
|
||
|
||
Renderer 只消费布局结果，不重新计算分页。插件实现可以依赖 Core、Layout、Renderer 或 Designer 的适配器，但 Core 不反向依赖任何具体插件。
|
||
|
||
~~~text
|
||
plugin-qrcode
|
||
├── core element contract
|
||
├── layout adapter
|
||
├── renderer adapter
|
||
└── designer adapter（可选）
|
||
~~~
|
||
|
||
### 2.2 运行时主流程
|
||
|
||
~~~text
|
||
ReportDocument
|
||
│
|
||
▼
|
||
数据提供与参数注入
|
||
│
|
||
▼
|
||
表达式解析与绑定求值
|
||
│
|
||
▼
|
||
LayoutEngine（测量、展开、换行、分页）
|
||
│
|
||
▼
|
||
LayoutDocument（统一的分页结果）
|
||
│
|
||
├── HTML Renderer
|
||
├── SVG Renderer
|
||
└── PDF Renderer
|
||
~~~
|
||
|
||
## 3. 核心架构原则
|
||
|
||
### 3.1 Core 与 UI 完全分离
|
||
|
||
report-core：
|
||
|
||
~~~text
|
||
纯 TypeScript
|
||
无 Vue
|
||
无 React
|
||
无 DOM
|
||
无浏览器 API
|
||
无 UI 框架
|
||
~~~
|
||
|
||
Core 可以在 Browser、Node.js、Electron、Server 和 CLI 中复用。
|
||
|
||
### 3.2 文档模型与运行时状态分离
|
||
|
||
ReportDocument 只保存可序列化的报表定义，不保存以下编辑器状态：
|
||
|
||
- 当前选中项。
|
||
- 缩放比例和画布滚动位置。
|
||
- 辅助线、吸附线和临时选区。
|
||
- 撤销栈和 redo 栈。
|
||
- 已加载的数据和网络连接。
|
||
|
||
### 3.3 Layout 与 Renderer 分离
|
||
|
||
Layout 负责：
|
||
|
||
~~~text
|
||
尺寸计算
|
||
文本测量
|
||
换行
|
||
表格展开
|
||
动态高度
|
||
分页
|
||
~~~
|
||
|
||
Renderer 负责：
|
||
|
||
~~~text
|
||
把 LayoutDocument 绘制成 HTML、SVG 或 PDF
|
||
~~~
|
||
|
||
这样可以保证不同输出目标使用同一套分页结果。
|
||
|
||
### 3.4 运行时数据由外部注入
|
||
|
||
Core 不负责 fetch、数据库连接或 Token 管理。数据源定义和运行时数据提供器分开，避免把敏感配置写入报表文件。
|
||
|
||
### 3.5 文档必须可校验、可迁移
|
||
|
||
所有文档都必须带 schemaVersion，反序列化时先校验，再按版本逐步迁移。文档 JSON 中不能保存函数、DOM 节点或运行时对象。
|
||
|
||
## 4. 包职责
|
||
|
||
### 4.1 report-core
|
||
|
||
- 报表文档模型。
|
||
- 页面、区域、元素和样式模型。
|
||
- 数据源、数据集、参数契约。
|
||
- 插件契约和注册表。
|
||
- 文档创建、克隆、规范化。
|
||
- 序列化、反序列化、校验和迁移。
|
||
|
||
### 4.2 report-expression
|
||
|
||
- 表达式词法和语法解析。
|
||
- AST 和受限求值器。
|
||
- 字段、参数、行、分组和页面作用域。
|
||
- 表达式错误和诊断信息。
|
||
|
||
禁止通过 eval 或 new Function 执行任意 JavaScript。
|
||
|
||
### 4.3 report-layout
|
||
|
||
- 元素尺寸测量。
|
||
- 文本换行和动态高度。
|
||
- 明细数据展开。
|
||
- 分页和分页诊断。
|
||
- 生成统一的 LayoutDocument。
|
||
|
||
Layout 通过 TextMeasurer、FontResolver 等接口获得环境能力，不直接依赖 DOM。
|
||
|
||
### 4.4 report-renderer
|
||
|
||
- 消费 LayoutDocument。
|
||
- 提供 HTML、SVG 和 PDF Renderer。
|
||
- 处理目标格式相关的颜色、字体和资源输出。
|
||
|
||
PDF 的具体实现可以运行在浏览器或 Node/服务端，但必须遵循统一的 Renderer 接口。
|
||
|
||
### 4.5 report-designer
|
||
|
||
- 画布和坐标转换。
|
||
- 选择、拖拽、缩放、对齐和吸附。
|
||
- 属性编辑。
|
||
- 复制粘贴。
|
||
- 命令、事务和撤销重做。
|
||
- 快捷键和编辑器状态。
|
||
|
||
Designer 通过 Core 的命令接口修改文档，不直接实现报表业务规则。
|
||
|
||
### 4.6 report-designer-vue
|
||
|
||
只负责 Vue 组件、面板和 UI 适配，不向 Core 泄漏 Vue 类型。
|
||
|
||
## 5. report-core 目录
|
||
|
||
~~~text
|
||
packages/report-core/
|
||
│
|
||
├── src/
|
||
│ ├── model/
|
||
│ │ ├── report.ts
|
||
│ │ ├── page.ts
|
||
│ │ ├── section.ts
|
||
│ │ ├── element.ts
|
||
│ │ ├── table.ts
|
||
│ │ ├── style.ts
|
||
│ │ ├── dataset.ts
|
||
│ │ ├── datasource.ts
|
||
│ │ ├── parameter.ts
|
||
│ │ └── common.ts
|
||
│ │
|
||
│ ├── plugin/
|
||
│ │ ├── plugin.ts
|
||
│ │ ├── context.ts
|
||
│ │ ├── registry.ts
|
||
│ │ ├── element-plugin.ts
|
||
│ │ ├── datasource-plugin.ts
|
||
│ │ └── exporter-plugin.ts
|
||
│ │
|
||
│ ├── document/
|
||
│ │ ├── create.ts
|
||
│ │ ├── clone.ts
|
||
│ │ └── normalize.ts
|
||
│ │
|
||
│ ├── serialization/
|
||
│ │ ├── serialize.ts
|
||
│ │ ├── deserialize.ts
|
||
│ │ └── migrate.ts
|
||
│ │
|
||
│ ├── schema/
|
||
│ │ ├── version.ts
|
||
│ │ ├── defaults.ts
|
||
│ │ └── validation.ts
|
||
│ │
|
||
│ ├── diagnostics/
|
||
│ │ └── diagnostic.ts
|
||
│ ├── utils/
|
||
│ │ ├── id.ts
|
||
│ │ └── deep.ts
|
||
│ └── index.ts
|
||
│
|
||
└── tests/
|
||
~~~
|
||
|
||
## 6. Report 文档模型
|
||
|
||
报表采用“文档 + 区域 + 元素树”模型，不把所有元素平铺在根节点上。
|
||
|
||
~~~ts
|
||
export interface ReportDocument {
|
||
schemaVersion: number
|
||
|
||
id: string
|
||
name: string
|
||
|
||
page: PageSettings
|
||
|
||
styles: Record<string, StyleDefinition>
|
||
|
||
dataSources: Record<string, DataSourceDefinition>
|
||
datasets: Record<string, DatasetDefinition>
|
||
parameters: Record<string, ReportParameter>
|
||
|
||
sections: ReportSection[]
|
||
|
||
plugins?: ReportPluginReference[]
|
||
metadata?: ReportMetadata
|
||
}
|
||
~~~
|
||
|
||
### 6.1 报表区域
|
||
|
||
~~~ts
|
||
export type ReportSectionKind =
|
||
| "report-header"
|
||
| "page-header"
|
||
| "detail"
|
||
| "group-header"
|
||
| "group-footer"
|
||
| "summary"
|
||
| "page-footer"
|
||
|
||
export interface ReportSection {
|
||
id: string
|
||
kind: ReportSectionKind
|
||
|
||
datasetId?: string
|
||
children: ReportElement[]
|
||
|
||
options?: {
|
||
repeatOnEachPage?: boolean
|
||
keepTogether?: boolean
|
||
allowSplit?: boolean
|
||
}
|
||
}
|
||
~~~
|
||
|
||
V1 先实现 page-header、detail 和 page-footer，其他区域只保留模型扩展点。
|
||
|
||
> 实现进度：group-header / group-footer 已可用（含多级分组与组内聚合）。
|
||
> report-header 与 summary 仍只保留模型扩展点。
|
||
>
|
||
> 分组区域通过 `groupExpression` 指定分组键，`groupLevel` 指定嵌套级别：
|
||
>
|
||
> ~~~ts
|
||
> export interface ReportSection {
|
||
> // ...原有字段
|
||
> /** 分组键表达式，仅 group-header / group-footer 使用。 */
|
||
> groupExpression?: string
|
||
> /** 分组级别，从 1 开始；数值小的为外层组。 */
|
||
> groupLevel?: number
|
||
> }
|
||
> ~~~
|
||
>
|
||
> 分组语义为「**相邻行键值相同即同组**」，不改变行顺序——
|
||
> 因此宿主应先按分组键排序再传入数据。组脚可通过 `group` 作用域访问
|
||
> 聚合能力，如 `sum(group.amount)`、`group.count`、`group.key`。
|
||
|
||
### 6.2 元素树
|
||
|
||
~~~ts
|
||
export interface ReportElement {
|
||
id: string
|
||
type: string
|
||
|
||
frame: Rect
|
||
styleId?: string
|
||
|
||
binding?: ValueBinding
|
||
props?: Record<string, unknown>
|
||
children?: ReportElement[]
|
||
}
|
||
|
||
export interface Rect {
|
||
x: number
|
||
y: number
|
||
width: number
|
||
height: number
|
||
}
|
||
|
||
export interface ValueBinding {
|
||
field?: string
|
||
expression?: string
|
||
format?: string
|
||
}
|
||
~~~
|
||
|
||
内置元素初期包括：
|
||
|
||
~~~text
|
||
text
|
||
image
|
||
line
|
||
rect
|
||
container
|
||
table
|
||
~~~
|
||
|
||
插件元素使用自定义 type，并通过插件 Schema 验证 props。
|
||
|
||
### 6.3 明细表
|
||
|
||
明细表是 V1 的特殊元素，负责把数据集展开成多行。单元格内的元素坐标相对于当前单元格。
|
||
|
||
~~~ts
|
||
export interface TableElement extends ReportElement {
|
||
type: "table"
|
||
datasetId: string
|
||
columns: TableColumn[]
|
||
repeatHeaderOnEachPage?: boolean
|
||
}
|
||
|
||
export interface TableColumn {
|
||
id: string
|
||
width: number
|
||
header?: string
|
||
binding?: ValueBinding
|
||
children?: ReportElement[]
|
||
}
|
||
~~~
|
||
|
||
### 6.4 样式
|
||
|
||
样式通过 ID 复用，并允许有限的继承和元素级覆盖：
|
||
|
||
~~~ts
|
||
export interface StyleDefinition {
|
||
id: string
|
||
extends?: string
|
||
fontFamily?: string
|
||
fontSize?: number
|
||
color?: string
|
||
background?: string
|
||
border?: BorderStyle
|
||
align?: "left" | "center" | "right"
|
||
verticalAlign?: "top" | "middle" | "bottom"
|
||
}
|
||
~~~
|
||
|
||
## 7. Page 模型
|
||
|
||
V1 文档内部统一使用 mm，px 只用于 Designer 显示层，pt 只在 PDF 等输出边界转换。
|
||
|
||
~~~ts
|
||
export interface PageSettings {
|
||
paper: "A4" | "A5" | "custom"
|
||
orientation: "portrait" | "landscape"
|
||
|
||
customSize?: {
|
||
width: number
|
||
height: number
|
||
}
|
||
|
||
margin: PageMargin
|
||
background?: string
|
||
}
|
||
|
||
export interface PageMargin {
|
||
top: number
|
||
right: number
|
||
bottom: number
|
||
left: number
|
||
}
|
||
~~~
|
||
|
||
paper 和 orientation 是页面配置来源；Layout 阶段将其解析为最终的 width、height。自定义纸张必须提供尺寸，尺寸均以 mm 表示。
|
||
|
||
## 8. 数据和运行时上下文
|
||
|
||
报表文档只保存数据源定义，不保存连接、Token 和本次查询结果。
|
||
|
||
~~~ts
|
||
export interface DataSourceDefinition {
|
||
id: string
|
||
type: string
|
||
config?: Record<string, unknown>
|
||
connectionRef?: string
|
||
}
|
||
|
||
export interface DatasetDefinition {
|
||
id: string
|
||
sourceId?: string
|
||
fields?: DatasetField[]
|
||
query?: string
|
||
}
|
||
|
||
export interface RenderContext {
|
||
data: Record<string, unknown>
|
||
parameters: Record<string, unknown>
|
||
locale?: string
|
||
timezone?: string
|
||
}
|
||
|
||
export interface DataProvider {
|
||
getDataset(
|
||
dataset: DatasetDefinition,
|
||
context: RenderContext
|
||
): Promise<ReadonlyArray<Record<string, unknown>>>
|
||
}
|
||
~~~
|
||
|
||
DataProvider 由宿主应用注入，Core 不主动访问网络或数据库。
|
||
config 只保存非敏感的设计配置；连接密码、Token 等敏感信息必须通过 connectionRef 或宿主运行时注入。
|
||
|
||
## 9. Layout 中间结果
|
||
|
||
Layout Engine 接受报表文档和运行时上下文，输出所有 Renderer 共用的分页结果。
|
||
|
||
~~~ts
|
||
export interface LayoutOptions {
|
||
dataProvider?: DataProvider
|
||
textMeasurer: TextMeasurer
|
||
fontResolver: FontResolver
|
||
}
|
||
|
||
export interface LayoutEngine {
|
||
layout(
|
||
document: ReportDocument,
|
||
context: RenderContext,
|
||
options?: LayoutOptions
|
||
): Promise<LayoutDocument>
|
||
}
|
||
|
||
export interface LayoutDocument {
|
||
pages: LayoutPage[]
|
||
diagnostics: LayoutDiagnostic[]
|
||
}
|
||
|
||
export interface LayoutPage {
|
||
width: number
|
||
height: number
|
||
nodes: LayoutNode[]
|
||
}
|
||
|
||
export interface LayoutNode {
|
||
id: string
|
||
type: string
|
||
frame: Rect
|
||
style: ResolvedStyle
|
||
content?: unknown
|
||
children?: LayoutNode[]
|
||
}
|
||
~~~
|
||
|
||
Layout 必须支持以下接口：
|
||
|
||
~~~ts
|
||
export interface TextMeasurer {
|
||
measure(text: string, style: ResolvedStyle): TextMetrics
|
||
}
|
||
|
||
export interface FontResolver {
|
||
resolve(fontFamily: string): ResolvedFont
|
||
}
|
||
~~~
|
||
|
||
这样可以分别适配浏览器、Node 和服务端字体环境，同时让分页逻辑保持独立。
|
||
|
||
## 10. 表达式约定
|
||
|
||
表达式系统使用受限语法和 AST，不执行任意 JavaScript。
|
||
|
||
V1 至少支持：
|
||
|
||
~~~text
|
||
字段：row.amount
|
||
参数：params.customerName
|
||
简单运算：row.price * row.quantity
|
||
条件：if(row.amount > 0, "有", "无")
|
||
格式化：format(row.date, "YYYY-MM-DD")
|
||
~~~
|
||
|
||
表达式失败时返回带有元素 ID 和表达式内容的诊断信息，单个字段错误不应导致整个文档无结果。
|
||
|
||
## 11. 插件模型
|
||
|
||
插件只通过契约接入，不允许 Core 直接导入插件实现。
|
||
|
||
~~~ts
|
||
export interface ReportPlugin {
|
||
id: string
|
||
version: string
|
||
elements?: ElementPlugin[]
|
||
datasources?: DataSourcePlugin[]
|
||
exporters?: ExporterPlugin[]
|
||
}
|
||
|
||
export interface ElementPlugin {
|
||
type: string
|
||
schema: unknown
|
||
createDefault(): ReportElement
|
||
}
|
||
~~~
|
||
|
||
需要针对不同运行环境提供可选适配器：
|
||
|
||
~~~text
|
||
ElementPlugin
|
||
├── LayoutAdapter
|
||
├── RendererAdapter（html/svg/pdf）
|
||
└── DesignerAdapter
|
||
~~~
|
||
|
||
插件引用只保存 id、version 和配置。插件缺失时应产生诊断信息，而不是阻止整个文档被读取。
|
||
|
||
## 12. 序列化、校验和迁移
|
||
|
||
- schemaVersion 使用单调递增整数。
|
||
- 反序列化顺序为：解析 JSON → 校验结构 → 执行迁移 → 规范化默认值。
|
||
- 迁移函数按版本逐步执行，不允许跨版本直接修改内部对象。
|
||
- 序列化结果保持稳定排序，便于版本控制和差异比较。
|
||
- 校验错误必须指出字段路径和元素 ID。
|
||
|
||
示例：
|
||
|
||
~~~text
|
||
deserialize(json)
|
||
→ validate(json)
|
||
→ migrate(json, currentVersion)
|
||
→ normalize(document)
|
||
~~~
|
||
|
||
## 13. 诊断和错误处理
|
||
|
||
统一使用诊断对象表达警告和错误：
|
||
|
||
~~~ts
|
||
export interface Diagnostic {
|
||
severity: "info" | "warning" | "error"
|
||
code: string
|
||
message: string
|
||
path?: string
|
||
elementId?: string
|
||
}
|
||
~~~
|
||
|
||
数据缺失、表达式错误、字体缺失、插件缺失和分页失败都应尽量返回可定位的诊断信息。
|
||
|
||
## 14. UI 规范
|
||
|
||
### 14.1 设计目标
|
||
|
||
Designer 的界面采用现代、简洁、干净的工具型产品风格，参考 shadcn/ui 的设计语言，但不要求 Core 或业务应用必须绑定某一个 UI 框架。
|
||
|
||
核心原则：
|
||
|
||
- 画布优先，减少非必要装饰。
|
||
- 使用中性背景、细边框和低强度阴影建立层次。
|
||
- 通过间距、字号和颜色层级表达信息，不依赖渐变和大面积高亮。
|
||
- 常用操作保持短路径，复杂配置分组收起。
|
||
- 所有颜色、间距、圆角和阴影使用设计令牌，禁止组件内散落硬编码。
|
||
|
||
### 14.2 UI 层边界
|
||
|
||
- report-core 不包含任何 UI、CSS 或主题代码。
|
||
- report-designer 负责编辑器状态、命令和交互行为。
|
||
- report-designer-vue 负责 Vue 组件、面板和样式实现。
|
||
- 组件采用 Headless 思路，宿主应用可以覆盖主题和品牌色。
|
||
- 可以使用 shadcn-vue 或同类组件实现，但必须通过 report-designer-vue 隔离依赖。
|
||
|
||
### 14.3 整体布局
|
||
|
||
桌面端采用三栏、画布居中的工作区：
|
||
|
||
~~~text
|
||
┌──────────────────────────────────────────────────────────────┐
|
||
│ 顶部工具栏：文件、撤销、重做、预览、保存、缩放、主题 │
|
||
├──────────────┬───────────────────────────────┬───────────────┤
|
||
│ 左侧工具箱 │ │ 右侧属性面板 │
|
||
│ 元素 / 数据 │ 报表画布 │ 属性 / 样式 │
|
||
│ 模板 / 图层 │ │ 数据绑定 │
|
||
├──────────────┴───────────────────────────────┴───────────────┤
|
||
│ 底部状态栏：页码、缩放、单位、布局诊断、快捷键提示 │
|
||
└──────────────────────────────────────────────────────────────┘
|
||
~~~
|
||
|
||
建议尺寸：
|
||
|
||
- 左侧工具箱：240px 左右，可折叠。
|
||
- 右侧属性面板：320px 左右，可折叠。
|
||
- 顶部工具栏：48px。
|
||
- 底部状态栏：28px。
|
||
- 中间画布区域自适应，并支持拖拽调整两侧面板宽度。
|
||
|
||
屏幕宽度小于 900px 时，侧栏改为抽屉或浮层；移动端优先保证预览和基础属性编辑，不强行复刻完整桌面编辑器。
|
||
|
||
### 14.4 设计令牌
|
||
|
||
使用 CSS 自定义属性作为主题契约，至少提供亮色和暗色两套主题：
|
||
|
||
~~~css
|
||
:root {
|
||
--rd-background: 0 0% 100%;
|
||
--rd-foreground: 222 47% 11%;
|
||
--rd-muted: 210 40% 96%;
|
||
--rd-muted-foreground: 215 16% 47%;
|
||
--rd-border: 214 32% 91%;
|
||
--rd-input: 214 32% 91%;
|
||
--rd-primary: 221 83% 53%;
|
||
--rd-primary-foreground: 210 40% 98%;
|
||
--rd-destructive: 0 72% 51%;
|
||
--rd-canvas: 220 14% 96%;
|
||
--rd-selection: 221 83% 53%;
|
||
--rd-radius: 8px;
|
||
}
|
||
~~~
|
||
|
||
具体色值可以由宿主应用覆盖，但必须保持以下语义：
|
||
|
||
- background：应用和面板背景。
|
||
- canvas：画布工作区背景。
|
||
- foreground：主要文字和图标。
|
||
- muted：次级区域和禁用背景。
|
||
- border：分隔线和输入框边框。
|
||
- primary：主操作、选中态和焦点环。
|
||
- destructive：删除和不可逆操作。
|
||
- selection：画布元素选中框和辅助线。
|
||
|
||
推荐使用 OKLCH 或 HSL 变量，不在组件中直接写十六进制颜色。
|
||
|
||
### 14.5 字体和间距
|
||
|
||
~~~css
|
||
font-family: Inter, -apple-system, BlinkMacSystemFont, "Segoe UI",
|
||
"PingFang SC", "Microsoft YaHei", sans-serif;
|
||
~~~
|
||
|
||
推荐字号：12px（辅助信息）、13px（表单和工具栏）、14px（正文）、16px（小标题）、20px（页面标题）。
|
||
|
||
间距使用 4px 基准：4、8、12、16、20、24、32px。默认圆角 6~8px，面板阴影保持低强度，避免卡片堆叠感。
|
||
|
||
### 14.6 基础组件风格
|
||
|
||
基础组件遵循扁平、克制、可聚焦的风格：
|
||
|
||
- Button：Primary、Secondary、Ghost、Destructive、Icon 五类。
|
||
- Input、Textarea、Select、Combobox：1px 边框，聚焦时显示明显但克制的 focus ring。
|
||
- Tabs、Segmented Control：用于属性面板和视图切换。
|
||
- Popover、Tooltip、Context Menu、Command Menu：用于低频和快捷操作。
|
||
- Dialog、Toast、Alert：用于确认、反馈和错误提示。
|
||
- Resizable Panel：用于左右侧栏和属性面板。
|
||
|
||
按钮不使用过度圆润的胶囊形，图标按钮必须提供 Tooltip 和可访问名称。删除等危险操作不能只依赖颜色区分。
|
||
|
||
### 14.7 画布规范
|
||
|
||
- 工作区使用浅灰或深灰中性背景，页面使用白色或主题纸张颜色。
|
||
- 页面保持轻微阴影和清晰边界，不使用强烈投影。
|
||
- 元素 Hover 使用低透明度背景，Selected 使用 1px 主色边框和 8 个缩放控制点。
|
||
- 对齐线、吸附线和标尺使用辅助色，不遮挡元素内容。
|
||
- 支持 50%、75%、100%、125%、150%、200% 常用缩放。
|
||
- 画布操作同时支持鼠标、键盘和上下文菜单，不把拖拽作为唯一入口。
|
||
- 选中态、错误态和辅助线不能只通过颜色表达，必要时增加边框、图标或文字提示。
|
||
|
||
### 14.8 属性面板规范
|
||
|
||
- 按“布局、内容、样式、数据绑定、高级”分组。
|
||
- 分组默认折叠低频配置，保留最近使用状态。
|
||
- 数值输入显示单位，支持键盘微调和批量修改。
|
||
- 绑定字段提供字段选择器，同时允许直接输入表达式。
|
||
- 无选中元素时显示页面属性；多选时只显示共同属性。
|
||
- 表单错误就地显示，并关联到对应字段，不使用只在底部出现的泛化错误。
|
||
|
||
### 14.9 交互和状态
|
||
|
||
顶部工具栏至少提供：
|
||
|
||
- 新建、打开、保存。
|
||
- 撤销、重做。
|
||
- 预览、打印。
|
||
- 缩放和适应页面。
|
||
- 主题切换和帮助入口。
|
||
|
||
推荐快捷键：Ctrl/Cmd + S 保存、Ctrl/Cmd + Z 撤销、Ctrl/Cmd + Shift + Z 重做、Delete 删除、Ctrl/Cmd + C/V 复制粘贴、Ctrl/Cmd + K 打开命令菜单。
|
||
|
||
所有异步操作都要有 Loading、Empty、Error 和 Disabled 状态；保存成功、布局警告和表达式错误使用统一 Toast 或诊断面板反馈。
|
||
|
||
### 14.10 主题、密度和无障碍
|
||
|
||
- 默认提供 Light 和 Dark 两套主题。
|
||
- 支持 Standard 和 Compact 两种密度，默认 Standard。
|
||
- 颜色对比度目标达到 WCAG AA，正文至少 4.5:1。
|
||
- 所有交互控件支持键盘访问，焦点状态必须可见。
|
||
- 弹窗、抽屉、菜单和属性面板提供正确的 ARIA 语义。
|
||
- 点击目标不小于 32px，主要触控目标建议不小于 36px。
|
||
- 尊重 prefers-reduced-motion，避免非必要动画。
|
||
|
||
### 14.11 UI 验收标准
|
||
|
||
初期 UI 至少应满足：
|
||
|
||
1. 用户可以在不阅读文档的情况下找到新增元素、保存、预览和撤销操作。
|
||
2. 画布、工具箱和属性面板在亮色和暗色主题下都能正常使用。
|
||
3. 选中、禁用、错误、加载和空状态具有一致的视觉语言。
|
||
4. 关键操作可以只使用键盘完成。
|
||
5. 主题颜色可以由宿主应用通过 CSS 变量覆盖。
|
||
|
||
## 15. 测试策略
|
||
|
||
初期至少建立以下测试：
|
||
|
||
- √ 文档 Schema、默认值和版本迁移测试。
|
||
- √ 固定元素和明细表的布局快照测试。
|
||
- √ 页眉、页脚和多页分页测试。
|
||
- HTML、SVG、PDF Renderer 的公共布局结果一致性测试。
|
||
- √ 表达式安全性、空值和类型转换测试。
|
||
- √ 中文字体、长文本和自定义纸张测试。
|
||
- √ 插件缺失和插件版本不兼容测试。
|
||
|
||
建议准备一个固定的示例报表作为跨包契约测试数据。
|
||
|
||
> 当前测试规模：`report-core` 139 例、`report-expression` 111 例、
|
||
> `report-layout` 124 例、`report-renderer` 12 例、`report-designer` 14 例、
|
||
> `report-designer-vue` 11 例，合计 **411** 例。
|
||
> 字体相关用例依赖系统字体，在缺少字体的环境中自动跳过。
|
||
> HTML/SVG 分页一致性测试已随 Renderer 实现补齐。
|
||
|
||
## 16. 初期实施顺序
|
||
|
||
> 进度标记说明：`√` 表示已实现并有测试覆盖；`◐` 表示部分实现；未标记表示尚未开始。
|
||
>
|
||
> 当前进度：阶段 1、2、3 已完成；阶段 4 主体完成（Renderer、Designer 核心、
|
||
> Vue UI 骨架），Vue 层的图层面板、数据绑定面板、快捷键留待后续迭代。
|
||
|
||
### √ 阶段 1：Core 和文档模型
|
||
|
||
- √ 完成 ReportDocument、Section、Element、Page、Style。
|
||
- √ 完成默认值、校验、序列化和迁移。
|
||
- √ 完成基础命令和 ID 生成。
|
||
|
||
产物：`packages/report-core`（139 个测试用例）。
|
||
|
||
### √ 阶段 2：基础 Layout
|
||
|
||
- √ 完成单页固定元素布局。
|
||
- √ 完成文本测量、换行和基础分页。
|
||
- √ 输出统一的 LayoutDocument。
|
||
|
||
产物：`packages/report-layout`（含自研 TTF/TTC 字体度量解析）。
|
||
|
||
### √ 阶段 3：数据和明细表
|
||
|
||
- √ 接入 RenderContext 和 DataProvider。
|
||
- √ 支持字段绑定、简单表达式和明细表展开。
|
||
- √ 支持页眉、页脚重复。
|
||
|
||
产物：`packages/report-expression`（83+28 个测试用例）、`packages/report-layout` 的
|
||
数据绑定与分组能力。
|
||
|
||
补充实现（超出本阶段原始列项）：
|
||
|
||
- √ 受限表达式系统（字段、参数、运算、条件、格式化）。
|
||
- √ 聚合函数（sum / avg / count / min / max）。
|
||
- √ 基础分组（group-header / group-footer、多级分组、组内聚合）。
|
||
- √ 明细表表头每页重复。
|
||
|
||
### ◐ 阶段 4：Renderer 和 Designer
|
||
|
||
- √ 实现 SVG、HTML 和浏览器打印（`@report/renderer`，含 HTML/SVG 分页一致性测试）。
|
||
- √ 实现 PDF Renderer 契约（可注入 `PdfBackend`，缺失/报错走诊断）。
|
||
- √ 完成 Designer 的选择、拖拽、属性编辑和撤销重做（`@report/designer`，纯逻辑层）。
|
||
- √ Vue 层 UI 骨架（`@report/designer-vue`，原生 Vue3 + Vite 库模式，无第三方组件库）：
|
||
三栏布局壳、画布（渲染/选中/新增）、工具栏（撤销重做/缩放）、属性面板（基础编辑）、
|
||
状态栏、设计令牌（亮/暗主题 CSS 变量）。
|
||
- 待后续迭代：图层面板、数据绑定面板、拖拽移动、快捷键、预览接入 Renderer。
|
||
|
||
### 阶段 5：插件和 PDF
|
||
|
||
- 实现二维码、条码等独立插件。
|
||
- 根据部署环境确定 PDF 的具体后端。
|
||
- 补充字体、资源和输出一致性测试。
|
||
|
||
## 17. V1 验收标准
|
||
|
||
一个示例报表应当能够：
|
||
|
||
1. 在 Designer 中创建并保存。
|
||
2. 绑定一组运行时数据。
|
||
3. 生成包含页眉、明细和页脚的多页结果。
|
||
4. 在 HTML 和 SVG 中得到相同的分页结构。
|
||
5. 通过浏览器打印输出。
|
||
6. 在升级 Schema 后仍可被迁移和读取。
|
||
|
||
达到以上标准后，再继续扩展复杂分组、图表、PDF 和更多插件。
|