x-print-designer 0.4.14 → 0.4.41

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,41 +79,243 @@ pnpm build:wc
 
 启动后浏览器访问 `http://localhost:5173` 即可看到设计器 Demo 页面（`index.html`）。
 
-### Vue 组件接入
+### Vue 组件接入（XPrintDesigner）
 
-**适用于：** 将设计器作为子组件嵌入已有 Vue 3 项目。
+**适用于：** Vue 3 项目以一等公民组件方式接入。`XPrintDesigner` 是 Web Component 的 Vue 适配层：props 声明式传参、事件自动透传、ref 暴露常用方法，**无需手动管理 `ready` 时序**。
+
+#### 基础用法（简化版）
+
+使用新增的工具函数，**从 700 行减少到 30 行**：
 
 ```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, createRestfulAdapter, buildFieldDictionary } from 'x-print-designer'
 import 'x-print-designer/style.css'
 
-const sampleData = ref({
-  id: 1,
-  title: '报告标题',
-  customerName: '张三',
-  items: [
-    { name: '产品A', price: 100, quantity: 2 }
-  ]
+// ✅ 使用 CRUD 适配器工厂（从 80 行减少到 10 行）
+const crudAdapter = createRestfulAdapter({
+  baseURL: '/backend',
+  endpoints: {
+    list: '/report/template/list',
+    get: '/report/template/detail/:id',
+    upsert: '/report/template/edit',
+  },
+  transform: {
+    request: (data) => ({
+      id: data.id,
+      name: data.name,
+      templateJson: JSON.stringify(data.data)
+    }),
+    response: (res) => res.records.map(r => ({
+      id: r.id,
+      name: r.name,
+      data: JSON.parse(r.templateJson)
+    }))
+  },
+  onSave: async (data) => {
+    await editTemplate(data)
+    ElMessage.success('保存成功')
+  }
 })
 
-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)
-  })
+// ✅ 使用字段字典工具函数（从 40 行减少到 3 行）
+const fieldDictionary = ref({})
+async function loadFieldDictionary() {
+  const modules = await getReportTemplateFields(['media', 'device', 'wayline'])
+  fieldDictionary.value = buildFieldDictionary(modules, { autoResolveConflicts: true })
+}
+loadFieldDictionary()
+
+const config = ref({
+  mode: 'template',
+  testData: { id: 1, title: '报告标题', items: [{ name: '产品A', price: 100 }] },
+  crud: {
+    mode: 'remote',
+    endpoints: crudAdapter.endpoints,
+    config: { fetcher: crudAdapter.fetcher }
+  },
+  fieldDictionary: fieldDictionary.value
+})
+
+const onChecklist = (detail) => {
+  console.log('接入自检', detail.checks, '全部通过:', detail.allPassed)
+}
+const onPrinted = (detail) => {
+  console.log('打印完成', detail)
+}
+</script>
+```
+
+#### 完整示例（不使用工具函数）
+
+```vue
+<template>
+  <XPrintDesigner
+    :config="config"
+    @checklist="onChecklist"
+    @printed="onPrinted"
+  />
+</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)
+    })
+  }
+})
+
+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>
 ```
 
