x-print-designer 0.0.3 → 0.0.5

package/README.md

@@ -1,6 +1,6 @@
 # X-Print-Designer
 
-基于 Vue 3 + TypeScript 开发的打印设计器，支持可视化拖拽设计打印模板，集成 ECharts 图表组件，提供模板模式与报告模式两种工作方式。
+基于 Vue 3 + TypeScript 开发的打印设计器，支持可视化拖拽设计打印模板，集成 ECharts 图表组件。
 
 ---
 
@@ -8,11 +8,15 @@
 
 - [核心概念：模板模式 vs 报告模式](#核心概念模板模式-vs-报告模式)
 - [快速开始](#快速开始)
+- [Vue 组件使用说明](#vue-组件使用说明)
+- [Web Component 使用说明](#web-component-使用说明)
 - [传入数据格式](#传入数据格式)
-- [支持的元素类型](#支持的元素类型)
-- [数据绑定方式](#数据绑定方式)
-- [测试数据](#测试数据)
+- [保存回调 `onSave`](#保存回调-onsave)
+- [自动保存配置](#自动保存配置)
+- [模板数据结构（完整格式）](#模板数据结构完整格式)
+- [元素数据绑定](#元素数据绑定)
 - [变量语法参考](#变量语法参考)
+- [支持的元素类型](#支持的元素类型)
 - [技术栈](#技术栈)
 
 ---
@@ -21,103 +25,36 @@
 
 设计器支持两种工作模式，通过 `mode` 属性/方法进行切换。
 
-### 模板模式（template）— 默认模式
-
-**适用场景：** 创建可复用的打印模板，模板与数据分离。先在设计器中画好布局，打印时再填入真实数据。
-
-**保存行为：**
-- 保存时**只保存页面布局信息**（元素位置、样式、画布大小、参考线等）
-- **不保存**测试数据（`testData`）
+### 模板模式（`template`）— 默认模式
 
-**典型工作流：**
-1. 在设计器中拖拽元素，设计打印模板的布局
-2. 使用变量语法（如 `{#orderNo}`）标记数据占位符
-3. 保存模板，模板只包含布局结构
-4. 业务系统调用打印/导出时，传入真实数据替换变量
+**适用场景：** 创建可复用的打印模板，模板与数据分离。布局固定，数据在打印时动态注入。
 
-**保存的数据结构：**
+- 保存时**只保存页面布局**（元素位置、样式、画布大小等）
+- **不保存** `testData`（测试数据）
 
-```json
-{
-  "pages": [ /* 页面和元素列表 */ ],
-  "canvasSize": { "width": 794, "height": 1123 },
-  "guides": [],
-  "zoom": 1,
-  "showGrid": true,
-  "headerHeight": 0,
-  "footerHeight": 0,
-  "watermark": { "enabled": false, "text": "", "angle": -30, "color": "#000000", "opacity": 0.1, "size": 24, "density": 160 },
-  "unit": "mm",
-  "pageSpacingX": 0,
-  "pageSpacingY": 0,
-  "canvasBackground": "#ffffff"
-}
-```
+### 报告模式（`report`）
 
-### 报告模式（report）
+**适用场景：** 数据与布局绑定在一起的完整报告（如检测报告、统计报表）。
 
-**适用场景：** 创建包含数据的完整报告，布局和数据一起保存。适用于需要将模板和示例数据打包存储的场景。
+- 保存时**同时保存页面布局 + 测试数据**（`testData`）
 
-**保存行为：**
-- 保存时**同时保存页面布局信息和测试数据**（`testData`）
-- `testData` 中包含当前设计器中填写/导入的测试数据
+### 对比
 
-**典型工作流：**
-1. 在设计器中拖拽元素，设计报告布局
-2. 通过 API 或界面导入测试数据
-3. 保存报告，布局和数据一起持久化
-4. 加载报告时，布局和测试数据一起恢复
+| 特性 | `template` | `report` |
+|------|-----------|----------|
+| 保存布局 | ✅ | ✅ |
+| 保存 testData | ❌ | ✅ |
+| 典型用途 | 订单打印、标签 | 检测报告、报表 |
 
-**保存的数据结构（与模板模式的区别）：**
-
-```json
-{
-  "pages": [ /* ... */ ],
-  "canvasSize": { "width": 794, "height": 1123 },
-  "watermark": { /* ... */ },
-  "testData": {
-    "orderNo": "A001",
-    "customerName": "张三",
-    "items": [
-      { "name": "产品A", "price": 100, "quantity": 2 }
-    ]
-  }
-}
-```
-
-### 对比总结
-
-| 特性 | 模板模式 (template) | 报告模式 (report) |
-|------|-------------------|------------------|
-| 保存布局 | ✅ 是 | ✅ 是 |
-| 保存测试数据 (`testData`) | ❌ 否 | ✅ 是 |
-| 适用场景 | 通用打印模板 | 数据+布局一体的报告 |
-| 数据注入时机 | 打印/导出时传入 | 设计时即绑定 |
-| 典型用途 | 订单打印、标签打印 | 检测报告、统计报表 |
-
-### 如何切换模式
-
-**Vue 组件方式：**
+### 切换模式
 
 ```vue
-<template>
-  <!-- 模板模式（默认） -->
-  <PrintDesigner mode="template" />
-  
-  <!-- 报告模式 -->
-  <PrintDesigner mode="report" />
-</template>
+<PrintDesigner mode="template" />
+<PrintDesigner mode="report" />
 ```
 
-**Web Component 方式：**
-
 ```js
-const designer = document.querySelector('print-designer');
-
-// 切换为模板模式（默认）
 designer.setMode('template');
-
-// 切换为报告模式
 designer.setMode('report');
 ```
 
@@ -125,43 +62,100 @@ designer.setMode('report');
 
 ## 快速开始
 
-### 安装
-
 ```bash
 npm install
 npm run dev
 ```
 
-### Vue 组件方式
+### 最简接入
 
 ```vue
 <template>
   <PrintDesigner
     mode="template"
     :sample-data="sampleData"
+    :on-save="handleSave"
   />
 </template>
 
 <script setup>
 import { ref } from 'vue';
-import PrintDesigner from './components/PrintDesigner.vue';
+import PrintDesigner from '@/components/PrintDesigner.vue';
 
 const sampleData = ref({
   id: 1,
   name: '测试报告',
+  templateId: 'tpl_001',
   variables: {
     title: '报告标题',
     customerName: '张三',
     items: [
-      { name: '产品A', price: 100, quantity: 2 },
-      { name: '产品B', price: 200, quantity: 3 }
+      { name: '产品A', price: 100, quantity: 2 }
     ]
   }
 });
+
+const handleSave = (payload) => {
+  console.log('保存数据:', payload);
+  // { id: '...', name: '测试报告', data: {...}, isNew: false }
+  // 用户自行调用接口保存
+};
 </script>
 ```
 
-### Web Component 方式
+---
+
+## Vue 组件使用说明
+
+### 组件 Props 一览
+
+| 属性 | 类型 | 默认值 | 说明 |
+|------|------|--------|------|
+| `mode` | `'template'` \| `'report'` | `'template'` | 工作模式 |
+| `sample-data` | `object` | — | 传入的示例数据 |
+| `on-save` | `(payload) => void \| Promise<void>` | — | 保存回调，详见下方 |
+| `auto-save-enabled` | `boolean` | `false` | 是否开启定时自动保存 |
+| `auto-save-interval-ms` | `number` | `120000` | 自动保存间隔（毫秒），默认 2 分钟 |
+
+### Props 详细说明
+
+#### `mode`
+
+工作模式。`'template'` 保存时只存布局，`'report'` 保存时同时存布局和 testData。
+
+```vue
+<PrintDesigner mode="report" />
+```
+
+#### `sample-data`
+
+传入设计器的示例数据。**最关键的属性**。详见下方 [传入数据格式](#传入数据格式)。
+
+```vue
+<PrintDesigner :sample-data="{ id: 1, name: '报告', variables: {...} }" />
+```
+
+#### `on-save`
+
+保存回调函数。当用户点击保存按钮（或自动保存触发）时，设计器组装好数据后调用此回调，**不再自动调接口**，完全交由用户自行处理。
+
+```vue
+<PrintDesigner :on-save="(payload) => fetch('/api/save', { method: 'POST', body: JSON.stringify(payload) })" />
+```
+
+#### `auto-save-enabled`
+
+是否开启定时自动保存。开启后每隔 `auto-save-interval-ms` 毫秒自动触发 `on-save` 回调。详见 [自动保存配置](#自动保存配置)。
+
+#### `auto-save-interval-ms`
+
+自动保存间隔时间（毫秒），默认 `120000`（2 分钟）。
+
+---
+
+## Web Component 使用说明
+
+### 标签方式
 
 ```html
 <print-designer id="designer"></print-designer>
@@ -169,131 +163,272 @@ const sampleData = ref({
 <script>
   const designer = document.getElementById('designer');
 
-  // 设置模式
   designer.setMode('template');
-
-  // 设置测试数据
-  designer.setTestData({
-    orderNo: 'ORD-001',
-    customerName: '张三',
-    items: [
-      { name: '产品A', price: 100, quantity: 2 }
-    ]
+  designer.setOnSave((payload) => {
+    fetch('/api/save', { method: 'POST', body: JSON.stringify(payload) });
   });
-
-  // 设置模板列表
-  designer.setTemplates([
-    {
-      id: 'tpl-1',
-      name: 'A4 打印模板',
-      data: {
-        pages: [],
-        canvasSize: { width: 794, height: 1123 },
-        unit: 'mm'
-      }
-    }
-  ], { currentTemplateId: 'tpl-1' });
+  designer.setAutoSave(true, 120000);
+  designer.setTestData({ orderNo: 'ORD-001', items: [...] });
 </script>
 ```
 
+### API 速览
+
+| 方法 | 说明 |
+|------|------|
+| `setMode(mode)` | 设置模式：`'template'` / `'report'` |
+| `setOnSave(handler)` | 设置保存回调 |
+| `setAutoSave(enabled, intervalMs?)` | 开启/关闭自动保存 |
+| `setTestData(data)` | 设置测试数据 |
+| `setVariables(vars)` | 打印/导出时注入真实变量 |
+| `setTemplates(list, opts)` | 设置模板列表 |
+| `loadTemplate(id)` | 加载指定模板到画布 |
+| `print(request)` | 执行打印 |
+| `export(request)` | 导出 PDF/图片/HTML |
+
+### 打印时注入真实数据
+
+```js
+const designer = document.querySelector('print-designer');
+
+await designer.loadTemplate('tpl-order');
+
+designer.setVariables({
+  orderNo: 'REAL-2026-001',
+  customerName: '李四',
+  totalAmount: 5999.00
+});
+
+await designer.print({ mode: 'browser', options: { silent: true } });
+```
+
 ---
 
 ## 传入数据格式
 
-### 1. 通过 `sample-data` 属性传入（Vue 组件方式）
+数据以 **扁平键值对** 形式传入，所有字段在根级别，在模板中通过 `@变量名` 或 `{#变量名}` 直接引用。
 
-使用 `PrintDesigner` 组件时，通过 `sample-data` 属性传入示例数据，用于设计器中的数据绑定预览：
+### `sample-data` 字段说明
 
-```vue
-<template>
-  <PrintDesigner :sample-data="sampleData" />
-</template>
+| 字段 | 类型 | 必填 | 说明 |
+|------|------|------|------|
+| `id` | `number` / `string` | 是 | **业务数据的 ID**，如报告 ID、订单 ID |
+| `templateId` | `string` | 否 | 加载的打印模板 ID，不传则用当前已选模板 |
+| `name` | `string` | 否 | 数据名称，如报告标题、订单名称 |
+| `variables` | `object` | 否 | **业务变量对象**，包含模板中绑定的所有字段 |
+| 任意自定义字段 | `any` | 否 | 如 `createTime`、`selected`，也可在模板中引用 |
 
-<script setup>
-const sampleData = ref({
-  id: 8,
-  name: '测试报告',
-  createTime: '2026-05-01',
-  variables: {
-    dockname: '机场名称',
-    dronesn: '无人机序列号',
-    totalcount: 100,
-    flightRecords: [
-      { time: '2026-04-02 09:30', taskname: '巡检任务A', distance: '12.5 km' },
-      { time: '2026-04-02 14:00', taskname: '巡检任务B', distance: '8.3 km' }
+> `id` 是业务数据的标识，`templateId` 是打印模板的标识，两者是不同概念。
+
+### `variables` 内部结构
+
+`variables` 是一个扁平或嵌套的 JSON 对象，其中的所有字段都可在模板元素中通过变量语法绑定。
+
+支持的数据类型：
+- **字符串** `string` — 文本元素绑定
+- **数字** `number` — 文本、图表数据
+- **布尔值** `boolean`
+- **数组** `array` — 表格数据源、图表数据源
+- **嵌套对象** `object` — 多级路径访问
+
+### 示例：完整数据格式
+
+```json
+{
+  "id": 8,
+  "name": "宝安机场飞行任务记录",
+  "templateId": "tpl_report_drone",
+  "createTime": "2026-05-01",
+  "variables": {
+    "dockname": "宝安国际无人机机场",
+    "dronesn": "6EE5NC104E0PY6",
+    "dronename": "M300 RTK",
+    "reportname": "宝安机场飞行任务记录报告",
+    "tasktype": "航线巡检",
+    "totalcount": 4,
+    "totaldistance": "48.6 km",
+    "conclusion": "本轮飞行任务覆盖宝安区重点航线，数据采集完整。",
+    "flightRecords": [
+      {
+        "time": "2026-04-02 09:30",
+        "taskname": "宝安港区A线巡检",
+        "dockname": "宝安国际无人机机场",
+        "distance": "12.5 km",
+        "image": "https://picsum.photos/id/1/200/80"
+      },
+      {
+        "time": "2026-04-08 14:00",
+        "taskname": "西乡街道线路巡查",
+        "dockname": "罗湖无人机机场",
+        "distance": "10.2 km",
+        "image": "https://picsum.photos/id/10/200/80"
+      }
     ],
-    chartData: [
-      { category: '一月', value: 1200 },
-      { category: '二月', value: 1500 },
-      { category: '三月', value: 1800 }
+    "taskRecords": [
+      {
+        "time": "2026-04-02 09:30",
+        "taskname": "宝安港区A线巡检",
+        "dockname": "宝安国际无人机机场",
+        "warn": 2
+      },
+      {
+        "time": "2026-04-08 14:00",
+        "taskname": "西乡街道线路巡查",
+        "dockname": "罗湖无人机机场",
+        "warn": 1
+      }
+    ],
+    "chartData": [
+      { "category": "一月", "value": 1200 },
+      { "category": "二月", "value": 1500 },
+      { "category": "三月", "value": 1800 }
     ]
   }
-});
-</script>
+}
 ```
 
-**`sampleData` 字段说明：**
+### 在模板中绑定变量
 
-| 字段 | 类型 | 必填 | 说明 |
-|-----|------|-----|------|
-| `id` | `number` / `string` | 否 | 数据唯一标识 |
-| `name` | `string` | 否 | 数据名称 |
-| `variables` | `object` | **是** | 变量对象，包含所有可供模板绑定的数据 |
+| 变量 | 绑定写法 | 应用元素 |
+|------|---------|---------|
+| `variables.dockname` | `@dockname` 或 `{#dockname}` | 文本 |
+| `variables.reportname` | `@reportname` | 文本 |
+| `variables.totaldistance` | `@totaldistance` | 文本 |
+| `variables.createtime` | `@createtime` | 文本 |
+| `variables.flightRecords` | `@flightRecords` | 表格、自定义表格 |
+| `variables.taskRecords` | `@taskRecords` | 表格 |
+| `variables.chartData` | `@chartData` | 图表 |
 
-`variables` 对象支持任意嵌套结构：
-- **简单值：** `string`、`number`、`boolean`
-- **数组：** 用于表格和图表组件的数据源
-- **嵌套对象：** 支持多级路径访问
+### 表格数据
 
-### 2. 通过 `setTestData()` 方法传入（Web Component 方式）
+表格需要三个维度的变量：
 
-```js
-const designer = document.querySelector('print-designer');
+| 绑定字段 | 变量名 | 格式 | 说明 |
+|---------|-------|------|------|
+| `variable` | `@items` | `Array<Object>` | 表格行数据 |
+| `columnsVariable` | `@tableCols` | `Array<{field, header, width}>` | 列定义 |
+| `footerDataVariable` | `@tableFooter` | `Array<Object>` | 页脚汇总行 |
 
-designer.setTestData({
-  orderNo: 'ORD-2026-001',
-  customerName: '张三',
-  items: [
-    { name: '产品A', price: 100, quantity: 2 },
-    { name: '产品B', price: 200, quantity: 3 }
+```json
+{
+  "items": [
+    { "name": "产品A", "price": 100, "quantity": 2 },
+    { "name": "产品B", "price": 200, "quantity": 3 }
+  ],
+  "tableCols": [
+    { "field": "name", "header": "产品名称", "width": 120 },
+    { "field": "price", "header": "单价", "width": 80 },
+    { "field": "quantity", "header": "数量", "width": 80 }
   ],
-  chartData: [
-    { category: '一月', value: 1200 },
-    { category: '二月', value: 1500 }
+  "tableFooter": [
+    { "name": { "value": "合计" }, "price": { "value": "300" } }
   ]
-});
+}
 ```
 
-### 3. 通过 `setVariables()` 方法传入（Web Component 方式）
+### 图表数据
 
-`setVariables` 用于在实际打印/导出时替换模板中的变量占位符：
+```json
+{
+  "chartData": [
+    { "category": "一月", "value": 1200 },
+    { "category": "二月", "value": 1500 }
+  ]
+}
+```
 
-```js
-const designer = document.querySelector('print-designer');
+图表元素需配置：
+- **chartDataVariable：** `@chartData`
+- **chartXField：** `category`（X 轴字段名）
+- **chartYField：** `value`（Y 轴字段名）
+- **chartNameField：** `category`（饼图名称字段）
 
-// 加载模板
-await designer.loadTemplate('tpl-order');
+---
 
-// 设置真实数据
-designer.setVariables({
-  orderNo: 'REAL-2026-001',
-  customerName: '李四',
-  totalAmount: 5999.00
-});
+## 保存回调 `onSave`
 
-// 静默打印
-await designer.print({ mode: 'browser', options: { silent: true } });
+传入 `onSave` 后，用户点击保存按钮（`Ctrl+S` 或工具栏按钮）时，设计器不再自动调接口，而是将组装好的数据通过回调交给用户自行处理。
+
+### 回调参数
+
+```ts
+interface SavePayload {
+  id: string | null;    // 模板 ID，null 表示新建
+  name: string;         // 模板名称
+  data: Record<string, any>;  // 完整模板数据（pages/canvasSize/watermark/testData...）
+  isNew: boolean;       // 是否新建模板
+}
+```
+
+### 使用示例
+
+```vue
+<PrintDesigner
+  :on-save="handleSave"
+/>
+
+<script setup>
+const handleSave = async (payload) => {
+  // payload.data 包含 pages、canvasSize、watermark、testData 等所有画布数据
+  const response = await fetch('/api/save', {
+    method: 'POST',
+    headers: { 'Content-Type': 'application/json' },
+    body: JSON.stringify(payload)
+  });
+  if (!response.ok) throw new Error('保存失败');
+};
+</script>
+```
+
+> 不传 `onSave` 时，设计器会走原有的默认保存逻辑（调用内置 CRUD 接口或存 localStorage），行为不变。
+
+---
+
+## 自动保存配置
+
+传入 `onSave` 后，可同时开启自动保存。开启后设计器会每隔固定时间调用 `onSave` 回调，右下角显示最近保存时间。
+
+### Props 配置
+
+| 属性 | 类型 | 默认值 | 说明 |
+|------|------|--------|------|
+| `auto-save-enabled` | `boolean` | `false` | 是否开启 |
+| `auto-save-interval-ms` | `number` | `120000` | 间隔（毫秒），默认 2 分钟 |
+
+### 示例
+
+```vue
+<PrintDesigner
+  :on-save="handleSave"
+  :auto-save-enabled="true"
+  :auto-save-interval-ms="120000"
+/>
+```
+
+```js
+designer.setOnSave(handleSave);
+designer.setAutoSave(true, 120000);  // 每 2 分钟自动保存
+designer.setAutoSave(false);         // 关闭
 ```
 
-### 4. 模板数据结构（完整格式）
+> 右下角会显示 "最近保存: HH:MM:SS"，每次回调完成后自动更新时间。
+
+---
+
+## 模板数据结构（完整格式）
 
-当你需要直接保存或加载完整的模板数据时，使用以下数据结构：
+当用户直接保存/加载完整模板时，使用以下数据结构：
 
 ```json
 {
   "id": "tpl_001",
   "name": "A4 订单模板",
   "updatedAt": 1715251200000,
+  "permissions": {
+    "editable": true,
+    "deletable": true,
+    "copyable": true
+  },
   "data": {
     "pages": [
       {
@@ -307,11 +442,7 @@ await designer.print({ mode: 'browser', options: { silent: true } });
             "width": 200,
             "height": 24,
             "content": "订单号: {#orderNo}",
-            "style": {
-              "fontSize": 14,
-              "fontWeight": "bold",
-              "color": "#111827"
-            }
+            "style": { "fontSize": 14, "fontWeight": "bold", "color": "#111827" }
           },
           {
             "id": "el_table_1",
@@ -360,9 +491,7 @@ await designer.print({ mode: 'browser', options: { silent: true } });
     },
     "testData": {
       "orderNo": "A001",
-      "items": [
-        { "name": "产品A", "price": 100, "quantity": 2 }
-      ]
+      "items": [{ "name": "产品A", "price": 100, "quantity": 2 }]
     }
   },
   "ext": {
@@ -380,154 +509,100 @@ await designer.print({ mode: 'browser', options: { silent: true } });
 }
 ```
 
-**顶层字段说明：**
+### 顶层字段
 
 | 字段 | 类型 | 必填 | 说明 |
 |-----|------|-----|------|
-| `id` | `string` | 是 | 模板唯一标识 |
+| `id` | `string` | 是 | 模板唯一 ID |
 | `name` | `string` | 是 | 模板名称 |
 | `updatedAt` | `number` | 否 | 更新时间戳（毫秒） |
+| `permissions` | `object` | 否 | `{ editable, deletable, copyable }` |
 | `data` | `object` | 是 | 模板设计数据 |
-| `data.pages` | `Page[]` | 是 | 页面列表，每个页面包含元素数组 |
-| `data.canvasSize` | `Size` | 是 | 画布尺寸 `{ width, height }` |
-| `data.unit` | `string` | 否 | 单位：`mm` / `px` / `pt` / `in` / `cm` |
-| `data.watermark` | `WatermarkSettings` | 否 | 水印配置 |
-| `data.guides` | `Guide[]` | 否 | 参考线列表 |
-| `data.testData` | `object` | 否 | 测试数据（报告模式会保存） |
-| `ext` | `object` | 否 | 扩展字段 |
-| `ext.availableVariables` | `VariableTreeItem[]` | 否 | 模板绑定的变量树 |
-| `permissions` | `object` | 否 | 权限控制 `{ editable, deletable, copyable }` |
-
----
-
-## 支持的元素类型
-
-| 元素类型 | 说明 | 数据支持 |
-|---------|------|---------|
-| 文本（Text） | 显示静态文本或变量内容 | 静态内容 / 变量引用 |
-| 长文本（LongText） | 自动扩展的多行文本 | 静态内容 / 变量引用 |
-| 图片（Image） | 显示图片 | 静态URL / 变量引用 |
-| 表格（Table） | 展示数据表格，支持自动分页 | 静态数据 / 数据变量 |
-| 自定义表格（CustomTable） | 自由合并单元格的表格 | 静态数据 / 数据变量 |
-| 条形码（Barcode） | 生成条形码 | 变量引用 |
-| 二维码（QRCode） | 生成二维码 | 变量引用 |
-| 图表（Chart） | ECharts 图表（柱状图/折线图/饼图/环形图/面积图） | 静态数据 / 数据变量 |
-| 线条（Line） | 绘制直线 | — |
-| 矩形（Rect） | 绘制矩形 | — |
-| 圆形（Circle） | 绘制圆形 | — |
-| 页码（PageNumber） | 显示页码信息 | — |
-
----
-
-## 数据绑定方式
-
-### 1. 静态数据
-
-直接在元素属性面板中输入静态内容，适用于固定不变的文本、图片URL等。
-
-### 2. 变量绑定
-
-使用特殊语法引用外部传入的数据，数据在打印/导出时动态替换。
-
-### 3. 数组数据（表格 & 图表）
-
-表格和图表组件可以绑定数组类型的数据变量。
-
-**表格数据格式：**
-
-```json
-{
-  "items": [
-    { "name": "产品A", "price": 100, "quantity": 2 },
-    { "name": "产品B", "price": 200, "quantity": 3 }
-  ],
-  "tableCols": [
-    { "field": "name", "header": "产品名称", "width": 120 },
-    { "field": "price", "header": "单价", "width": 80 },
-    { "field": "quantity", "header": "数量", "width": 80 }
-  ],
-  "tableFooter": [
-    { "name": { "value": "合计" }, "price": { "value": "300" } }
-  ]
-}
-```
+| `ext` | `object` | 否 | 扩展数据（变量树等） |
 
-在表格元素的属性面板中：
-- **数据变量（variable）：** 绑定到 `@items`
-- **列定义变量（columnsVariable）：** 绑定到 `@tableCols`
-- **页脚数据变量（footerDataVariable）：** 绑定到 `@tableFooter`
+### `data` 内部字段
 
-**图表数据格式：**
-
-```json
-{
-  "chartData": [
-    { "category": "一月", "value": 1200 },
-    { "category": "二月", "value": 1500 },
-    { "category": "三月", "value": 1800 }
-  ]
+| 字段 | 类型 | 必填 | 说明 |
+|-----|------|-----|------|
+| `pages` | `Page[]` | 是 | 页面列表，每页含 `elements` 数组 |
+| `canvasSize` | `{ width, height }` | 是 | 画布尺寸（默认 A4: 794×1123） |
+| `unit` | `'mm'`\|`'px'`\|`'pt'`\|`'in'`\|`'cm'` | 否 | 单位 |
+| `watermark` | `WatermarkSettings` | 否 | 水印配置 |
+| `guides` | `Guide[]` | 否 | 参考线 |
+| `zoom` | `number` | 否 | 缩放比例 |
+| `showGrid` | `boolean` | 否 | 显示网格 |
+| `headerHeight` | `number` | 否 | 页眉高度 |
+| `footerHeight` | `number` | 否 | 页脚高度 |
+| `pageSpacingX` | `number` | 否 | 水平边距 |
+| `pageSpacingY` | `number` | 否 | 垂直边距 |
+| `canvasBackground` | `string` | 否 | 画布背景色 |
+| `testData` | `object` | 否 | 测试数据（报告模式保存） |
+
+### 元素基本字段
+
+```ts
+interface PrintElement {
+  id: string;          // 元素唯一 ID
+  type: ElementType;   // 元素类型: 'text'|'image'|'table'|'customTable'|'barcode'|'qrcode'|'line'|'rect'|'circle'|'chart'|'pageNumber'|'longtext'
+  x: number;           // X 坐标
+  y: number;           // Y 坐标
+  width: number;       // 宽度
+  height: number;      // 高度
+  content?: string;    // 文本内容（支持变量占位符）
+  variable?: string;   // 绑定变量名（如 '@items'）
+  style: ElementStyle; // 样式对象
 }
 ```
 
-图表元素支持的绑定字段：
-- **chartDataVariable：** 数据变量名
-- **chartXField：** X轴/分类字段名
-- **chartYField：** Y轴/数值字段名
-- **chartNameField：** 名称字段（饼图）
-
 ---
 
-## 测试数据
-
-在设计器中编辑时，可以手动编辑测试数据以便预览变量渲染效果。
-
-### 设计器内编辑
+## 元素数据绑定
 
-在模板列表中对模板右键 → 选择"测试数据" → 在弹出的 JSON 编辑器中编辑测试数据。
+### 变量语法
 
-### 通过 API 设置
+| 语法 | 示例 | 说明 |
+|-----|------|------|
+| `@变量名` | `@customerName` | 直接引用变量 |
+| `{#变量路径}` | `{#order.items[0].name}` | 支持嵌套路径和数组索引 |
 
-```js
-// Web Component 方式
-designer.setTestData({
-  orderNo: 'TEST-001',
-  customerName: '测试客户'
-});
+### 各元素可绑定字段
 
-// 获取当前测试数据
-const data = designer.getTestData();
-```
+| 元素 | 绑定的属性 | 示例 |
+|------|----------|------|
+| 文本 / 长文本 | `content` | `订单号: {#orderNo}` |
+| 图片 | `variable` | `@imageUrl` |
+| 表格 | `variable` + `columnsVariable` + `footerDataVariable` | `@items`, `@tableCols`, `@tableFooter` |
+| 条形码 | `variable` | `@barcode` |
+| 二维码 | `variable` | `@url` |
+| 图表 | `chartDataVariable` + `chartXField` + `chartYField` | `@chartData`, `category`, `value` |
 
 ---
 
-## 变量语法参考
-
-| 语法 | 示例 | 说明 |
-|-----|------|------|
-| `@变量名` | `@customerName` | 使用 `@` 符号引用顶层变量 |
-| `{#变量路径}` | `{#order.details[0].name}` | 使用 `{#}` 包裹，支持嵌套路径和数组索引 |
-| `{#变量名}` | `{#orderNo}` | 与 `@` 等价，推荐使用此格式 |
-
-在元素属性中绑定变量：
+## 支持的元素类型
 
-| 元素类型 | 可绑定属性的字段 | 示例 |
-|---------|----------------|------|
-| 文本 | `content` | `订单号: {#orderNo}` |
-| 图片 | `variable` | `@logoUrl` |
-| 表格 | `variable`、`columnsVariable`、`footerDataVariable` | `@items` |
-| 条形码 | `variable` | `{#barcode}` |
-| 二维码 | `variable` | `{#url}` |
-| 图表 | `chartDataVariable` | `@chartData` |
+| 类型 | 标识 | 说明 |
+|------|------|------|
+| 文本 | `text` | 静态文本或变量内容 |
+| 长文本 | `longtext` | 多行自动扩展文本 |
+| 图片 | `image` | 图片显示（URL 绑定） |
+| 表格 | `table` | 数据表格，支持自动分页、页脚 |
+| 自定义表格 | `customTable` | 自由合并单元格 |
+| 条形码 | `barcode` | 一维条形码 |
+| 二维码 | `qrcode` | 二维码 |
+| 图表 | `chart` | ECharts（柱状图/折线图/饼图/环形图/面积图） |
+| 线条 | `line` | 直线 |
+| 矩形 | `rect` | 矩形 |
+| 圆形 | `circle` | 圆形 |
+| 页码 | `pageNumber` | 页码显示 |
 
 ---
 
 ## 技术栈
 
-- Vue 3
-- TypeScript
+- Vue 3 / TypeScript
 - Pinia（状态管理）
 - Tailwind CSS
 - ECharts 5
-- Monaco Editor（代码编辑器）
+- Monaco Editor
 
 ---