x-print-designer 0.4.7 → 0.4.10

package/README.md

@@ -350,17 +350,37 @@ designer.setMode('report')
 | `setTestData(data)` | `Record<string, any>` | `void` | 设置测试/预览数据（等价 Vue 组件的 `sample-data`） |
 | `setSampleData(data)` | `Record<string, any>` | `void` | `setTestData` 的别名 |
 | `setVariables(vars)` | `Record<string, any>` | `void` | 打印/导出时注入真实变量（覆盖 testData 中的同名字段） |
-| `setTemplates(list, opts?)` | `Array<Template>, object?` | `void` | 设置预设模板列表。`opts` 可选：`{ currentTemplateId?: string }` |
-| `loadTemplate(id)` | `string` | `Promise<void>` | 加载指定模板到画布 |
+| `setTemplates(list, opts?)` | `Array<Template>, object?` | `Promise<void>` | 设置预设模板列表并加载当前模板。`opts` 可选：`{ currentTemplateId?: string }`。返回的 Promise 在画布 pages 填充完成后 resolve，可据此消除时序竞态 |
+| `loadTemplate(id)` | `string` | `Promise<boolean>` | 加载指定模板到画布。resolve 时 pages 已填充；返回 `false` 表示因前置条件（如正在编辑自定义元素）未触发 |
 | `loadTemplateData(data)` | `Record<string, any>` | `boolean` | 直接加载模板 JSON 数据到画布，返回是否成功 |
 | `getTemplateData()` | — | `Record<string, any>` | 获取当前模板完整数据 |
 | `getPreviewHtml()` | — | `Promise<string>` | 获取预览 HTML 字符串 |
 | `print(options?)` | `PrintOptions` | `Promise<void>` | 执行打印，详见[打印与导出](#打印与导出) |
 | `export(options?)` | `ExportOptions` | `Promise<void>` | 导出 PDF / 图片 / HTML，详见[打印与导出](#打印与导出) |
-| `setPreviewMode(options)` | `PreviewModeOptions` | `void` | 进入独立预览面板模式 |
+| `setPreviewMode(options)` | `PreviewModeOptions` | `void` | 进入独立预览面板模式。传入的 `pages` 若含循环页（`loopDataVariable`），预览时会自动按数据展开成 N 页 |
 | `exitPreviewMode()` | — | `void` | 退出预览模式，返回编辑器 |
 | `setBranding(config)` | `{ title?, logoUrl?, showTitle?, showLogo? }` | `void` | 设置品牌标识 |
-| `setLang(lang)` | `'zh'` \| `'en'` | `void` | 切换语言 |
+| `setLanguage(lang)` | `'zh'` \| `'en'` | `void` | 切换语言 |
+| `setCrudMode(mode, opts?)` | `'local'` \| `'remote'`, `{ skipAutoLoad?: boolean }` | `void` | 切换 CRUD 模式。`skipAutoLoad: true` 跳过 remote 模式下自动 `loadTemplates + loadTemplate` 的链式加载，适用于已通过 `setTemplates` 提供数据的场景，避免双次加载闪烁 |
+| `expandLoopPages(pages, ctx?)` | `Page[], LoopExpandContext?` | `Page[]` | 循环页展开：按 `page.loopDataVariable` + 数据数组，把 1 个模板页展开成 N 页。不传 `ctx` 时默认使用当前 store 数据（导出语义） |
+| `hasLoopPage(pages)` | `Page[]?` | `boolean` | 判断页面数组中是否含循环页 |
+| `collapseLoopPages(currentPages, originalPages)` | `Page[], Page[]` | `Page[]` | 折叠已展开的循环页，还原为带 `loopDataVariable` 的单个模板页。适用于报告模式保存前还原模板结构 |
+
+### 事件参考
+
+Web Component 元素会派发以下自定义事件，可通过 `addEventListener` 监听：
+
+| 事件名 | 触发时机 | `detail` 结构 |
+|--------|---------|--------------|
+| `ready` | 组件挂载完成、API 可调用时（下一个 tick 派发） | 无 |
+| `templateloaded` | 模板加载完成、画布 pages 已填充时 | `{ id: string, mode: 'template' \| 'report' }` |
+| `print` | 开始执行打印前 | `{ request: DesignerPrintRequest }` |
+| `printed` | 打印成功完成 | `{ request, result }` |
+| `export` | 开始导出前 | `{ request: DesignerExportRequest }` |
+| `exported` | 导出成功完成（pdf/html/images/pdfBlob/imageBlob） | `{ request }` 或 `{ request, blob }`（Blob 类型） |
+| `error` | 打印/导出/内部渲染出错 | `{ scope: 'print' \| 'export' \| 'getPreviewHtml' \| 'render', error, info? }` |
+
+> **时序提示**：若需要在模板加载完成后执行操作（如注入运行时数据），监听 `templateloaded` 事件，或 `await` `setTemplates` / `loadTemplate` 返回的 Promise，二者等价且都比轮询 `store.pages` 更可靠。
 
 ### 基本使用示例
 

package/dist/{JsBarcode-DaJP3cMD.js → JsBarcode-hwIbESSq.js}

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

package/dist/{browser-PaZLWyYp.js → browser-B42qU2Gc.js}

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

package/dist/{dom-to-image-more.min-DtQ9SBfy.js → dom-to-image-more.min-CU_b0kYq.js}

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

package/dist/{index-Bn1xBFgs.js → index-B22omX0t.js}

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