x-print-designer 0.2.6 → 0.3.0

package/README.md

@@ -254,14 +254,21 @@ const handleSave = (payload) => {
 | 方法 | 说明 |
 |------|------|
 | `setMode(mode)` | 设置模式：`'template'` / `'report'` |
+| `setViewMode(viewMode)` | 切换视图：`'edit'` / `'preview'` |
 | `setOnSave(handler)` | 设置保存回调 |
 | `setAutoSave(enabled, intervalMs?)` | 开启/关闭自动保存 |
 | `setTestData(data)` | 设置测试数据 |
 | `setVariables(vars)` | 打印/导出时注入真实变量 |
+| `setSampleData(data)` | 设置样本数据 |
 | `setTemplates(list, opts)` | 设置模板列表 |
 | `loadTemplate(id)` | 加载指定模板到画布 |
+| `loadTemplateData(data)` | 直接加载模板 JSON 数据到画布 |
+| `getTemplateData()` | 获取当前模板完整数据 |
+| `getPreviewHtml()` | 获取预览 HTML 字符串 |
 | `print(request)` | 执行打印 |
 | `export(request)` | 导出 PDF/图片/HTML |
+| `setPreviewMode(options)` | 🆕 进入独立预览面板模式 |
+| `exitPreviewMode()` | 🆕 退出预览模式，返回编辑器 |
 
 ### 打印时注入真实数据
 
@@ -279,6 +286,81 @@ designer.setVariables({
 await designer.print({ mode: 'browser', options: { silent: true } });
 ```
 
+### 独立预览面板 (`setPreviewMode` / `exitPreviewMode`) 🆕
+
+当设计器以 Web Component 方式嵌入时，可切换到独立的**纯预览模式**——只渲染打印内容，不显示编辑器工具栏、属性面板、辅助线等 UI。
+
+**适用于：**
+- 插件/第三方页面嵌入时，单独展示打印预览效果
+- 用户填写表单后直接预览生成的打印内容
+- 无需编辑功能的只读预览场景
+
+#### 切换方式
+
+```javascript
+const designer = document.querySelector('print-designer');
+
+// 进入预览模式，传入模板和数据
+designer.setPreviewMode({
+  pages: templateData.pages,                    // 页面元素布局
+  canvasSize: { width: 794, height: 1123 },    // 画布尺寸
+  canvasBackground: '#ffffff',                  // 背景色
+  testData: {                                   // 测试数据
+    name: '张三',
+    amount: 1000,
+    items: [{ name: '产品A', price: 100 }]
+  },
+  variables: {},                                // 变量映射
+  watermark: { enabled: false }                 // 水印设置
+});
+
+// 退出预览，返回编辑器界面
+designer.exitPreviewMode();
+```
+
+#### 参数说明
+
+| 参数 | 类型 | 必填 | 说明 |
+|------|------|------|------|
+| `pages` | `Page[]` | ✅ 是 | 页面元素布局数组 |
+| `canvasSize` | `{ width, height }` | ✅ 是 | 画布尺寸（px） |
+| `canvasBackground` | `string` | 否 | 画布背景色，默认 `'#ffffff'` |
+| `testData` | `object` | 否 | 测试数据，模板中的变量会自动解析 |
+| `variables` | `object` | 否 | 额外变量映射 |
+| `watermark` | `object` | 否 | 水印配置 |
+
+#### 使用示例
+
+```javascript
+// 场景：用户点击"预览"按钮，传入后端返回的模板和当前表单数据
+async function openPreview(reportId) {
+  const designer = document.querySelector('print-designer');
+
+  // 从后端获取模板数据
+  const template = await fetch(`/api/templates/${reportId}`).then(r => r.json());
+
+  // 进入预览模式
+  designer.setPreviewMode({
+    pages: template.data.pages,
+    canvasSize: template.data.canvasSize,
+    canvasBackground: template.data.canvasBackground || '#ffffff',
+    testData: {
+      customerName: document.getElementById('name').value,
+      orderDate: document.getElementById('date').value,
+      items: getOrderItems()
+    },
+    watermark: template.data.watermark
+  });
+}
+
+// 返回编辑
+function backToEdit() {
+  designer.exitPreviewMode();
+}
+```
+
+> **注意：** `exitPreviewMode()` 会自动恢复进入预览前的编辑器状态（模板选择、编辑进度等）。
+
 ---
 
 ## 传入数据格式
@@ -869,16 +951,23 @@ https://example.com/logo.png
 |------|------|------|
 | 文本 | `text` | 静态文本或变量内容 |
 | 长文本 | `longtext` | 多行自动扩展文本 |
-| 图片 | `image` | 图片显示（URL 绑定） |
-| 表格 | `table` | 数据表格，支持自动分页、页脚 |
-| 自定义表格 | `customTable` | 自由合并单元格 |
+| 富文本 | `richtext` | 富文本格式化内容 |
+| 图片 | `image` | 图片显示（URL / Base64 / 变量绑定） |
+| 表格 | `table` | 数据表格，支持自动分页、页脚脚本 |
+| 自定义表格 | `customTable` | 自由合并单元格、单元格内嵌图片/字段 |
+| 嵌套表格 | `nestedtable` | 分组嵌套数据展示 |
 | 条形码 | `barcode` | 一维条形码 |
 | 二维码 | `qrcode` | 二维码 |
 | 图表 | `chart` | ECharts（柱状图/折线图/饼图/环形图/面积图） |
+| 数据卡片 | `datacard` | 单个关键指标数据展示 |
+| 进度条 | `progress` | 百分比进度展示 |
+| 列表 | `list` | 多行列表数据展示 |
+| 日期 | `date` | 日期时间显示 |
+| 页码 | `pageNumber` | 页码显示 |
+| 签名/印章 | `signature` | 印章图片或二维码 |
 | 线条 | `line` | 直线 |
 | 矩形 | `rect` | 矩形 |
 | 圆形 | `circle` | 圆形 |
-| 页码 | `pageNumber` | 页码显示 |
 
 ---