@@ -242,9 +450,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 +467,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 +560,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 +593,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 +723,468 @@ 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 双层拦截）。
+
+---
+
+## 工具函数（v0.4.39+ 新增）
+
+为了降低宿主接入门槛，插件提供了开箱即用的工具函数，**将常见配置从数百行简化到几行**。
+
+### 1. CRUD 适配器工厂 `createRestfulAdapter`
+
+**问题：** 宿主需要写 80+ 行 `fetcher` 逻辑来适配后端 API。
+
+**解决：** 使用适配器工厂，**从 80 行减少到 10 行**。
+
+```ts
+import { createRestfulAdapter, adapterPresets } from 'x-print-designer'
+
+// 方式一：使用预设（Spring Boot / Laravel / Express）
+const adapter = createRestfulAdapter({
+  ...adapterPresets.springBoot('/api'),  // 自动配置端点路径
+  transform: {
+    request: (data) => ({
+      id: data.id,
+      name: data.name,
+      templateJson: JSON.stringify(data.data)
+    }),
+    response: (res) => res.records.map(r => ({
+      id: r.id,
+      name: r.name,
+      data: JSON.parse(r.templateJson)
+    }))
+  },
+  onSave: async (data) => {
+    await editTemplate(data)
+    ElMessage.success('保存成功')
+  }
+})
+
+// 方式二：自定义端点路径
+const adapter = createRestfulAdapter({
+  baseURL: '/backend',
+  endpoints: {
+    list: '/report/template/list',
+    get: '/report/template/detail/:id',  // 支持 :id 占位符
+    upsert: '/report/template/edit',
+    delete: '/report/template/delete/:id'
+  },
+  transform: { /* ... */ },
+  onSave: async (data) => { /* ... */ },
+  onError: (error, operation) => {
+    console.error(`Operation ${operation} failed:`, error)
+  }
+})
+
+// 应用到设计器
+designerEl.setCrudEndpoints(adapter.endpoints, { fetcher: adapter.fetcher })
+```
+
+**API：**
+
+```ts
+interface RestfulAdapterConfig {
+  baseURL: string
+  endpoints: {
+    list: string
+    get: string      // 支持 :id 占位符
+    upsert: string
+    delete?: string
+  }
+  transform?: {
+    request?: (data: any) => any      // 请求数据转换（保存时）
+    response?: (data: any) => any     // 响应数据转换（列表/详情）
+  }
+  onSave?: (data: any) => void | Promise<void>
+  onDelete?: (id: string) => void | Promise<void>
+  headers?: Record<string, string>
+  onError?: (error: Error, operation: 'list' | 'get' | 'upsert' | 'delete') => void
+}
+```
+
+### 2. 字段字典工具 `buildFieldDictionary`
+
+**问题：** 需要手动构建 40+ 行字典映射逻辑，处理字段冲突、模块前缀等。
+
+**解决：** 使用工具函数，**从 40 行减少到 3 行**。
+
+```ts
+import { buildFieldDictionary } from 'x-print-designer'
+
+// 获取字段列表
+const modules = await getReportTemplateFields(['media', 'device', 'wayline', 'task', 'event'])
+
+// 一行构建字典（自动处理字段名冲突）
+const dictionary = buildFieldDictionary(modules, {
+  autoResolveConflicts: true,  // 自动添加模块前缀解决冲突
+  prefixStrategy: 'auto',      // 'auto' | 'always' | 'never'
+  prefixSeparator: '.',        // 分隔符
+  filter: (field, module) => field.fieldType !== 'internal'  // 可选过滤器
+})
+
+// 应用到设计器
+designerEl.setFieldDictionary(dictionary)
+```
+
+**示例输入/输出：**
+
+```ts
+// 输入
+const modules = [
+  {
+    moduleKey: 'device',
+    moduleName: '设备信息',
+    fields: [
+      { fieldKey: 'id', labelCn: '设备ID', primaryKey: true },
+      { fieldKey: 'name', labelCn: '设备名称' }
+    ]
+  },
+  {
+    moduleKey: 'task',
+    moduleName: '任务信息',
+    fields: [
+      { fieldKey: 'id', labelCn: '任务ID', primaryKey: true },
+      { fieldKey: 'name', labelCn: '任务名称' }
+    ]
+  }
+]
+
+// 输出（自动解决 id 和 name 字段冲突）
+{
+  'device.id': { fieldKey: 'id', labelCn: '设备ID', moduleKey: 'device', ... },
+  'device.name': { fieldKey: 'name', labelCn: '设备名称', moduleKey: 'device', ... },
+  'task.id': { fieldKey: 'id', labelCn: '任务ID', moduleKey: 'task', ... },
+  'task.name': { fieldKey: 'name', labelCn: '任务名称', moduleKey: 'task', ... }
+}
+```
+
+**辅助函数：**
+
+```ts
+import { mergeFieldDictionaries, getFieldLabel } from 'x-print-designer'
+
+// 合并多个字典
+const merged = mergeFieldDictionaries([dict1, dict2, dict3], 'last')  // 'first' | 'last'
+
+// 根据语言获取标签
+const label = getFieldLabel(dictionary['device.name'], 'zh')  // '设备名称'
+```
+
+### 3. 自动样式注入
+
+**问题：** 宿主需要手动列举并注入 287 行 Tailwind/UnoCSS 样式类。
+
+**解决：** 插件自动检测并注入，**0 行代码**。
+
+```vue
+<template>
+  <!-- ✅ 无需任何样式注入代码，插件自动检测 Tailwind/UnoCSS/Element Plus 并注入 -->
+  <print-designer />
+</template>
+```
+
+**原理：** 插件在 `connectedCallback` 时自动扫描 `document.querySelectorAll('style')`，智能检测主流 CSS 框架并克隆到 Shadow DOM。
+
+**可选：禁用自动注入**
+
+```html
+<print-designer no-auto-style></print-designer>
+```
+
+### 4. 配置预设 `presets`
+
+**问题：** 每次都要从头配置模式、UI、主题等基础设置。
+
+**解决：** 使用场景预设，**1 行配置搞定**。
+
+```ts
+import { presets, mergePreset } from 'x-print-designer'
+
+// 方式一：直接使用预设
+const config = {
+  ...presets.uavReport,  // 无人机报告场景
+  onSave: handleSave
+}
+
+// 方式二：合并预设和自定义配置
+const config = mergePreset(presets.expressLabel, {
+  branding: { title: '我的快递单设计器' },
+  autoSave: { enabled: false }
+})
+```
+
+**可用预设：**
+
+| 预设名 | 场景 | 特点 |
+|--------|------|------|
+| `presets.uavReport` | 无人机报告 | report 模式 + beginner UI + 30s 自动保存 |
+| `presets.expressLabel` | 物流快递单 | template 模式 + expert UI + 60s 自动保存 |
+| `presets.invoice` | 发票/票据 | template 模式 + expert UI + 60s 自动保存 |
+| `presets.label` | 标签/吊牌 | template 模式 + beginner UI + 60s 自动保存 |
+| `presets.certificate` | 证书/证明 | template 模式 + beginner UI + 不自动保存 |
+| `presets.contract` | 合同/协议 | template 模式 + expert UI + 30s 自动保存 |
+| `presets.generalReport` | 通用报告 | report 模式 + beginner UI + 30s 自动保存 |
+
+### 5. Vue Composable `useDesigner`
+
+**问题：** Vue 宿主仍需手动管理 ref、ready、初始化等。
+
+**解决：** 使用 composable，**自动处理一切**。
+
+```vue
+<template>
+  <print-designer ref="designerRef" />
+</template>
+
+<script setup lang="ts">
+import { useDesigner, createRestfulAdapter } from 'x-print-designer/vue'
+
+const { designerRef, ready, setData, exportPdf } = useDesigner({
+  mode: 'template',
+  crudAdapter: createRestfulAdapter({
+    baseURL: '/api',
+    endpoints: { list: '/templates', get: '/templates/:id', upsert: '/templates' },
+    onSave: async (data) => { await saveTemplate(data) }
+  }),
+  fieldModules: ['media', 'device'],
+  fieldLoader: async (modules) => {
+    return await getReportTemplateFields(modules)
+  },
+  onError: (error) => {
+    ElMessage.error('设计器错误: ' + error.message)
+  }
+})
+
+// ✅ 使用非常简单
+const handleExport = async () => {
+  await exportPdf('我的模板.pdf')
+}
+</script>
+```
+
+**API：**
+
+```ts
+interface UseDesignerOptions {
+  mode?: 'template' | 'report'
+  uiMode?: 'beginner' | 'expert'
+  crudAdapter?: ReturnType<typeof createRestfulAdapter>
+  fieldModules?: string[]               // 自动加载字段字典
+  fieldLoader?: (modules: string[]) => Promise<FieldDictionaryModule[]>
+  onSave?: (data: any) => void | Promise<void>
+  onError?: (error: any) => void
+  autoInit?: boolean                    // 默认 true
+}
+
+interface UseDesignerReturn {
+  designerRef: Ref<any>
+  ready: Ref<boolean>
+  setData: (data: any) => void
+  setTestData: (data: any) => void
+  setVariables: (data: any) => void
+  exportPdf: (filename?: string) => Promise<void>
+  exportImage: (filename?: string) => Promise<void>
+  print: (request?: any) => Promise<void>
+  getDesignerElement: () => any
+  init: () => Promise<void>
+}
+```
+
+### 6. 诊断工具 `diagnoseIntegration`
+
+**问题：** 集成出问题时不知道哪里配置错了。
+
+**解决：** 使用诊断工具，**自动检查 12 项配置**。
+
+```ts
+import { diagnoseIntegration, exportDiagnosticReport } from 'x-print-designer/diagnostics'
+
+// 运行诊断
+const diagnosis = diagnoseIntegration(designerEl)
+
+if (!diagnosis.allPassed) {
+  console.warn('集成检查未通过：', diagnosis.failedChecks)
+  
+  // 导出诊断报告
+  exportDiagnosticReport(diagnosis, 'my-diagnostic.md')
+}
+```
+
+**检查项：**
+
+| 检查项 | 级别 | 说明 |
+|--------|------|------|
+| Element Exists | 🔴 关键 | 元素是否存在 |
+| Ready State | 🔴 关键 | 是否已就绪 |
+| Shadow DOM | 🔴 关键 | Shadow DOM 是否初始化 |
+| Styles Injected | 🟡 警告 | 样式是否注入 |
+| CRUD Configured | 🟡 警告 | CRUD 是否配置 |
+| Save Handler | 🟡 警告 | 保存回调是否配置 |
+| Data API | ℹ️ 信息 | 数据 API 是否可用 |
+| Print API | ℹ️ 信息 | 打印 API 是否可用 |
+| Export API | ℹ️ 信息 | 导出 API 是否可用 |
+| Monaco Loader | ℹ️ 信息 | 代码编辑器是否可用 |
+| Field Dictionary | ℹ️ 信息 | 字段字典是否配置 |
+| Auto Style Injection | ℹ️ 信息 | 自动样式注入是否生效 |
+
+**诊断结果示例：**
+
+```
+✅ [PrintDesigner] 集成检查全部通过
+
+或
+
+❌ 关键问题： Ready State, Shadow DOM
+  - Ready State: 设计器尚未就绪，请等待 ready 事件
+  - Shadow DOM: Shadow DOM 未初始化
+
+⚠️  警告： Save Handler
+  - Save Handler: 未配置 onSave 回调，保存功能将不可用
+```
+
+---
+
 ## 传入数据格式
 
 ### 基本要求
 
-`sample-data` / `setTestData(data)` 接收一个普通的 JSON 对象。**唯一必填字段是 `id`**。
+`config.testData` / `setTestData(data)` 接收一个普通的 JSON 对象。**唯一必填字段是 `id`**。
 
 | 字段 | 类型 | 必填 | 说明 |
 |------|------|------|------|
@@ -772,18 +1462,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 +1517,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 +1758,7 @@ await designer.export({ type: 'html', filename: '订单-2024' })
 | 线条 | `line` | 直线（支持实线/虚线/点线） |
 | 矩形 | `rect` | 矩形（支持圆角） |
 | 圆形 | `circle` | 圆形 |
+| 组合 | `group` | 多个元素的组合容器，作为整体移动/缩放/复制/删除（见[组合与取消组合](#组合与取消组合)） |
 
 ---
 
@@ -1153,9 +1856,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` 的间隔是否设置过短（频繁保存可能被节流）
 
 ---