x-print-designer 0.0.2 → 0.0.4

package/README.md

@@ -1,103 +1,533 @@
-# X-Print-Designer
-
-基于Vue Print Designer的二开插件
-
-## 插件简介
-
-本插件是一款功能强大的打印设计器，集成了Vue 3和TypeScript开发的环境，新增了ECharts图表组件，支持多种元素类型和数据绑定方式。
-
-## 新增功能
-
-### ECharts图表组件
-
-支持以下图表类型：
-- **柱状图（Bar）**：展示分类数据的数值大小
-- **折线图（Line）**：展示数据趋势变化
-- **饼图（Pie）**：展示数据的占比分布
-- **环形图（Doughnut）**：展示数据的占比分布（带中心镂空）
-- **面积图（Area）**：展示数据趋势变化（带填充效果）
-
-图表支持特性：
-- 自定义标题、图例、提示框
-- 自定义坐标轴标题和标签样式
-- 显示数据标签
-- 自定义颜色配置
-- 支持自定义ECharts选项
-
-## 支持的元素类型
-
-| 元素类型 | 说明 | 数据支持 |
-|---------|------|---------|
-| 文本（Text） | 显示静态文本或变量内容 | 静态内容 / 变量引用 |
-| 图片（Image） | 显示图片 | 静态URL / 变量引用 |
-| 表格（Table） | 展示数据表格 | 静态数据 / 数据变量 |
-| 条形码（Barcode） | 生成条形码 | 变量引用 |
-| 二维码（QRCode） | 生成二维码 | 变量引用 |
-| 图表（Chart） | ECharts图表展示 | 静态数据 / 数据变量 |
-| 线条（Line） | 绘制直线 | - |
-| 矩形（Rect） | 绘制矩形 | - |
-| 圆形（Circle） | 绘制圆形 | - |
-| 页码（PageNumber） | 显示页码信息 | - |
-
-## 数据使用方式
-
-### 1. 静态数据配置
-
-直接在元素属性面板中输入静态内容，适用于固定不变的数据。
-
-### 2. 变量数据绑定
-
-使用变量语法引用外部数据，支持两种格式：
-
-| 语法格式 | 示例 | 说明 |
-|---------|------|------|
-| `@变量名` | `@customerName` | 使用@符号开头 |
-| `{#变量名}` | `{#order.total}` | 使用{#}包裹 |
-
-变量支持嵌套访问，例如 `{#order.details[0].productName}`。
-
-### 3. 数组数据处理
-
-对于表格和图表组件，支持绑定数组类型数据：
-
-**表格数据格式示例：**
-```json
-{
-  "tableData": [
-    { "name": "产品A", "price": 100, "quantity": 2 },
-    { "name": "产品B", "price": 200, "quantity": 3 }
-  ]
-}
-```
-
-**图表数据格式示例：**
-```json
-{
-  "chartData": [
-    { "category": "一月", "value": 1200 },
-    { "category": "二月", "value": 1500 },
-    { "category": "三月", "value": 1800 }
-  ]
-}
-```
-
-### 4. 表格高级功能
-
-表格组件支持以下高级功能：
-- **列数据变量**：动态绑定表格列数据
-- **页脚数据变量**：显示表格汇总信息
-- **自定义脚本**：使用脚本处理数据转换
-- **自动分页**：数据过多时自动分页显示
-- **页脚重复**：每页重复显示页脚
-
-## 测试数据
-
-在设计器中编辑时，系统会根据元素配置自动生成测试数据用于预览。您也可以在设计器中手动编辑测试数据，以便更好地预览各种数据情况下的打印效果。
-
-## 技术栈
-
-- Vue 3
-- TypeScript
-- ECharts 5
-- Pinia（状态管理）
-- Tailwind CSS
+# X-Print-Designer
+
+基于 Vue 3 + TypeScript 开发的打印设计器，支持可视化拖拽设计打印模板，集成 ECharts 图表组件，提供模板模式与报告模式两种工作方式。
+
+---
+
+## 目录
+
+- [核心概念：模板模式 vs 报告模式](#核心概念模板模式-vs-报告模式)
+- [快速开始](#快速开始)
+- [传入数据格式](#传入数据格式)
+- [支持的元素类型](#支持的元素类型)
+- [数据绑定方式](#数据绑定方式)
+- [测试数据](#测试数据)
+- [变量语法参考](#变量语法参考)
+- [技术栈](#技术栈)
+
+---
+
+## 核心概念：模板模式 vs 报告模式
+
+设计器支持两种工作模式，通过 `mode` 属性/方法进行切换。
+
+### 模板模式（template）— 默认模式
+
+**适用场景：** 创建可复用的打印模板，模板与数据分离。先在设计器中画好布局，打印时再填入真实数据。
+
+**保存行为：**
+- 保存时**只保存页面布局信息**（元素位置、样式、画布大小、参考线等）
+- **不保存**测试数据（`testData`）
+
+**典型工作流：**
+1. 在设计器中拖拽元素，设计打印模板的布局
+2. 使用变量语法（如 `{#orderNo}`）标记数据占位符
+3. 保存模板，模板只包含布局结构
+4. 业务系统调用打印/导出时，传入真实数据替换变量
+
+**保存的数据结构：**
+
+```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）
+
+**适用场景：** 创建包含数据的完整报告，布局和数据一起保存。适用于需要将模板和示例数据打包存储的场景。
+
+**保存行为：**
+- 保存时**同时保存页面布局信息和测试数据**（`testData`）
+- `testData` 中包含当前设计器中填写/导入的测试数据
+
+**典型工作流：**
+1. 在设计器中拖拽元素，设计报告布局
+2. 通过 API 或界面导入测试数据
+3. 保存报告，布局和数据一起持久化
+4. 加载报告时，布局和测试数据一起恢复
+
+**保存的数据结构（与模板模式的区别）：**
+
+```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>
+```
+
+**Web Component 方式：**
+
+```js
+const designer = document.querySelector('print-designer');
+
+// 切换为模板模式（默认）
+designer.setMode('template');
+
+// 切换为报告模式
+designer.setMode('report');
+```
+
+---
+
+## 快速开始
+
+### 安装
+
+```bash
+npm install
+npm run dev
+```
+
+### Vue 组件方式
+
+```vue
+<template>
+  <PrintDesigner
+    mode="template"
+    :sample-data="sampleData"
+  />
+</template>
+
+<script setup>
+import { ref } from 'vue';
+import PrintDesigner from './components/PrintDesigner.vue';
+
+const sampleData = ref({
+  id: 1,
+  name: '测试报告',
+  variables: {
+    title: '报告标题',
+    customerName: '张三',
+    items: [
+      { name: '产品A', price: 100, quantity: 2 },
+      { name: '产品B', price: 200, quantity: 3 }
+    ]
+  }
+});
+</script>
+```
+
+### Web Component 方式
+
+```html
+<print-designer id="designer"></print-designer>
+
+<script>
+  const designer = document.getElementById('designer');
+
+  // 设置模式
+  designer.setMode('template');
+
+  // 设置测试数据
+  designer.setTestData({
+    orderNo: 'ORD-001',
+    customerName: '张三',
+    items: [
+      { name: '产品A', price: 100, quantity: 2 }
+    ]
+  });
+
+  // 设置模板列表
+  designer.setTemplates([
+    {
+      id: 'tpl-1',
+      name: 'A4 打印模板',
+      data: {
+        pages: [],
+        canvasSize: { width: 794, height: 1123 },
+        unit: 'mm'
+      }
+    }
+  ], { currentTemplateId: 'tpl-1' });
+</script>
+```
+
+---
+
+## 传入数据格式
+
+### 1. 通过 `sample-data` 属性传入（Vue 组件方式）
+
+使用 `PrintDesigner` 组件时，通过 `sample-data` 属性传入示例数据，用于设计器中的数据绑定预览：
+
+```vue
+<template>
+  <PrintDesigner :sample-data="sampleData" />
+</template>
+
+<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' }
+    ],
+    chartData: [
+      { category: '一月', value: 1200 },
+      { category: '二月', value: 1500 },
+      { category: '三月', value: 1800 }
+    ]
+  }
+});
+</script>
+```
+
+**`sampleData` 字段说明：**
+
+| 字段 | 类型 | 必填 | 说明 |
+|-----|------|-----|------|
+| `id` | `number` / `string` | 否 | 数据唯一标识 |
+| `name` | `string` | 否 | 数据名称 |
+| `variables` | `object` | **是** | 变量对象，包含所有可供模板绑定的数据 |
+
+`variables` 对象支持任意嵌套结构：
+- **简单值：** `string`、`number`、`boolean`
+- **数组：** 用于表格和图表组件的数据源
+- **嵌套对象：** 支持多级路径访问
+
+### 2. 通过 `setTestData()` 方法传入（Web Component 方式）
+
+```js
+const designer = document.querySelector('print-designer');
+
+designer.setTestData({
+  orderNo: 'ORD-2026-001',
+  customerName: '张三',
+  items: [
+    { name: '产品A', price: 100, quantity: 2 },
+    { name: '产品B', price: 200, quantity: 3 }
+  ],
+  chartData: [
+    { category: '一月', value: 1200 },
+    { category: '二月', value: 1500 }
+  ]
+});
+```
+
+### 3. 通过 `setVariables()` 方法传入（Web Component 方式）
+
+`setVariables` 用于在实际打印/导出时替换模板中的变量占位符：
+
+```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 } });
+```
+
+### 4. 模板数据结构（完整格式）
+
+当你需要直接保存或加载完整的模板数据时，使用以下数据结构：
+
+```json
+{
+  "id": "tpl_001",
+  "name": "A4 订单模板",
+  "updatedAt": 1715251200000,
+  "data": {
+    "pages": [
+      {
+        "id": "page_1",
+        "elements": [
+          {
+            "id": "el_text_1",
+            "type": "text",
+            "x": 40,
+            "y": 40,
+            "width": 200,
+            "height": 24,
+            "content": "订单号: {#orderNo}",
+            "style": {
+              "fontSize": 14,
+              "fontWeight": "bold",
+              "color": "#111827"
+            }
+          },
+          {
+            "id": "el_table_1",
+            "type": "table",
+            "x": 40,
+            "y": 100,
+            "width": 500,
+            "height": 200,
+            "variable": "@items",
+            "columnsVariable": "@tableCols",
+            "showFooter": true,
+            "footerDataVariable": "@tableFooter",
+            "autoPaginate": true,
+            "style": {
+              "fontSize": 12,
+              "color": "#000000",
+              "headerBackgroundColor": "#f3f4f6",
+              "borderColor": "#d1d5db",
+              "borderWidth": 1
+            }
+          }
+        ]
+      }
+    ],
+    "canvasSize": { "width": 794, "height": 1123 },
+    "guides": [],
+    "zoom": 1,
+    "showGrid": true,
+    "headerHeight": 0,
+    "footerHeight": 0,
+    "showHeaderLine": false,
+    "showFooterLine": false,
+    "showMinimap": false,
+    "canvasBackground": "#ffffff",
+    "pageSpacingX": 0,
+    "pageSpacingY": 0,
+    "unit": "mm",
+    "watermark": {
+      "enabled": false,
+      "text": "",
+      "angle": -30,
+      "color": "#000000",
+      "opacity": 0.1,
+      "size": 24,
+      "density": 160
+    },
+    "testData": {
+      "orderNo": "A001",
+      "items": [
+        { "name": "产品A", "price": 100, "quantity": 2 }
+      ]
+    }
+  },
+  "ext": {
+    "availableVariables": [
+      {
+        "id": "order",
+        "label": "订单信息",
+        "children": [
+          { "id": "orderNo", "label": "订单号" },
+          { "id": "items", "label": "订单明细", "isArray": true }
+        ]
+      }
+    ]
+  }
+}
+```
+
+**顶层字段说明：**
+
+| 字段 | 类型 | 必填 | 说明 |
+|-----|------|-----|------|
+| `id` | `string` | 是 | 模板唯一标识 |
+| `name` | `string` | 是 | 模板名称 |
+| `updatedAt` | `number` | 否 | 更新时间戳（毫秒） |
+| `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" } }
+  ]
+}
+```
+
+在表格元素的属性面板中：
+- **数据变量（variable）：** 绑定到 `@items`
+- **列定义变量（columnsVariable）：** 绑定到 `@tableCols`
+- **页脚数据变量（footerDataVariable）：** 绑定到 `@tableFooter`
+
+**图表数据格式：**
+
+```json
+{
+  "chartData": [
+    { "category": "一月", "value": 1200 },
+    { "category": "二月", "value": 1500 },
+    { "category": "三月", "value": 1800 }
+  ]
+}
+```
+
+图表元素支持的绑定字段：
+- **chartDataVariable：** 数据变量名
+- **chartXField：** X轴/分类字段名
+- **chartYField：** Y轴/数值字段名
+- **chartNameField：** 名称字段（饼图）
+
+---
+
+## 测试数据
+
+在设计器中编辑时，可以手动编辑测试数据以便预览变量渲染效果。
+
+### 设计器内编辑
+
+在模板列表中对模板右键 → 选择"测试数据" → 在弹出的 JSON 编辑器中编辑测试数据。
+
+### 通过 API 设置
+
+```js
+// Web Component 方式
+designer.setTestData({
+  orderNo: 'TEST-001',
+  customerName: '测试客户'
+});
+
+// 获取当前测试数据
+const data = designer.getTestData();
+```
+
+---
+
+## 变量语法参考
+
+| 语法 | 示例 | 说明 |
+|-----|------|------|
+| `@变量名` | `@customerName` | 使用 `@` 符号引用顶层变量 |
+| `{#变量路径}` | `{#order.details[0].name}` | 使用 `{#}` 包裹，支持嵌套路径和数组索引 |
+| `{#变量名}` | `{#orderNo}` | 与 `@` 等价，推荐使用此格式 |
+
+在元素属性中绑定变量：
+
+| 元素类型 | 可绑定属性的字段 | 示例 |
+|---------|----------------|------|
+| 文本 | `content` | `订单号: {#orderNo}` |
+| 图片 | `variable` | `@logoUrl` |
+| 表格 | `variable`、`columnsVariable`、`footerDataVariable` | `@items` |
+| 条形码 | `variable` | `{#barcode}` |
+| 二维码 | `variable` | `{#url}` |
+| 图表 | `chartDataVariable` | `@chartData` |
+
+---
+
+## 技术栈
+
+- Vue 3
+- TypeScript
+- Pinia（状态管理）
+- Tailwind CSS
+- ECharts 5
+- Monaco Editor（代码编辑器）
+
+---

package/dist/{JsBarcode-CaEyZMPG.js → JsBarcode-BCOR_2Tk.js}

@@ -1,4 +1,4 @@
-import { getDefaultExportFromCjs } from "./web-component-6n-bG7Fh.js";
+import { getDefaultExportFromCjs } from "./web-component-Bgmv52X1.js";
 function _mergeNamespaces(n, m) {
   for (var i = 0; i < m.length; i++) {
     const e = m[i];

package/dist/{browser-Bl9hyQY4.js → browser-54jWk43N.js}

@@ -1,4 +1,4 @@
-import { getDefaultExportFromCjs } from "./web-component-6n-bG7Fh.js";
+import { getDefaultExportFromCjs } from "./web-component-Bgmv52X1.js";
 function _mergeNamespaces(n, m) {
   for (var i = 0; i < m.length; i++) {
     const e = m[i];

package/dist/{dom-to-image-more.min-CwgZFoL1.js → dom-to-image-more.min-DaRf6ofp.js}

@@ -1,4 +1,4 @@
-import { getDefaultExportFromCjs } from "./web-component-6n-bG7Fh.js";
+import { getDefaultExportFromCjs } from "./web-component-Bgmv52X1.js";
 function _mergeNamespaces(n, m) {
   for (var i = 0; i < m.length; i++) {
     const e = m[i];

package/dist/{index-C8ZY6iyn.js → index-Cg6-YG7b.js}

@@ -1,4 +1,4 @@
-import { defineComponent, h, computed, onUnmounted, watch, shallowRef, loader, onMounted, nextTick, ref } from "./web-component-6n-bG7Fh.js";
+import { defineComponent, h, computed, onUnmounted, watch, shallowRef, loader, onMounted, nextTick, ref } from "./web-component-Bgmv52X1.js";
 var __defProp$2 = Object.defineProperty;
 var __defProps = Object.defineProperties;
 var __getOwnPropDescs = Object.getOwnPropertyDescriptors;

package/dist/{index.es-Bd9RXDZp.js → index.es-Dky7JXCp.js}

@@ -1,4 +1,4 @@
-import { commonjsGlobal, getDefaultExportFromCjs } from "./web-component-6n-bG7Fh.js";
+import { commonjsGlobal, getDefaultExportFromCjs } from "./web-component-Bgmv52X1.js";
 import { _typeof as _typeof$1 } from "./typeof-DxTVrAEz.js";
 var es_promise = {};
 var es_promise_constructor = {};

package/dist/{jspdf.es.min-CXfI1dny.js → jspdf.es.min-CzIpPYrU.js}

@@ -10832,7 +10832,7 @@ function le() {
   var h2 = l2.getContext("2d");
   h2.fillStyle = "#fff", h2.fillRect(0, 0, l2.width, l2.height);
   var f2 = { ignoreMouse: true, ignoreAnimation: true, ignoreDimensions: true }, d2 = this;
-  return (i.canvg ? Promise.resolve(i.canvg) : import("./index.es-Bd9RXDZp.js")).catch(function(t3) {
+  return (i.canvg ? Promise.resolve(i.canvg) : import("./index.es-Dky7JXCp.js")).catch(function(t3) {
     return Promise.reject(new Error("Could not load canvg: " + t3));
   }).then(function(t3) {
     return t3.default ? t3.default : t3;

package/dist/{jszip.min-DoQFFAlg.js → jszip.min-nApOj_gF.js}

@@ -1,4 +1,4 @@
-import { commonjsGlobal, getDefaultExportFromCjs } from "./web-component-6n-bG7Fh.js";
+import { commonjsGlobal, getDefaultExportFromCjs } from "./web-component-Bgmv52X1.js";
 function _mergeNamespaces(n, m) {
   for (var i = 0; i < m.length; i++) {
     const e = m[i];