x-print-designer 0.4.13 → 0.4.28

package/README.md

@@ -9,11 +9,17 @@
 - [前置依赖要求](#前置依赖要求)
 - [快速开始](#快速开始)
   - [源码开发](#源码开发)
-  - [Vue 组件接入](#vue-组件接入)
+  - [Vue 组件接入（XPrintDesigner）](#vue-组件接入xprintdesigner)
+  - [5 分钟接入（推荐）](#5-分钟接入推荐)
   - [Web Component 接入](#web-component-接入)
 - [核心概念：模板模式 vs 报告模式](#核心概念模板模式-vs-报告模式)
 - [Vue 组件使用说明](#vue-组件使用说明)
 - [Web Component 使用说明](#web-component-使用说明)
+  - [完整 API 参考](#完整-api-参考)
+  - [场景化模板库](#场景化模板库)
+  - [数据驱动模板向导](#数据驱动模板向导)
+  - [组合与取消组合](#组合与取消组合)
+  - [远程 CRUD 配置](#远程-crud-配置)
 - [传入数据格式](#传入数据格式)
 - [元素数据绑定](#元素数据绑定)
 - [图片元素使用说明](#图片元素使用说明)
@@ -73,44 +79,172 @@ pnpm build:wc
 
 启动后浏览器访问 `http://localhost:5173` 即可看到设计器 Demo 页面（`index.html`）。
 
-### Vue 组件接入
+### Vue 组件接入（XPrintDesigner）
 
-**适用于：** 将设计器作为子组件嵌入已有 Vue 3 项目。
+**适用于：** Vue 3 项目以一等公民组件方式接入。`XPrintDesigner` 是 Web Component 的 Vue 适配层：props 声明式传参、事件自动透传、ref 暴露常用方法，**无需手动管理 `ready` 时序**。
 
 ```vue
 <template>
-  <PrintDesigner
-    mode="template"
-    :sample-data="sampleData"
-    :on-save="handleSave"
+  <XPrintDesigner
+    :config="config"
+    @checklist="onChecklist"
+    @printed="onPrinted"
   />
 </template>
 
 <script setup lang="ts">
 import { ref } from 'vue'
-import { PrintDesigner } from 'x-print-designer'
+import { XPrintDesigner } from 'x-print-designer'
 import 'x-print-designer/style.css'
 
-const sampleData = ref({
-  id: 1,
-  title: '报告标题',
-  customerName: '张三',
-  items: [
-    { name: '产品A', price: 100, quantity: 2 }
-  ]
+const config = ref({
+  mode: 'template',
+  testData: { id: 1, title: '报告标题', items: [{ name: '产品A', price: 100 }] },
+  onSave: async (payload) => {
+    await fetch('/api/templates/save', {
+      method: 'POST',
+      headers: { 'Content-Type': 'application/json' },
+      body: JSON.stringify(payload)
+    })
+  }
 })
 
-const handleSave = async (payload) => {
-  // payload: { id, name, data, isNew }
-  await fetch('/api/templates/save', {
-    method: 'POST',
-    headers: { 'Content-Type': 'application/json' },
-    body: JSON.stringify(payload)
-  })
+const onChecklist = (detail) => {
+  console.log('接入自检', detail.checks, '全部通过:', detail.allPassed)
+}
+const onPrinted = (detail) => {
+  console.log('打印完成', detail)
 }
 </script>
 ```
 
+**Props：**
+
+| 属性 | 类型 | 说明 |
+|------|------|------|
+| `config` | `DesignerInitConfig \| null` | 统一初始化配置（等价 `el.init(config)`），ready 前传入会自动排队 |
+| `mode` | `'template' \| 'report'` | 工作模式 |
+| `uiMode` | `'beginner' \| 'expert'` | 界面模式（简洁/完整） |
+| `viewMode` | `'edit' \| 'preview'` | 视图模式 |
+| `headless` | `boolean` | 无头模式 |
+| `onSave` | `(payload) => void \| Promise<void>` | 保存回调（映射 `setOnSave`） |
+| `theme` | `string` | 主题（映射 `setTheme`） |
+
+**事件：** `ready` / `print` / `printed` / `export` / `exported` / `error` / `checklist`，与 Web Component 同名事件一一对应。
+
+**ref 暴露方法：** `init(config)`、`setData(payload, options)`、`print(request)`、`export(request)`、`setOnSave(handler)`、`setPreviewMode(options)`。
+
+> 更完整的 API（`setTemplateLibrary`、`setCrudEndpoints`、`setVariables` 等）可通过 `ref.value.$el` 拿到底层 `<print-designer>` 元素后直接调用，或使用下方 Web Component 方式。
+
+### 5 分钟接入（推荐）
+
+**适用于：** 想用最少代码快速接入的宿主（任意前端技术栈）。
+
+只需 4 步、**≤10 行代码**，且**无需手动监听 `ready` 时序**：
+
+```html
+<!DOCTYPE html>
+<html lang="zh-CN">
+<head>
+  <meta charset="UTF-8" />
+  <!-- ① 引入脚本与样式 -->
+  <script type="module" src="/dist/print-designer.es.js"></script>
+  <link rel="stylesheet" href="/dist/print-designer.css" />
+</head>
+<body>
+  <!-- ② 放置组件标签 -->
+  <print-designer id="designer"></print-designer>
+
+  <script>
+    // ③ 一次性传入全部配置（init 方法通道）
+    const designer = document.getElementById('designer')
+    designer.init({
+      mode: 'template',
+      testData: { id: 1, title: '报告标题', items: [{ name: '产品A', price: 100 }] },
+      onSave: (payload) => {
+        fetch('/api/templates/save', {
+          method: 'POST',
+          headers: { 'Content-Type': 'application/json' },
+          body: JSON.stringify(payload)
+        })
+      }
+    })
+
+    // ④ 可选：监听接入自检结果
+    designer.addEventListener('checklist', (e) => {
+      console.log('接入自检', e.detail.checks, '全部通过:', e.detail.allPassed)
+    })
+  </script>
+</body>
+</html>
+```
+
+**方法通道 vs 属性通道（二选一）：**
+
+- **方法通道（推荐）**：直接调用 `el.init(config)`。`ready` 前调用会自动排队，`ready` 后自动应用，无需自己等事件。
+- **属性通道**：通过 `config` 属性声明式传入 JSON，效果等价：
+
+```html
+<print-designer
+  config='{"mode":"template","testData":{"id":1,"title":"报告标题"},"onSave":null}'
+></print-designer>
+```
+
+> 若 `config` 属性 JSON 解析失败，组件会派发 `error` 事件（`detail.scope === 'config'`）且不影响默认 UI。
+
+**接入自检 `checklist` 事件：** 组件在 `ready` 时自动派发，`detail` 形如 `{ checks: [{ name, passed, hint? }...], allPassed }`，检查项包括 `ready`、`dataChannel`、`printApi`、`exportApi`、`onSaveBound`、`monacoLoader`。若存在未通过项，控制台会出现 `[PrintDesigner] 接入自检未全部通过：...` 的 `warn` 提示（例如未配置 `onSave` 时 `onSaveBound` 为 `false`），便于快速定位遗漏。
+
+#### `init(config)` 完整配置字段
+
+`DesignerInitConfig` 一次调用即可完成全部初始化；`ready` 前调用自动排队，`ready` 后立即应用。**显式调用过的 setter 优先级高于 init 配置**（不会双写冲突）。
+
+| 字段 | 类型 | 说明 |
+|------|------|------|
+| `mode` | `'template' \| 'report'` | 工作模式 |
+| `viewMode` | `'edit' \| 'preview'` | 视图模式 |
+| `uiMode` | `'beginner' \| 'expert' \| null` | 界面模式（简洁/完整） |
+| `language` | `string` | 语言（`'zh'` / `'en'`） |
+| `headless` | `boolean` | 无头模式 |
+| `data` | `Record<string, any>` | 数据（走 `setData` 默认通道） |
+| `testData` | `Record<string, any>` | 测试/预览数据 |
+| `variables` | `Record<string, any>` | 运行时变量（打印/导出时覆盖 testData） |
+| `onSave` | `(payload) => void \| Promise<void> \| null` | 保存回调 |
+| `autoSave` | `{ enabled, intervalMs? }` | 自动保存 |
+| `fieldDictionary` | `DesignerFieldDictionary \| null` | 字段字典（变量面板中文标签） |
+| `textPolishHandler` | `(text) => Promise<string> \| null` | 文本润色处理器（宿主 AI 能力） |
+| `textPolishConfig` | `TextPolishConfig \| null` | 内置 DeepSeek 润色配置 |
+| `branding` | `{ title?, logoUrl?, showTitle?, showLogo? }` | 品牌标识 |
+| `theme` | `string` | 主题（`'light'` / `'dark'` / `'system'`） |
+| `printDefaults` | `DesignerPrintDefaults` | 默认打印/导出选项与连接设置 |
+| `previewMode` | `DesignerPreviewModeOptions` | 独立预览模式 |
+| `crud` | `{ mode?, endpoints?, config? }` | 远程 CRUD 配置（见[远程 CRUD 配置](#远程-crud-配置)） |
+
+**Vue 宿主 5 分钟接入（XPrintDesigner）：** 用法与 Web Component 完全等价，仅换为组件写法：
+
+```vue
+<template>
+  <XPrintDesigner :config="config" />
+</template>
+
+<script setup lang="ts">
+import { ref } from 'vue'
+import { XPrintDesigner } from 'x-print-designer'
+import 'x-print-designer/style.css'
+
+const config = ref({
+  mode: 'template',
+  testData: { id: 1, title: '报告标题', items: [{ name: '产品A', price: 100 }] },
+  onSave: async (payload) => {
+    await fetch('/api/templates/save', {
+      method: 'POST',
+      headers: { 'Content-Type': 'application/json' },
+      body: JSON.stringify(payload)
+    })
+  }
+})
+</script>
+```
+
 ### Web Component 接入
 
 **适用于：** 任意前端技术栈（React / Angular / 原生 HTML），以自定义标签方式嵌入。
@@ -242,9 +376,9 @@ designer.print({ mode: 'browser', options: { silent: true } })
 ### 切换模式
 
 ```vue
-<!-- Vue 组件 -->
-<PrintDesigner mode="template" />  <!-- 模板模式（默认） -->
-<PrintDesigner mode="report" />    <!-- 报告模式 -->
+<!-- Vue 组件（XPrintDesigner） -->
+<XPrintDesigner mode="template" />  <!-- 模板模式（默认） -->
+<XPrintDesigner mode="report" />    <!-- 报告模式 -->
 ```
 
 ```javascript
@@ -259,63 +393,72 @@ designer.setMode('report')
 
 ### 组件 Props
 
+`XPrintDesigner` 是 Web Component 的 Vue 适配层（从 `x-print-designer` 导出）。除下表 props 外，其余配置（数据、CRUD、品牌、主题等）统一通过 `config` 传入。
+
 | 属性 | 类型 | 默认值 | 说明 |
 |------|------|--------|------|
-| `mode` | `'template'` \| `'report'` | `'template'` | 工作模式，影响保存行为 |
-| `view-mode` | `'edit'` \| `'preview'` | `'edit'` | 视图模式，`'preview'` 时只渲染打印内容 |
+| `config` | `DesignerInitConfig \| null` | `null` | 统一初始化配置（等价 `el.init(config)`），见[init 完整配置](#initconfig-完整配置字段) |
+| `mode` | `'template'` \| `'report'` | — | 工作模式，影响保存行为 |
+| `uiMode` | `'beginner'` \| `'expert'` | — | 界面模式（简洁/完整） |
+| `viewMode` | `'edit'` \| `'preview'` | — | 视图模式，`'preview'` 时只渲染打印内容 |
 | `headless` | `boolean` | `false` | 无头模式，隐藏顶部工具栏和侧边栏 |
-| `sample-data` | `Record<string, any>` | — | 传入的示例/预览数据，详见[传入数据格式](#传入数据格式) |
-| `on-save` | `(payload) => void \| Promise<void>` | — | 保存回调，详见[保存回调](#保存回调-onsave) |
-| `auto-save-enabled` | `boolean` | `false` | 是否开启定时自动保存 |
-| `auto-save-interval-ms` | `number` | `120000` | 自动保存间隔（毫秒），默认 2 分钟 |
+| `onSave` | `(payload) => void \| Promise<void>` | — | 保存回调，详见[保存回调](#保存回调-onsave)（映射 `setOnSave`） |
+| `theme` | `string` | — | 主题（映射 `setTheme`） |
 
 ### Props 详细说明
 
-#### `mode`
+#### `config`
 
-工作模式，决定保存时是否附带 `testData`。
+**宿主接入的首选入口**：所有配置（数据、保存、CRUD、品牌、主题等）一次传入，等价于调用 `el.init(config)`。`ready` 前传入自动排队，`ready` 后自动应用。
 
 ```vue
-<PrintDesigner mode="report" />
+<XPrintDesigner :config="{
+  mode: 'report',
+  testData: { id: 1, title: '检测报告', items: [{ name: '产品A', price: 100 }] },
+  onSave: async (payload) => { await fetch('/api/reports/save', { method: 'POST', body: JSON.stringify(payload) }) },
+  autoSave: { enabled: true, intervalMs: 120000 },
+  crud: { mode: 'remote', endpoints: { /* ... */ } }
+}" />
 ```
 
-#### `view-mode`
+#### `mode`
 
-切换编辑/预览视图。设为 `'preview'` 时隐藏所有编辑器 UI，仅渲染打印页面。适用于嵌入第三方页面时只展示打印效果。
+工作模式，决定保存时是否附带 `testData`。
 
 ```vue
-<PrintDesigner view-mode="preview" />
+<XPrintDesigner mode="report" />
 ```
 
-#### `headless`
+#### `viewMode`
 
-无头模式，隐藏顶部工具栏和侧边属性面板。用于嵌入式场景仅保留画布区域。
+切换编辑/预览视图。设为 `'preview'` 时隐藏所有编辑器 UI，仅渲染打印页面。适用于嵌入第三方页面时只展示打印效果。
 
 ```vue
-<PrintDesigner headless />
+<XPrintDesigner view-mode="preview" />
 ```
 
-#### `sample-data`
+#### `headless`
 
-传入设计器的预览数据。**最关键的属性**。详见 [传入数据格式](#传入数据格式)。
+无头模式，隐藏顶部工具栏和侧边属性面板。用于嵌入式场景仅保留画布区域。
 
 ```vue
-<PrintDesigner :sample-data="{ id: 1, title: '报告', items: [...] }" />
+<XPrintDesigner headless />
 ```
 
-#### `on-save`
+#### `onSave`
 
-保存回调函数。传入后设计器**不再执行内置保存逻辑**，完全由用户自行处理持久化。
+保存回调函数。传入后设计器**不再执行内置保存逻辑**，完全由用户自行处理持久化。也可通过 `config.onSave` 传入，效果一致。
 
 ```vue
-<PrintDesigner :on-save="(payload) => mySaveApi(payload)" />
+<XPrintDesigner :on-save="(payload) => mySaveApi(payload)" />
 ```
 
 > 不传 `onSave` 时，设计器使用内置 CRUD 逻辑（根据配置调远程接口或存 localStorage）。
 
-#### `auto-save-enabled` / `auto-save-interval-ms`
+#### 预览数据与自动保存
 
-详见 [自动保存配置](#自动保存配置)。
+- 预览数据：通过 `config.testData`（等价 Web Component 的 `setTestData`，详见 [传入数据格式](#传入数据格式)）。
+- 自动保存：通过 `config.autoSave = { enabled, intervalMs? }` 开启（详见 [自动保存配置](#自动保存配置)）。
 
 ---
 
@@ -343,15 +486,29 @@ designer.setMode('report')
 
 | 方法 | 参数 | 返回值 | 说明 |
 |------|------|--------|------|
+| `init(config)` | `DesignerInitConfig` | `void` | 统一初始化入口（见[init 完整配置](#initconfig-完整配置字段)）。ready 前调用自动排队，ready 后自动应用 |
 | `setMode(mode)` | `'template'` \| `'report'` | `void` | 设置工作模式 |
 | `setViewMode(viewMode)` | `'edit'` \| `'preview'` | `void` | 切换视图模式 |
+| `setUIMode(mode)` | `'beginner'` \| `'expert'` | `void` | 切换界面模式（简洁/完整） |
 | `setOnSave(handler)` | `(payload) => void \| Promise<void>` | `void` | 设置保存回调 |
 | `setAutoSave(enabled, intervalMs?)` | `boolean, number?` | `void` | 开启/关闭自动保存，`intervalMs` 默认 120000 |
-| `setTestData(data)` | `Record<string, any>` | `void` | 设置测试/预览数据（等价 Vue 组件的 `sample-data`） |
-| `setSampleData(data)` | `Record<string, any>` | `void` | `setTestData` 的别名 |
-| `setVariables(vars)` | `Record<string, any>` | `void` | 打印/导出时注入真实变量（覆盖 testData 中的同名字段） |
+| `setTestData(data)` | `Record<string, any>` | `Promise<void>` | 设置测试/预览数据（等价 Vue 组件通过 `config.testData` 传入） |
+| `setSampleData(data)` | `Record<string, any>` | `Promise<void>` | `setTestData` 的别名 |
+| `setVariables(vars)` | `Record<string, any>` | `Promise<void>` | 打印/导出时注入真实变量（覆盖 testData 中的同名字段） |
+| `setTemplateVariables(vars)` | `Record<string, any>` | `Promise<void>` | 设置模板变量（按 `@键` 规范化后写入 variables） |
+| `setData(data, opts?)` | `Record<string, any>, DesignerDataOptions?` | `Promise<void>` | **统一数据注入入口**。`opts.channel` 可选 `variables`(默认)/`testData`/`sampleData`/`availableVariables`，读取优先级 `runtimeVariables > testData > sampleData`，见[数据通道与优先级](#数据通道与优先级) |
+| `getTestData()` | — | `Record<string, any>` | 获取当前测试数据 |
+| `getVariables()` | — | `Record<string, any>` | 获取当前运行时变量 |
+| `getTemplateVariables()` | — | `Record<string, any>` | 获取当前模板变量 |
+| `setFieldDictionary(dict)` | `Record<string, FieldItem>` | `void` | 设置字段字典（变量面板中显示中文标签） |
+| `setAvailableVariables(vars)` | `VariableTreeItem[]` | `void` | 设置可用变量树（字段选择提示） |
+| `setDataLoading(loading)` | `boolean` | `void` | 设置外部数据加载状态（展示 loading 遮罩） |
+| `setTextPolishHandler(handler)` | `(text) => Promise<string>` | `void` | 注入文本润色处理器（宿主侧 AI 能力，优先于内置 DeepSeek） |
+| `setTextPolishConfig(config)` | `TextPolishConfig` | `void` | 配置内置 DeepSeek 润色（`{ apiKey, baseURL?, model? }`） |
 | `setTemplates(list, opts?)` | `Array<Template>, object?` | `Promise<void>` | 设置预设模板列表并加载当前模板。`opts` 可选：`{ currentTemplateId?: string }`。返回的 Promise 在画布 pages 填充完成后 resolve，可据此消除时序竞态 |
 | `loadTemplate(id)` | `string` | `Promise<boolean>` | 加载指定模板到画布。resolve 时 pages 已填充；返回 `false` 表示因前置条件（如正在编辑自定义元素）未触发 |
+| `loadExampleTemplate(id)` | `string` | `Promise<boolean>` | 加载内置示例模板（复制为可编辑模板并加载；同名模板存在时直接加载） |
+| `setTemplateLibrary(list, opts?)` | `DesignerTemplateLibraryItem[], { mode?: 'replace' \| 'merge' }?` | `void` | 替换或合并示例模板库（场景化模板注入）。`mode: 'replace'`（默认）整体替换内置库；`'merge'` 同 id 覆盖、新 id 追加。影响空态与模板下拉的示例模板区。`category` 可复用内置场景 key（`device-run`/`inspection`/`event-feedback`/`other`）或自定义任意值 |
 | `loadTemplateData(data)` | `Record<string, any>` | `boolean` | 直接加载模板 JSON 数据到画布，返回是否成功 |
 | `getTemplateData()` | — | `Record<string, any>` | 获取当前模板完整数据 |
 | `getPreviewHtml()` | — | `Promise<string>` | 获取预览 HTML 字符串 |
@@ -362,9 +519,11 @@ designer.setMode('report')
 | `setBranding(config)` | `{ title?, logoUrl?, showTitle?, showLogo? }` | `void` | 设置品牌标识 |
 | `setLanguage(lang)` | `'zh'` \| `'en'` | `void` | 切换语言 |
 | `setCrudMode(mode, opts?)` | `'local'` \| `'remote'`, `{ skipAutoLoad?: boolean }` | `void` | 切换 CRUD 模式。`skipAutoLoad: true` 跳过 remote 模式下自动 `loadTemplates + loadTemplate` 的链式加载，适用于已通过 `setTemplates` 提供数据的场景，避免双次加载闪烁 |
+| `setCrudEndpoints(endpoints, opts?)` | `CrudEndpoints, { baseUrl?, headers?, fetcher? }` | `void` | 配置远程 CRUD 端点（templates/customElements 的 list/get/upsert/delete），详见[远程 CRUD 配置](#远程-crud-配置) |
+| `setAutoCollapseLoopPages(enabled)` | `boolean` | `void` | 切换保存时自动折叠循环页（默认开启）。关闭后需自行调用 `collapseLoopPages` |
 | `expandLoopPages(pages, ctx?)` | `Page[], LoopExpandContext?` | `Page[]` | 循环页展开：按 `page.loopDataVariable` + 数据数组，把 1 个模板页展开成 N 页。不传 `ctx` 时默认使用当前 store 数据（导出语义） |
 | `hasLoopPage(pages)` | `Page[]?` | `boolean` | 判断页面数组中是否含循环页 |
-| `collapseLoopPages(currentPages, originalPages)` | `Page[], Page[]` | `Page[]` | 折叠已展开的循环页，还原为带 `loopDataVariable` 的单个模板页。适用于报告模式保存前还原模板结构 |
+| `collapseLoopPages(currentPages, originalPages)` | `Page[], Page[]` | `Page[]` | 折叠已展开的循环页，还原为带 `loopDataVariable` 的单个模板页。保存流程已自动折叠，通常无需手动调用 |
 
 ### 事件参考
 
@@ -490,11 +649,150 @@ function backToEdit() {
 
 ---
 
+## 场景化模板库
+
+为降低业务人员上手门槛，模板下拉与空态页按**业务场景**分组展示内置示例模板，并支持搜索过滤。内置场景围绕无人机业务：
+
+| 场景 key | 场景名称 | 内置模板 |
+|----------|---------|---------|
+| `device-run` | 设备运行 | 设备档案卡、飞行任务记录、设备状态、电池电量、航程统计 |
+| `inspection` | 巡检记录 | 巡检报告、巡检任务明细、巡检缺陷记录、飞行日志 |
+| `event-feedback` | 事件反馈 | 告警汇总单、事件上报单、异常反馈单、处置结果单 |
+| `other` | 其他 | 通用示例（送货单等） |
+
+### 宿主注入模板库 `setTemplateLibrary`
+
+宿主可将自定义模板注入示例库：`mode: 'replace'`（默认）整体替换内置库；`mode: 'merge'` 同 `id` 覆盖、新 `id` 追加。注入后模板下拉与空态**响应式刷新**。
+
+```ts
+el.setTemplateLibrary([
+  {
+    id: 'biz-device-card',
+    name: '设备档案卡（自定义）',
+    description: '用于设备入库归档打印',
+    category: 'device-run', // 复用内置场景 key，或传自定义字符串（如 'biz'）
+    data: { pages: [/* ... */], canvasSize: { width: 794, height: 1123 } }
+  }
+], { mode: 'merge' })
+```
+
+> 模板数据 `data` 需包含 `pages`（非空元素数组）与 `canvasSize`；缺 `id`/`name` 或结构不合法的项会被自动丢弃。
+
+### 加载内置示例 `loadExampleTemplate`
+
+```ts
+// 按 id 加载内置示例模板：复制为可编辑模板并填充画布（同名模板已存在时直接加载）
+await el.loadExampleTemplate('example-device-status')
+```
+
+---
+
+## 数据驱动模板向导
+
+不熟悉画布设计的用户可直接从样例数据生成模板骨架：在模板下拉中选择 **"从数据生成模板"**，粘贴样例 JSON（或使用内置示例数据），设计器会：
+
+1. **推断字段结构**：识别标量字段（文本/数字/日期）与数组字段（对象数组 → 表格）。
+2. **生成基础骨架**：自动创建"标题 + 每字段一行 label + 数据表格"布局，表格自动绑定数组字段并渲染行。
+3. **加载进画布微调**：骨架加载后变量可正常解析，用户只需调整样式与排版。
+
+> 定位为**骨架生成**：不做像素级智能排版；生成的布局可在画布中自由微调，也可通过 `setTemplateLibrary` 沉淀为团队模板。
+
+---
+
+## 组合与取消组合
+
+画布支持将多个元素**组合为一个整体**操作（移动、缩放、复制、删除）：
+
+- **组合**：按住 `Ctrl`（Mac 为 `Cmd`）多选元素后，点击顶部工具栏 **"组合"** 按钮（或快捷键）。组合后属性面板显示"组合包含 N 个元素"。
+- **整体操作**：组合作为一个整体参与拖拽移动、八方向缩放（子元素等比联动）、复制粘贴（粘贴后子元素 id 自动再生，不会冲突）。
+- **取消组合**：选中组合后，属性面板点击 **"取消组合"**，成员恢复为独立元素（还原绝对坐标）。
+- **限制**：组合至少需要 2 个元素；已锁定元素不能参与组合。
+
+---
+
+## 数据通道与优先级
+
+设计器存在多条数据注入通道，为避免使用混淆，**读取时统一按以下优先级解析**（同 key 冲突时，优先级高的通道胜出）：
+
+```
+runtimeVariables（运行时变量，setVariables / setData variables）
+  > testData（模板测试数据，setTestData / setSampleData / setData testData）
+  > sampleData（宿主静态示例数据，仅兜底取值）
+  > ext.availableVariables（模板字段树声明，仅用于字段提示，不参与取值）
+```
+
+- **建议**：新接入的宿主统一使用 [`setData(data, options)`](#完整-api-参考) 一个入口，用 `options.channel` 选择写入通道；旧 4 个方法（`setTestData` / `setSampleData` / `setVariables` / `setTemplateVariables`）保留并作为 `setData` 的薄包装，行为不变。
+- **原则**：只统一"读取时"的 fallback 链，不合并存储，编辑态 / 打印态差异保持不变。
+
+```js
+// 打印/导出时覆盖预览数据（运行时变量优先级最高）
+designer.setData(
+  { items: [{ name: '巡检无人机', qty: 2, total: 12800 }] },
+  { channel: 'variables', merge: true }
+);
+```
+
+---
+
+## 远程 CRUD 配置
+
+不传 `onSave` 时，设计器走内置 CRUD：`local` 模式存 localStorage（默认），`remote` 模式调后端接口。宿主接入云存储需两步：
+
+### 1. 配置端点 `setCrudEndpoints`
+
+端点支持字符串（默认方法：list 用 GET、upsert 用 POST）或对象（自定义 `url` + `method`）。URL 支持相对路径（自动拼接 `baseUrl`）或**绝对路径**（忽略 `baseUrl`，便于对接第三方/微服务）：
+
+```ts
+el.setCrudEndpoints({
+  baseUrl: 'https://api.example.com', // 也可在 options 中传
+  templates: {
+    list: '/print/templates',                    // GET https://api.example.com/print/templates
+    get: '/print/templates/{id}',                // {id} 占位符会被真实 id 替换
+    upsert: '/print/templates',                  // POST（body 为模板对象）
+    delete: '/print/templates/{id}'
+  },
+  customElements: {
+    list: '/print/custom-elements',
+    get: '/print/custom-elements/{id}',
+    upsert: '/print/custom-elements',
+    delete: '/print/custom-elements/{id}'
+  }
+}, {
+  baseUrl: 'https://your-domain.com',
+  headers: { Authorization: 'Bearer xxx', 'X-Tenant-ID': '123' }
+})
+```
+
+### 2. 切换远程模式 `setCrudMode`
+
+```ts
+el.setCrudMode('remote') // 保存/删除/加载走远程 API；local 为默认（localStorage）
+```
+
+> 若已通过 `setTemplates` 自行提供数据，可传 `setCrudMode('remote', { skipAutoLoad: true })` 跳过 remote 模式下的自动链式加载，避免双次加载闪烁。
+
+### 后端接口约定（4 个端点 / 资源）
+
+| 端点 | 请求 | 响应要求 |
+|------|------|---------|
+| `list` | GET | 返回**模板/自定义元素数组**；渲染按返回顺序 |
+| `get` | GET `{id}` | 返回详情：模板含 `data` 与 `ext.availableVariables`；自定义元素含 `element` |
+| `upsert` | POST | 创建/更新；**必须返回真实 `id`** |
+| `delete` | DELETE `{id}` | 返回 `{ success: boolean }` |
+
+**通用约定：**
+
+- 每个资源（template / customElement）都有 `id`、`name`、`permissions`（`{ editable, deletable, copyable }`）、`updatedAt`、`ext` 字段。
+- **扩展字段一律放 `ext` 下**（如 `ext.category`、`ext.templateTags`、`ext.availableVariables`），不支持根级扁平自定义字段；前端按 key 合并对象、数组"后者覆盖"。
+- `permissions.editable: false` 时设计器进入只读模式（UI 与 Store/API 双层拦截）。
+
+---
+
 ## 传入数据格式
 
 ### 基本要求
 
-`sample-data` / `setTestData(data)` 接收一个普通的 JSON 对象。**唯一必填字段是 `id`**。
+`config.testData` / `setTestData(data)` 接收一个普通的 JSON 对象。**唯一必填字段是 `id`**。
 
 | 字段 | 类型 | 必填 | 说明 |
 |------|------|------|------|
@@ -772,18 +1070,28 @@ interface SavePayload {
 
 ```vue
 <template>
-  <PrintDesigner
+  <XPrintDesigner
     :mode="mode"
-    :sample-data="sampleData"
-    :on-save="handleSave"
+    :config="{
+      testData: sampleData,
+      onSave: handleSave
+    }"
   />
 </template>
 
 <script setup lang="ts">
 import { ref } from 'vue'
+import { XPrintDesigner } from 'x-print-designer'
+import 'x-print-designer/style.css'
 
 const mode = ref<'template' | 'report'>('template')
 
+const sampleData = ref({
+  id: 1,
+  title: '报告标题',
+  items: [{ name: '产品A', price: 100 }]
+})
+
 const handleSave = async (payload) => {
   // 根据模式决定 API 端点
   const endpoint = mode.value === 'template'
@@ -817,17 +1125,19 @@ const handleSave = async (payload) => {
 
 ### Vue 组件
 
-| 属性 | 类型 | 默认值 | 说明 |
+自动保存通过 `config.autoSave` 配置（`XPrintDesigner` 无独立 props，统一走 `config`）：
+
+| 字段 | 类型 | 默认值 | 说明 |
 |------|------|--------|------|
-| `auto-save-enabled` | `boolean` | `false` | 是否开启 |
-| `auto-save-interval-ms` | `number` | `120000` | 间隔（毫秒），默认 2 分钟 |
+| `autoSave.enabled` | `boolean` | `false` | 是否开启 |
+| `autoSave.intervalMs` | `number` | `120000` | 间隔（毫秒），默认 2 分钟 |
 
 ```vue
-<PrintDesigner
-  :on-save="handleSave"
-  :auto-save-enabled="true"
-  :auto-save-interval-ms="120000"
-/>
+<XPrintDesigner :config="{
+  testData: sampleData,
+  onSave: handleSave,
+  autoSave: { enabled: true, intervalMs: 120000 }
+}" />
 ```
 
 ### Web Component
@@ -1056,6 +1366,7 @@ await designer.export({ type: 'html', filename: '订单-2024' })
 | 线条 | `line` | 直线（支持实线/虚线/点线） |
 | 矩形 | `rect` | 矩形（支持圆角） |
 | 圆形 | `circle` | 圆形 |
+| 组合 | `group` | 多个元素的组合容器，作为整体移动/缩放/复制/删除（见[组合与取消组合](#组合与取消组合)） |
 
 ---
 
@@ -1153,9 +1464,9 @@ await designer.export({ type: 'html', filename: '订单-2024' })
 **原因：** 自动保存需要 `onSave` 回调。
 
 **排查步骤：**
-1. 确认同时传入了 `onSave` 和 `auto-save-enabled`
+1. 确认同时传入了 `onSave` 和 `config.autoSave = { enabled: true }`（Vue 组件）或调用了 `setAutoSave(true)`
 2. 自动保存仅在内容有变更时触发，未修改时不会保存
-3. 检查 `auto-save-interval-ms` 是否设置过短（频繁保存可能被节流）
+3. 检查 `autoSave.intervalMs` / `setAutoSave` 的间隔是否设置过短（频繁保存可能被节流）
 
 ---
 

package/dist/{JsBarcode-Ie7CY3Wt.js → JsBarcode-DSibbGlC.js}

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

package/dist/{JsBarcode-5g1FBqni.js → JsBarcode-DnTB2TYK.js}

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

package/dist/{browser-VQbZ-HlB.js → browser-CGxtUZAc.js}

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

package/dist/{browser-CdoI5PCM.js → browser-DG3U5_to.js}

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

package/dist/{dom-to-image-more.min-CyxmydGS.js → dom-to-image-more.min-skzBroxH.js}

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