x-print-designer 0.4.72 → 0.4.97

package/README.md

@@ -1,1881 +1,1883 @@
-# X-Print-Designer
-
-基于 Vue 3 + TypeScript 开发的打印设计器，支持可视化拖拽设计打印模板，集成 ECharts 图表组件。
-
----
-
-## 目录
-
-- [前置依赖要求](#前置依赖要求)
-- [快速开始](#快速开始)
-  - [源码开发](#源码开发)
-  - [Vue 组件接入（XPrintDesigner）](#vue-组件接入xprintdesigner)
-  - [5 分钟接入（推荐）](#5-分钟接入推荐)
-  - [Web Component 接入](#web-component-接入)
-- [核心概念：模板模式 vs 报告模式](#核心概念模板模式-vs-报告模式)
-- [Vue 组件使用说明](#vue-组件使用说明)
-- [Web Component 使用说明](#web-component-使用说明)
-  - [完整 API 参考](#完整-api-参考)
-  - [场景化模板库](#场景化模板库)
-  - [数据驱动模板向导](#数据驱动模板向导)
-  - [组合与取消组合](#组合与取消组合)
-  - [远程 CRUD 配置](#远程-crud-配置)
-- [传入数据格式](#传入数据格式)
-- [元素数据绑定](#元素数据绑定)
-- [图片元素使用说明](#图片元素使用说明)
-- [保存回调 `onSave`](#保存回调-onsave)
-- [自动保存配置](#自动保存配置)
-- [打印与导出](#打印与导出)
-- [模板数据结构](#模板数据结构)
-- [支持的元素类型](#支持的元素类型)
-- [版本兼容性说明](#版本兼容性说明)
-- [常见问题排查](#常见问题排查)
-- [技术栈](#技术栈)
-
----
-
-## 前置依赖要求
-
-| 依赖 | 最低版本 | 说明 |
-|------|---------|------|
-| **Node.js** | `>= 18` | 运行时环境 |
-| **pnpm** | `>= 8` | 推荐包管理器（项目使用 `pnpm-lock.yaml`） |
-| **Vue** | `^3.5` | 核心框架 |
-
-### 浏览器兼容性
-
-| 浏览器 | 最低版本 | 说明 |
-|--------|---------|------|
-| Chrome | >= 90 | 完全支持 |
-| Edge | >= 90 | 完全支持 |
-| Firefox | >= 90 | 完全支持 |
-| Safari | >= 15 | 完全支持 |
-
-> **说明：** 设计器基于现代浏览器 API（`ResizeObserver`、`CSS Grid`、`Shadow DOM`），不支持 IE 11 及以下版本。
-
----
-
-## 快速开始
-
-### 源码开发
-
-```bash
-# 克隆仓库
-git clone https://github.com/0ldFive/Vue-Print-Designer.git
-cd x-print-designer
-
-# 安装依赖
-pnpm install
-
-# 启动开发服务器
-pnpm dev
-
-# 构建生产包
-pnpm build
-
-# 构建 Web Component 包
-pnpm build:wc
-```
-
-启动后浏览器访问 `http://localhost:5173` 即可看到设计器 Demo 页面（`index.html`）。
-
-### Vue 组件接入（XPrintDesigner）
-
-**适用于：** Vue 3 项目以一等公民组件方式接入。`XPrintDesigner` 是 Web Component 的 Vue 适配层：props 声明式传参、事件自动透传、ref 暴露常用方法，**无需手动管理 `ready` 时序**。
-
-#### 基础用法（简化版）
-
-使用新增的工具函数，**从 700 行减少到 30 行**：
-
-```vue
-<template>
-  <XPrintDesigner
-    :config="config"
-    @checklist="onChecklist"
-    @printed="onPrinted"
-  />
-</template>
-
-<script setup lang="ts">
-import { ref } from 'vue'
-import { XPrintDesigner, createRestfulAdapter, buildFieldDictionary } from 'x-print-designer'
-import 'x-print-designer/style.css'
-
-// ✅ 使用 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('保存成功')
-  }
-})
-
-// ✅ 使用字段字典工具函数（从 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>
-```
-
-### Web Component 接入
-
-**适用于：** 任意前端技术栈（React / Angular / 原生 HTML），以自定义标签方式嵌入。
-
-```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>
-    const designer = document.getElementById('designer')
-
-    designer.addEventListener('ready', () => {
-      designer.setMode('template')
-      designer.setTestData({
-        id: 1,
-        title: '报告标题',
-        items: [{ name: '产品A', price: 100 }]
-      })
-      designer.setOnSave((payload) => {
-        fetch('/api/templates/save', {
-          method: 'POST',
-          headers: { 'Content-Type': 'application/json' },
-          body: JSON.stringify(payload)
-        })
-      })
-    })
-  </script>
-</body>
-</html>
-```
-
----
-
-## 核心概念：模板模式 vs 报告模式
-
-设计器支持两种工作模式，通过 `mode` 属性/方法进行切换。
-
-### 概念说明
-
-| 概念 | 说明 |
-|------|------|
-| **模板 (Template)** | 页面布局设计，包含元素位置、样式、画布大小等 |
-| **数据 (Data)** | 业务数据，如订单信息、报告内容、用户信息等 |
-| **模板 ID** | 模板的唯一标识，用于关联和加载模板 |
-| **数据 ID** | 业务数据的唯一标识，如订单 ID、报告 ID |
-
-### 模板模式（`template`）— 默认
-
-**设计理念：** 模板与数据分离，一个模板可绑定多个不同的数据。
-
-**适用场景：**
-- 订单打印（同一订单模板，打印不同订单）
-- 标签打印（同一标签模板，打印不同商品）
-- 快递单据（同一单据模板，打印不同收件人）
-
-**保存行为：** 保存时**只保存页面布局**（元素位置、样式、画布大小等），**不保存** `testData`。
-
-### 报告模式（`report`）
-
-**设计理念：** 数据与布局绑定，保存的是完整的报告快照。
-
-**适用场景：**
-- 检测报告（每次检测结果 + 固定格式的报告模板）
-- 数据报表（当前统计数据的可视化呈现）
-- 档案文件（包含具体数据的完整文档）
-
-**保存行为：** 保存时**同时保存页面布局 + testData**。
-
-### 两种模式对比
-
-| 特性 | `template` 模板模式 | `report` 报告模式 |
-|------|-------------------|------------------|
-| 保存布局 | ✅ | ✅ |
-| 保存 testData | ❌ | ✅ |
-| 数据与模板关系 | 分离，运行时注入 | 绑定，一起保存 |
-| 模板复用性 | 高，可用于多个数据 | 低，针对当前数据 |
-| 典型用途 | 订单打印、标签 | 检测报告、数据报表 |
-
-### 使用示例
-
-**模板模式（推荐用于可复用模板）：**
-
-```javascript
-// 1. 编辑模板时传入预览数据
-const sampleData = {
-  id: null,               // 无需数据 ID，仅用于预览
-  orderNo: 'PREVIEW-001',
-  customerName: '预览客户'
-}
-
-// 2. 保存模板（只保存布局，不含 testData）
-// payload.data 中不包含 testData
-
-// 3. 打印时动态注入真实数据
-designer.loadTemplate('tpl-order')
-designer.setVariables({
-  orderNo: 'ORD-2024-001',
-  customerName: '张三'
-})
-designer.print({ mode: 'browser', options: { silent: true } })
-```
-
-**报告模式（推荐用于完整报告）：**
-
-```javascript
-// 1. 编辑报告时传入完整数据
-const sampleData = {
-  id: 8,                  // 报告 ID
-  title: '2024年第一季度销售报告',
-  totalAmount: 50000,
-  items: [...]
-}
-
-// 2. 保存报告（布局 + 数据一起保存）
-// payload.data 中包含完整的 testData
-
-// 3. 加载后直接打印，无需再次注入数据
-designer.loadTemplate(8)
-designer.print({ mode: 'browser', options: { silent: true } })
-```
-
-### 切换模式
-
-```vue
-<!-- Vue 组件（XPrintDesigner） -->
-<XPrintDesigner mode="template" />  <!-- 模板模式（默认） -->
-<XPrintDesigner mode="report" />    <!-- 报告模式 -->
-```
-
-```javascript
-// Web Component
-designer.setMode('template')
-designer.setMode('report')
-```
-
----
-
-## Vue 组件使用说明
-
-### 组件 Props
-
-`XPrintDesigner` 是 Web Component 的 Vue 适配层（从 `x-print-designer` 导出）。除下表 props 外，其余配置（数据、CRUD、品牌、主题等）统一通过 `config` 传入。
-
-| 属性 | 类型 | 默认值 | 说明 |
-|------|------|--------|------|
-| `config` | `DesignerInitConfig \| null` | `null` | 统一初始化配置（等价 `el.init(config)`），见[init 完整配置](#initconfig-完整配置字段) |
-| `mode` | `'template'` \| `'report'` | — | 工作模式，影响保存行为 |
-| `uiMode` | `'beginner'` \| `'expert'` | — | 界面模式（简洁/完整） |
-| `viewMode` | `'edit'` \| `'preview'` | — | 视图模式，`'preview'` 时只渲染打印内容 |
-| `headless` | `boolean` | `false` | 无头模式，隐藏顶部工具栏和侧边栏 |
-| `onSave` | `(payload) => void \| Promise<void>` | — | 保存回调，详见[保存回调](#保存回调-onsave)（映射 `setOnSave`） |
-| `theme` | `string` | — | 主题（映射 `setTheme`） |
-
-### Props 详细说明
-
-#### `config`
-
-**宿主接入的首选入口**：所有配置（数据、保存、CRUD、品牌、主题等）一次传入，等价于调用 `el.init(config)`。`ready` 前传入自动排队，`ready` 后自动应用。
-
-```vue
-<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: { /* ... */ } }
-}" />
-```
-
-#### `mode`
-
-工作模式，决定保存时是否附带 `testData`。
-
-```vue
-<XPrintDesigner mode="report" />
-```
-
-#### `viewMode`
-
-切换编辑/预览视图。设为 `'preview'` 时隐藏所有编辑器 UI，仅渲染打印页面。适用于嵌入第三方页面时只展示打印效果。
-
-```vue
-<XPrintDesigner view-mode="preview" />
-```
-
-#### `headless`
-
-无头模式，隐藏顶部工具栏和侧边属性面板。用于嵌入式场景仅保留画布区域。
-
-```vue
-<XPrintDesigner headless />
-```
-
-#### `onSave`
-
-保存回调函数。传入后设计器**不再执行内置保存逻辑**，完全由用户自行处理持久化。也可通过 `config.onSave` 传入，效果一致。
-
-```vue
-<XPrintDesigner :on-save="(payload) => mySaveApi(payload)" />
-```
-
-> 不传 `onSave` 时，设计器使用内置 CRUD 逻辑（根据配置调远程接口或存 localStorage）。
-
-#### 预览数据与自动保存
-
-- 预览数据：通过 `config.testData`（等价 Web Component 的 `setTestData`，详见 [传入数据格式](#传入数据格式)）。
-- 自动保存：通过 `config.autoSave = { enabled, intervalMs? }` 开启（详见 [自动保存配置](#自动保存配置)）。
-
----
-
-## Web Component 使用说明
-
-### 加载方式
-
-```html
-<!-- ES Module 方式（推荐） -->
-<script type="module" src="/dist/print-designer.es.js"></script>
-<link rel="stylesheet" href="/dist/print-designer.css" />
-
-<!-- 或 UMD 方式 -->
-<script src="/dist/print-designer.umd.js"></script>
-<link rel="stylesheet" href="/dist/print-designer.css" />
-```
-
-```html
-<print-designer id="designer"></print-designer>
-```
-
-### 完整 API 参考
-
-所有方法均通过 DOM 元素直接调用。**必须在 `ready` 事件触发后调用。**
-
-| 方法 | 参数 | 返回值 | 说明 |
-|------|------|--------|------|
-| `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>` | `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 字符串 |
-| `print(options?)` | `PrintOptions` | `Promise<void>` | 执行打印，详见[打印与导出](#打印与导出) |
-| `export(options?)` | `ExportOptions` | `Promise<void>` | 导出 PDF / 图片 / HTML，详见[打印与导出](#打印与导出) |
-| `setPreviewMode(options)` | `PreviewModeOptions` | `void` | 进入独立预览面板模式。传入的 `pages` 若含循环页（`loopDataVariable`），预览时会自动按数据展开成 N 页 |
-| `exitPreviewMode()` | — | `void` | 退出预览模式，返回编辑器 |
-| `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` 的单个模板页。保存流程已自动折叠，通常无需手动调用 |
-
-### 事件参考
-
-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` 更可靠。
-
-### 基本使用示例
-
-```javascript
-const designer = document.getElementById('designer')
-
-designer.addEventListener('ready', () => {
-  // 设置模式
-  designer.setMode('template')
-
-  // 设置数据
-  designer.setTestData({
-    id: 1,
-    orderNo: 'ORD-001',
-    customerName: '张三',
-    items: [
-      { name: '产品A', price: 100, quantity: 2 },
-      { name: '产品B', price: 200, quantity: 3 }
-    ]
-  })
-
-  // 保存回调
-  designer.setOnSave(async (payload) => {
-    console.log('保存:', payload)
-    await fetch('/api/templates/save', {
-      method: 'POST',
-      headers: { 'Content-Type': 'application/json' },
-      body: JSON.stringify(payload)
-    })
-  })
-
-  // 开启自动保存（每 2 分钟）
-  designer.setAutoSave(true, 120000)
-})
-```
-
-### 打印时注入真实数据
-
-使用 `setVariables` 在打印/导出时覆盖预览数据中的字段：
-
-```javascript
-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 } })
-```
-
-### 独立预览面板
-
-当设计器嵌入第三方页面时，可切换到独立的**纯预览模式**——只渲染打印内容，不显示编辑器 UI。
-
-**适用于：** 插件/第三方页面嵌入时的打印预览、用户填写表单后的预览、无需编辑功能的只读场景。
-
-#### `setPreviewMode(options)`
-
-```typescript
-interface PreviewModeOptions {
-  pages: Page[]                              // 页面元素布局（必填）
-  canvasSize: { width: number; height: number } // 画布尺寸（必填）
-  canvasBackground?: string                  // 画布背景色，默认 '#ffffff'
-  testData?: Record<string, any>            // 测试数据
-  variables?: Record<string, any>           // 额外变量映射
-  watermark?: WatermarkSettings             // 水印配置
-}
-```
-
-#### 使用示例
-
-```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()` 会自动恢复进入预览前的编辑器状态（模板选择、编辑进度等）。
-
----
-
-## 场景化模板库
-
-为降低业务人员上手门槛，模板下拉与空态页按**业务场景**分组展示内置示例模板，并支持搜索过滤。内置场景围绕无人机业务：
-
-| 场景 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 回调，保存功能将不可用
-```
-
----
-
-## 传入数据格式
-
-### 基本要求
-
-`config.testData` / `setTestData(data)` 接收一个普通的 JSON 对象。**唯一必填字段是 `id`**。
-
-| 字段 | 类型 | 必填 | 说明 |
-|------|------|------|------|
-| `id` | `number` \| `string` | ✅ 是 | 业务数据的唯一标识，如报告 ID、订单 ID |
-| `templateId` | `string` | 否 | 绑定的模板 ID，不传则用当前已选模板 |
-| `name` | `string` | 否 | 数据名称 |
-| `variables` | `object` | 否 | 业务变量对象（推荐，用于组织数据） |
-| 任意自定义字段 | `any` | 否 | 也可直接在根级别存放变量 |
-
-### 两种组织方式（任选其一，自动兼容）
-
-#### 方式一：带 `variables` 包装（推荐）
-
-```json
-{
-  "id": 8,
-  "name": "测试报告",
-  "templateId": "tpl_report",
-  "variables": {
-    "title": "报告标题",
-    "customerName": "张三",
-    "items": [
-      { "name": "产品A", "price": 100, "quantity": 2 }
-    ],
-    "chartData": [
-      { "category": "一月", "value": 1200 }
-    ]
-  }
-}
-```
-
-模板绑定：`@title`、`@customerName`、`@items`、`@chartData`
-
-#### 方式二：扁平数据
-
-```json
-{
-  "id": 8,
-  "name": "测试报告",
-  "title": "报告标题",
-  "customerName": "张三",
-  "items": [
-    { "name": "产品A", "price": 100, "quantity": 2 }
-  ],
-  "chartData": [
-    { "category": "一月", "value": 1200 }
-  ]
-}
-```
-
-模板绑定：`@title`、`@customerName`、`@items`、`@chartData`
-
-> 两种方式等效。设计器内部优先在 `variables` 中查找，未找到则在根级别查找。
-
-### 支持的数据类型
-
-| 类型 | 示例 | 模板绑定 |
-|------|------|---------|
-| 字符串 | `"张三"` | `@customerName` |
-| 数字 | `100` | `@totalAmount` |
-| 布尔值 | `true` | `@isPaid` |
-| 数组 | `[{...}, {...}]` | `@items` |
-| 嵌套对象 | `{ user: { name: "李四" } }` | `@user.name` |
-
-### 表格数据
-
-表格元素需要三个维度的变量绑定：
-
-| 绑定属性 | 变量名示例 | 数据格式 | 说明 |
-|---------|-----------|---------|------|
-| `variable` | `@items` | `Array<Object>` | 表格行数据 |
-| `columnsVariable` | `@tableCols` | `Array<{field, header, width}>` | 列定义 |
-| `footerDataVariable` | `@tableFooter` | `Array<Object>` | 页脚汇总行 |
-
-```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" } }
-  ]
-}
-```
-
-### 图表数据
-
-```json
-{
-  "chartData": [
-    { "category": "一月", "value": 1200 },
-    { "category": "二月", "value": 1500 }
-  ]
-}
-```
-
-图表元素需在属性面板中配置：
-- **chartDataVariable**：`@chartData`
-- **chartXField**：`category`（X 轴字段名）
-- **chartYField**：`value`（Y 轴字段名）
-- **chartNameField**：`category`（饼图名称字段）
-
-### 完整示例数据
-
-```json
-{
-  "id": 8,
-  "name": "宝安机场飞行任务记录",
-  "templateId": "tpl_report_drone",
-  "createTime": "2026-05-01",
-  "variables": {
-    "dockname": "宝安国际无人机机场",
-    "dronesn": "6EE5NC104E0PY6",
-    "dronename": "M300 RTK",
-    "reportname": "宝安机场飞行任务记录报告",
-    "tasktype": "航线巡检",
-    "totalcount": 4,
-    "totaldistance": "48.6 km",
-    "conclusion": "本轮飞行任务覆盖宝安区重点航线，数据采集完整。",
-    "flightRecords": [
-      {
-        "time": "2026-04-02 09:30",
-        "taskname": "宝安港区A线巡检",
-        "dockname": "宝安国际无人机机场",
-        "distance": "12.5 km",
-        "image": "https://picsum.photos/id/1/200/80"
-      }
-    ],
-    "chartData": [
-      { "category": "一月", "value": 1200 },
-      { "category": "二月", "value": 1500 }
-    ]
-  }
-}
-```
-
-### 注意事项
-
-1. **`id` 字段**
-   - 业务数据的唯一标识，在保存回调中用于识别当前编辑的数据
-   - 不传则保存时 `payload.id` 为 `null`
-
-2. **`id` 与 `templateId` 的区别**
-   - `id`：业务数据的标识（报告中用作报告 ID）
-   - `templateId`：打印模板的标识，两者是完全不同的概念
-
-3. **变量命名**
-   - 使用 camelCase 命名，如 `customerName` 而非 `c`
-   - 避免特殊字符和空格
-   - 嵌套路径使用点号：`@user.profile.name`
-
-4. **数组数据**
-   - 表格和图表需要数组类型
-   - 数组元素应包含一致的字段结构：`items: [{name: "A", price: 100}, {name: "B", price: 200}]`
-
-5. **动态更新**
-   - Web Component 通过 `setSampleData()` / `setTestData()` 更新
-   - 数据更新后，画布中的变量绑定会自动重新解析
-
----
-
-## 元素数据绑定
-
-### 变量语法
-
-| 语法 | 示例 | 说明 |
-|-----|------|------|
-| `@变量名` | `@customerName` | 直接引用变量 |
-| `{#变量路径}` | `{#order.items[0].name}` | 支持嵌套路径和数组索引 |
-
-### 各元素可绑定字段
-
-| 元素 | 绑定属性 | 示例 |
-|------|---------|------|
-| 文本 / 长文本 | `content` | `订单号: {#orderNo}` |
-| 图片 | `variable` | `@imageUrl` |
-| 表格 | `variable` + `columnsVariable` + `footerDataVariable` | `@items`, `@tableCols`, `@tableFooter` |
-| 自定义表格 | `customTableCells[].field` | `@customerName`（单元格字段） |
-| 条形码 | `variable` 或 `content` | `@barcode` |
-| 二维码 | `variable` 或 `content` | `@url` |
-| 图表 | `chartDataVariable` + `chartXField` + `chartYField` | `@chartData`, `category`, `value` |
-| 数据卡片 | `variable` | `@totalAmount` |
-| 进度条 | `variable` | `@progress` |
-| 日期 | `variable` | `@createTime` |
-
----
-
-## 图片元素使用说明
-
-### 方式 1：直接输入图片 URL
-
-在属性面板的"图片地址"输入框填写 URL（支持 HTTP/HTTPS）。
-
-```
-https://example.com/logo.png
-```
-
-### 方式 2：本地上传（自动转 Base64）
-
-点击属性面板中的 **"上传图片"** 按钮或**双击画布上的图片元素**，从本地选择图片文件：
-- 自动转为 Base64 并填入图片地址
-- 限制最大 **2MB**
-- 支持 PNG、JPG、GIF、WebP 等格式
-
-### 方式 3：绑定变量
-
-将 `variable` 绑定到变量名，图片地址从数据中动态读取。
-
-| 绑定方式 | 示例 | 数据值要求 |
-|---------|------|-----------|
-| 静态变量 | `@logoUrl` | 字符串 URL 或 Base64 |
-| 数组元素 | `@flightRecords[0].image` | 该字段值为 URL 或 Base64 |
-
-**对应数据：**
-
-```json
-{
-  "variables": {
-    "logoUrl": "https://example.com/logo.png",
-    "avatarBase64": "data:image/png;base64,iVBORw0KGgo...",
-    "flightRecords": [
-      { "image": "https://picsum.photos/id/1/200/80" }
-    ]
-  }
-}
-```
-
-### 方式对比
-
-| 方式 | 适用场景 | 存储内容 |
-|------|---------|---------|
-| URL 输入 | 固定图片、CDN 资源 | URL 字符串 |
-| 本地上传 | 无公网链接的图片 | Base64 编码 |
-| 变量绑定 | 每条数据图片不同 | URL 或 Base64 |
-
----
-
-## 保存回调 `onSave`
-
-传入 `onSave` 后，用户保存（`Ctrl+S` 或工具栏保存按钮）时设计器不再自动持久化，而是将组装好的数据通过回调交给用户自行处理。
-
-### 回调参数
-
-```typescript
-interface SavePayload {
-  id: string | null      // 模板 ID，null 表示新建
-  name: string           // 模板名称
-  data: Record<string, any>  // 模板数据（含 pages、canvasSize、watermark 等）
-  isNew: boolean         // 是否新建模板
-}
-```
-
-### 不同模式下 data 内容差异
-
-| 字段 | 模板模式 | 报告模式 |
-|------|---------|---------|
-| `pages` | ✅ | ✅ |
-| `canvasSize` | ✅ | ✅ |
-| `watermark` | ✅ | ✅ |
-| `guides` | ✅ | ✅ |
-| `unit` | ✅ | ✅ |
-| `showGrid` | ✅ | ✅ |
-| `headerHeight` / `footerHeight` | ✅ | ✅ |
-| `canvasBackground` | ✅ | ✅ |
-| `pageSpacingX` / `pageSpacingY` | ✅ | ✅ |
-| `testData` | ❌ | ✅ |
-
-### 使用示例
-
-```vue
-<template>
-  <XPrintDesigner
-    :mode="mode"
-    :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'
-    ? '/api/templates/save'
-    : '/api/reports/save'
-
-  const res = await fetch(endpoint, {
-    method: 'POST',
-    headers: { 'Content-Type': 'application/json' },
-    body: JSON.stringify(payload)
-  })
-
-  if (!res.ok) throw new Error('保存失败')
-
-  // 新建时获取后端返回的 ID
-  const result = await res.json()
-  if (payload.isNew && result.id) {
-    console.log('新模板 ID:', result.id)
-  }
-}
-</script>
-```
-
-> 不传 `onSave` 时，设计器走内置默认保存逻辑（根据 CRUD 配置调远程接口或存 localStorage）。
-
----
-
-## 自动保存配置
-
-传入 `onSave` 后可同时开启自动保存。右下角会显示"最近保存: HH:MM:SS"。
-
-### Vue 组件
-
-自动保存通过 `config.autoSave` 配置（`XPrintDesigner` 无独立 props，统一走 `config`）：
-
-| 字段 | 类型 | 默认值 | 说明 |
-|------|------|--------|------|
-| `autoSave.enabled` | `boolean` | `false` | 是否开启 |
-| `autoSave.intervalMs` | `number` | `120000` | 间隔（毫秒），默认 2 分钟 |
-
-```vue
-<XPrintDesigner :config="{
-  testData: sampleData,
-  onSave: handleSave,
-  autoSave: { enabled: true, intervalMs: 120000 }
-}" />
-```
-
-### Web Component
-
-```javascript
-designer.setOnSave(handleSave)
-designer.setAutoSave(true, 120000)   // 每 2 分钟自动保存
-designer.setAutoSave(false)          // 关闭
-```
-
-> 自动保存仅在内容有变更时触发，连续未变更的周期内不会重复保存。
-
----
-
-## 打印与导出
-
-### Web Component API
-
-#### `print(options)`
-
-```typescript
-interface PrintOptions {
-  mode: 'browser' | 'silent'
-  options?: {
-    silent?: boolean            // 静默打印（跳过浏览器打印对话框）
-    printerName?: string        // 指定打印机名称
-    copies?: number             // 打印份数，默认 1
-    duplex?: boolean            // 双面打印
-    pageRanges?: string         // 页码范围，如 '1-3'
-  }
-}
-```
-
-```javascript
-// 浏览器打印
-await designer.print({ mode: 'browser' })
-
-// 静默打印到指定打印机
-await designer.print({
-  mode: 'silent',
-  options: {
-    printerName: 'HP-LaserJet',
-    copies: 2
-  }
-})
-```
-
-#### `export(options)`
-
-```typescript
-interface ExportOptions {
-  type: 'pdf' | 'image' | 'html'
-  filename?: string            // 输出文件名（不含扩展名）
-}
-```
-
-```javascript
-// 导出 PDF
-await designer.export({ type: 'pdf', filename: '订单-2024' })
-
-// 导出图片
-await designer.export({ type: 'image', filename: '订单-2024' })
-
-// 导出 HTML
-await designer.export({ type: 'html', filename: '订单-2024' })
-```
-
-### 快捷键
-
-| 快捷键 | 功能 |
-|--------|------|
-| `Ctrl+S` | 保存 |
-| `Ctrl+P` | 打印 |
-| `Ctrl+Shift+P` | 预览 |
-| `Ctrl+Shift+E` | 导出 PDF |
-
----
-
-## 模板数据结构
-
-当需要直接保存/加载完整模板时，使用以下数据结构。
-
-### 完整 JSON 结构
-
-```json
-{
-  "id": "tpl_001",
-  "name": "A4 订单模板",
-  "updatedAt": 1715251200000,
-  "permissions": {
-    "editable": true,
-    "deletable": true,
-    "copyable": true
-  },
-  "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` | ✅ 是 | 模板唯一 ID |
-| `name` | `string` | ✅ 是 | 模板名称 |
-| `updatedAt` | `number` | 否 | 更新时间戳（毫秒） |
-| `permissions` | `object` | 否 | `{ editable, deletable, copyable }` |
-| `data` | `object` | ✅ 是 | 模板设计数据 |
-| `ext` | `object` | 否 | 扩展数据（变量树等） |
-
-### `data` 字段
-
-| 字段 | 类型 | 必填 | 说明 |
-|-----|------|-----|------|
-| `pages` | `Page[]` | ✅ 是 | 页面列表，每页含 `elements` 数组 |
-| `canvasSize` | `{ width, height }` | ✅ 是 | 画布尺寸 px（默认 A4: 794×1123） |
-| `unit` | `'mm' \| 'px' \| 'pt' \| 'in' \| 'cm'` | 否 | 单位，默认 `'mm'` |
-| `watermark` | `WatermarkSettings` | 否 | 水印配置 |
-| `guides` | `Guide[]` | 否 | 辅助参考线 |
-| `zoom` | `number` | 否 | 缩放比例，默认 `1` |
-| `showGrid` | `boolean` | 否 | 显示网格 |
-| `headerHeight` | `number` | 否 | 页眉高度 px |
-| `footerHeight` | `number` | 否 | 页脚高度 px |
-| `pageSpacingX` | `number` | 否 | 水平页边距 px |
-| `pageSpacingY` | `number` | 否 | 垂直页边距 px |
-| `canvasBackground` | `string` | 否 | 画布背景色 |
-| `testData` | `object` | 否 | 测试数据（报告模式会保存，模板模式不保存） |
-
----
-
-## 支持的元素类型
-
-| 类型 | 标识 | 说明 |
-|------|------|------|
-| 文本 | `text` | 静态文本或变量内容 |
-| 长文本 | `longtext` | 多行自动扩展文本，支持彩色标记语法 `[color=#xxx]` |
-| 富文本 | `richtext` | HTML 富文本格式化内容 |
-| 图片 | `image` | 图片显示（URL / Base64 / 变量绑定） |
-| 表格 | `table` | 数据表格，支持自动分页、页脚汇总、自定义脚本 |
-| 自定义表格 | `customTable` | 自由合并单元格、单元格内嵌图片/字段、逐格自定义样式 |
-| 嵌套表格 | `nestedtable` | 分组嵌套数据展示（父级标签 + 子级行列表） |
-| 条形码 | `barcode` | 一维条形码（CODE128、EAN13、UPC 等） |
-| 二维码 | `qrcode` | 二维码（支持 L/M/Q/H 纠错级别） |
-| 图表 | `chart` | ECharts 图表（柱状图/折线图/饼图/环形图/面积图） |
-| 数据卡片 | `datacard` | 单个关键指标数据展示（含趋势箭头） |
-| 进度条 | `progress` | 百分比进度展示 |
-| 列表 | `list` | 编号列表数据展示（横向/纵向布局） |
-| 日期 | `date` | 日期时间显示（可绑定变量或显示当前时间） |
-| 页码 | `pageNumber` | 页码显示（支持多种格式） |
-| 签名/印章 | `signature` | 印章图片或二维码，支持透明度 |
-| 线条 | `line` | 直线（支持实线/虚线/点线） |
-| 矩形 | `rect` | 矩形（支持圆角） |
-| 圆形 | `circle` | 圆形 |
-| 组合 | `group` | 多个元素的组合容器，作为整体移动/缩放/复制/删除（见[组合与取消组合](#组合与取消组合)） |
-
----
-
-## 版本兼容性说明
-
-### 依赖版本矩阵
-
-| 组件包 | 要求版本 | 说明 |
-|--------|---------|------|
-| `vue` | `^3.5.0` | 核心框架 |
-| `pinia` | `^2.3.0` | 状态管理 |
-| `echarts` | `^6.0.0` | 图表库（按需引入） |
-| `lodash` | `^4.17.0` | 工具函数 |
-| `qrcode` | `^1.5.0` | 二维码生成 |
-| `jsbarcode` | `^3.12.0` | 条形码生成 |
-| `jspdf` | `4.2.x` | PDF 导出 |
-| `tailwindcss` | `^3.x` | CSS 框架（构建时依赖） |
-
-### 升级注意事项
-
-- **从 `0.2.x` 升级到 `0.3.x`**：`onSave` 回调签名变化，`payload.data` 中 `testData` 的保存规则改为由 `mode` 决定
-- **Vue 版本**：仅支持 Vue 3.5+，不支持 Vue 2.x
-- **Node 版本**：`vite build` 和 `vue-tsc` 需要 Node >= 18
-
----
-
-## 常见问题排查
-
-### 1. 设计器加载后空白 / 无渲染
-
-**原因：** 未引入样式文件或 `ready` 事件未触发。
-
-**排查步骤：**
-1. 确认已引入 `x-print-designer/style.css` 或 `dist/print-designer.css`
-2. Web Component 方式需在 `ready` 事件后调用 API
-3. 检查浏览器控制台是否有报错
-
-### 2. 变量绑定不生效，显示为空或变量名
-
-**原因：** 变量路径与数据字段不匹配。
-
-**排查步骤：**
-1. 确认 `sampleData` / `setTestData` 中包含对应字段
-2. 检查变量名大小写是否一致（`@customerName` vs `customername`）
-3. 嵌套路径使用点号分隔：`@user.name`
-4. 确认数据格式：表格需要数组，图表需要 `Array<{category, value}>`
-
-### 3. 表格数据显示为空
-
-**原因：** 表格 `variable` 未绑定或数据格式不匹配。
-
-**排查步骤：**
-1. 确认表格元素的 `variable` 属性绑定了变量名
-2. 确认数据中该变量值为数组格式
-3. 如果使用 `columnsVariable`，确保列定义数组字段存在且包含 `{field, header}`
-
-### 4. 打印/导出 PDF 时样式错乱
-
-**原因：** 打印管线依赖 iframe 渲染 + 计算样式内联，部分样式可能未正确捕获。
-
-**排查步骤：**
-1. 优先使用预览（`Ctrl+Shift+P`）确认渲染效果
-2. 确认 PDF 导出使用的是 `export({ type: 'pdf' })` 而非浏览器打印
-3. 检查控制台是否有 `Failed to load` 相关错误
-
-### 5. 自定义表格预览时样式丢失
-
-**原因：** 列宽未持久化或表格容器 `overflow: hidden` 约束未解锁。
-
-**排查步骤：**
-1. 确认已保存模板（列宽需持久化到 `customTableColWidths`）
-2. 升级到最新版本（v0.3.1+ 已修复预览模式下列宽持久化和容器高度问题）
-
-### 6. 图表在预览/导出时显示空白
-
-**原因：** ECharts 异步渲染未完成，预览管线已截取快照。
-
-**排查步骤：**
-1. 升级到最新版本（已修复 ChartElement 异步渲染注册问题）
-2. 确认 `chartDataVariable` 绑定的数据格式正确
-3. 在编辑模式下确认图表正常显示后再预览
-
-### 7. `onSave` 回调未触发
-
-**原因：** 未正确传入 `onSave` 属性。
-
-**排查步骤：**
-1. Vue 组件确认 `:on-save="handleSave"` 正确绑定
-2. Web Component 确认在 `ready` 事件后调用 `setOnSave`
-3. 检查 `handleSave` 函数是否存在且无语法错误
-4. 确认未同时传入自建的 CRUD 配置（`onSave` 会覆盖内置保存逻辑）
-
-### 8. 自动保存不生效
-
-**原因：** 自动保存需要 `onSave` 回调。
-
-**排查步骤：**
-1. 确认同时传入了 `onSave` 和 `config.autoSave = { enabled: true }`（Vue 组件）或调用了 `setAutoSave(true)`
-2. 自动保存仅在内容有变更时触发，未修改时不会保存
-3. 检查 `autoSave.intervalMs` / `setAutoSave` 的间隔是否设置过短（频繁保存可能被节流）
-
----
-
-## 技术栈
-
-| 技术 | 用途 |
-|------|------|
-| Vue 3 + TypeScript | 核心框架 |
-| Pinia | 状态管理 |
-| Tailwind CSS | 原子化 CSS |
-| ECharts 6 | 图表渲染 |
-| Monaco Editor | 代码/JSON 编辑器 |
-| jsPDF | PDF 生成 |
-| jsBarcode | 条形码生成 |
-| qrcode | 二维码生成 |
-| canvg | SVG → Canvas 转换 |
-| dom-to-image-more | DOM → 图片导出 |
-| jszip | ZIP 打包 |
-| vue-i18n | 国际化（中文/English） |
-| Vite | 构建工具 |
+# X-Print-Designer
+
+基于 Vue 3 + TypeScript 开发的打印设计器，支持可视化拖拽设计打印模板，集成 ECharts 图表组件。
+
+---
+
+## 目录
+
+- [前置依赖要求](#前置依赖要求)
+- [快速开始](#快速开始)
+  - [源码开发](#源码开发)
+  - [Vue 组件接入（XPrintDesigner）](#vue-组件接入xprintdesigner)
+  - [5 分钟接入（推荐）](#5-分钟接入推荐)
+  - [Web Component 接入](#web-component-接入)
+- [核心概念：模板模式 vs 报告模式](#核心概念模板模式-vs-报告模式)
+- [Vue 组件使用说明](#vue-组件使用说明)
+- [Web Component 使用说明](#web-component-使用说明)
+  - [完整 API 参考](#完整-api-参考)
+  - [场景化模板库](#场景化模板库)
+  - [数据驱动模板向导](#数据驱动模板向导)
+  - [组合与取消组合](#组合与取消组合)
+  - [远程 CRUD 配置](#远程-crud-配置)
+- [传入数据格式](#传入数据格式)
+- [元素数据绑定](#元素数据绑定)
+- [图片元素使用说明](#图片元素使用说明)
+- [保存回调 `onSave`](#保存回调-onsave)
+- [自动保存配置](#自动保存配置)
+- [打印与导出](#打印与导出)
+- [模板数据结构](#模板数据结构)
+- [支持的元素类型](#支持的元素类型)
+- [版本兼容性说明](#版本兼容性说明)
+- [常见问题排查](#常见问题排查)
+- [技术栈](#技术栈)
+
+---
+
+## 前置依赖要求
+
+| 依赖 | 最低版本 | 说明 |
+|------|---------|------|
+| **Node.js** | `>= 18` | 运行时环境 |
+| **pnpm** | `>= 8` | 推荐包管理器（项目使用 `pnpm-lock.yaml`） |
+| **Vue** | `^3.5` | 核心框架 |
+
+### 浏览器兼容性
+
+| 浏览器 | 最低版本 | 说明 |
+|--------|---------|------|
+| Chrome | >= 90 | 完全支持 |
+| Edge | >= 90 | 完全支持 |
+| Firefox | >= 90 | 完全支持 |
+| Safari | >= 15 | 完全支持 |
+
+> **说明：** 设计器基于现代浏览器 API（`ResizeObserver`、`CSS Grid`、`Shadow DOM`），不支持 IE 11 及以下版本。
+
+---
+
+## 快速开始
+
+### 源码开发
+
+```bash
+# 克隆仓库
+git clone https://github.com/0ldFive/Vue-Print-Designer.git
+cd x-print-designer
+
+# 安装依赖
+pnpm install
+
+# 启动开发服务器
+pnpm dev
+
+# 构建生产包
+pnpm build
+
+# 构建 Web Component 包
+pnpm build:wc
+```
+
+启动后浏览器访问 `http://localhost:5173` 即可看到设计器 Demo 页面（`index.html`）。
+
+### Vue 组件接入（XPrintDesigner）
+
+**适用于：** Vue 3 项目以一等公民组件方式接入。`XPrintDesigner` 是 Web Component 的 Vue 适配层：props 声明式传参、事件自动透传、ref 暴露常用方法，**无需手动管理 `ready` 时序**。
+
+#### 基础用法（简化版）
+
+使用新增的工具函数，**从 700 行减少到 30 行**：
+
+```vue
+<template>
+  <XPrintDesigner
+    :config="config"
+    @checklist="onChecklist"
+    @printed="onPrinted"
+  />
+</template>
+
+<script setup lang="ts">
+import { ref } from 'vue'
+import { XPrintDesigner, createRestfulAdapter, buildFieldDictionary } from 'x-print-designer'
+import 'x-print-designer/style.css'
+
+// ✅ 使用 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('保存成功')
+  }
+})
+
+// ✅ 使用字段字典工具函数（从 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" />
+  <!-- ① 引入脚本：全部样式（Tailwind 工具类 + 组件样式）已内联进 JS，
+       宿主无需使用 Tailwind，也无需手动引入 CSS；link 仅按需可选 -->
+  <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），以自定义标签方式嵌入。
+
+```html
+<!DOCTYPE html>
+<html lang="zh-CN">
+<head>
+  <meta charset="UTF-8" />
+  <script type="module" src="/dist/print-designer.es.js"></script>
+  <!-- 样式已内联，无需宿主引入 Tailwind；print-designer.css 可选 -->
+</head>
+<body>
+  <print-designer id="designer"></print-designer>
+
+  <script>
+    const designer = document.getElementById('designer')
+
+    designer.addEventListener('ready', () => {
+      designer.setMode('template')
+      designer.setTestData({
+        id: 1,
+        title: '报告标题',
+        items: [{ name: '产品A', price: 100 }]
+      })
+      designer.setOnSave((payload) => {
+        fetch('/api/templates/save', {
+          method: 'POST',
+          headers: { 'Content-Type': 'application/json' },
+          body: JSON.stringify(payload)
+        })
+      })
+    })
+  </script>
+</body>
+</html>
+```
+
+---
+
+## 核心概念：模板模式 vs 报告模式
+
+设计器支持两种工作模式，通过 `mode` 属性/方法进行切换。
+
+### 概念说明
+
+| 概念 | 说明 |
+|------|------|
+| **模板 (Template)** | 页面布局设计，包含元素位置、样式、画布大小等 |
+| **数据 (Data)** | 业务数据，如订单信息、报告内容、用户信息等 |
+| **模板 ID** | 模板的唯一标识，用于关联和加载模板 |
+| **数据 ID** | 业务数据的唯一标识，如订单 ID、报告 ID |
+
+### 模板模式（`template`）— 默认
+
+**设计理念：** 模板与数据分离，一个模板可绑定多个不同的数据。
+
+**适用场景：**
+- 订单打印（同一订单模板，打印不同订单）
+- 标签打印（同一标签模板，打印不同商品）
+- 快递单据（同一单据模板，打印不同收件人）
+
+**保存行为：** 保存时**只保存页面布局**（元素位置、样式、画布大小等），**不保存** `testData`。
+
+### 报告模式（`report`）
+
+**设计理念：** 数据与布局绑定，保存的是完整的报告快照。
+
+**适用场景：**
+- 检测报告（每次检测结果 + 固定格式的报告模板）
+- 数据报表（当前统计数据的可视化呈现）
+- 档案文件（包含具体数据的完整文档）
+
+**保存行为：** 保存时**同时保存页面布局 + testData**。
+
+### 两种模式对比
+
+| 特性 | `template` 模板模式 | `report` 报告模式 |
+|------|-------------------|------------------|
+| 保存布局 | ✅ | ✅ |
+| 保存 testData | ❌ | ✅ |
+| 数据与模板关系 | 分离，运行时注入 | 绑定，一起保存 |
+| 模板复用性 | 高，可用于多个数据 | 低，针对当前数据 |
+| 典型用途 | 订单打印、标签 | 检测报告、数据报表 |
+
+### 使用示例
+
+**模板模式（推荐用于可复用模板）：**
+
+```javascript
+// 1. 编辑模板时传入预览数据
+const sampleData = {
+  id: null,               // 无需数据 ID，仅用于预览
+  orderNo: 'PREVIEW-001',
+  customerName: '预览客户'
+}
+
+// 2. 保存模板（只保存布局，不含 testData）
+// payload.data 中不包含 testData
+
+// 3. 打印时动态注入真实数据
+designer.loadTemplate('tpl-order')
+designer.setVariables({
+  orderNo: 'ORD-2024-001',
+  customerName: '张三'
+})
+designer.print({ mode: 'browser', options: { silent: true } })
+```
+
+**报告模式（推荐用于完整报告）：**
+
+```javascript
+// 1. 编辑报告时传入完整数据
+const sampleData = {
+  id: 8,                  // 报告 ID
+  title: '2024年第一季度销售报告',
+  totalAmount: 50000,
+  items: [...]
+}
+
+// 2. 保存报告（布局 + 数据一起保存）
+// payload.data 中包含完整的 testData
+
+// 3. 加载后直接打印，无需再次注入数据
+designer.loadTemplate(8)
+designer.print({ mode: 'browser', options: { silent: true } })
+```
+
+### 切换模式
+
+```vue
+<!-- Vue 组件（XPrintDesigner） -->
+<XPrintDesigner mode="template" />  <!-- 模板模式（默认） -->
+<XPrintDesigner mode="report" />    <!-- 报告模式 -->
+```
+
+```javascript
+// Web Component
+designer.setMode('template')
+designer.setMode('report')
+```
+
+---
+
+## Vue 组件使用说明
+
+### 组件 Props
+
+`XPrintDesigner` 是 Web Component 的 Vue 适配层（从 `x-print-designer` 导出）。除下表 props 外，其余配置（数据、CRUD、品牌、主题等）统一通过 `config` 传入。
+
+| 属性 | 类型 | 默认值 | 说明 |
+|------|------|--------|------|
+| `config` | `DesignerInitConfig \| null` | `null` | 统一初始化配置（等价 `el.init(config)`），见[init 完整配置](#initconfig-完整配置字段) |
+| `mode` | `'template'` \| `'report'` | — | 工作模式，影响保存行为 |
+| `uiMode` | `'beginner'` \| `'expert'` | — | 界面模式（简洁/完整） |
+| `viewMode` | `'edit'` \| `'preview'` | — | 视图模式，`'preview'` 时只渲染打印内容 |
+| `headless` | `boolean` | `false` | 无头模式，隐藏顶部工具栏和侧边栏 |
+| `onSave` | `(payload) => void \| Promise<void>` | — | 保存回调，详见[保存回调](#保存回调-onsave)（映射 `setOnSave`） |
+| `theme` | `string` | — | 主题（映射 `setTheme`） |
+
+### Props 详细说明
+
+#### `config`
+
+**宿主接入的首选入口**：所有配置（数据、保存、CRUD、品牌、主题等）一次传入，等价于调用 `el.init(config)`。`ready` 前传入自动排队，`ready` 后自动应用。
+
+```vue
+<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: { /* ... */ } }
+}" />
+```
+
+#### `mode`
+
+工作模式，决定保存时是否附带 `testData`。
+
+```vue
+<XPrintDesigner mode="report" />
+```
+
+#### `viewMode`
+
+切换编辑/预览视图。设为 `'preview'` 时隐藏所有编辑器 UI，仅渲染打印页面。适用于嵌入第三方页面时只展示打印效果。
+
+```vue
+<XPrintDesigner view-mode="preview" />
+```
+
+#### `headless`
+
+无头模式，隐藏顶部工具栏和侧边属性面板。用于嵌入式场景仅保留画布区域。
+
+```vue
+<XPrintDesigner headless />
+```
+
+#### `onSave`
+
+保存回调函数。传入后设计器**不再执行内置保存逻辑**，完全由用户自行处理持久化。也可通过 `config.onSave` 传入，效果一致。
+
+```vue
+<XPrintDesigner :on-save="(payload) => mySaveApi(payload)" />
+```
+
+> 不传 `onSave` 时，设计器使用内置 CRUD 逻辑（根据配置调远程接口或存 localStorage）。
+
+#### 预览数据与自动保存
+
+- 预览数据：通过 `config.testData`（等价 Web Component 的 `setTestData`，详见 [传入数据格式](#传入数据格式)）。
+- 自动保存：通过 `config.autoSave = { enabled, intervalMs? }` 开启（详见 [自动保存配置](#自动保存配置)）。
+
+---
+
+## Web Component 使用说明
+
+### 加载方式
+
+```html
+<!-- ES Module 方式（推荐）：样式已全部内联进 JS，宿主无需 Tailwind / 手动引入 CSS -->
+<script type="module" src="/dist/print-designer.es.js"></script>
+
+<!-- 或 UMD 方式 -->
+<script src="/dist/print-designer.umd.js"></script>
+```
+
+```html
+<print-designer id="designer"></print-designer>
+```
+
+### 完整 API 参考
+
+所有方法均通过 DOM 元素直接调用。**必须在 `ready` 事件触发后调用。**
+
+| 方法 | 参数 | 返回值 | 说明 |
+|------|------|--------|------|
+| `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>` | `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 字符串 |
+| `print(options?)` | `PrintOptions` | `Promise<void>` | 执行打印，详见[打印与导出](#打印与导出) |
+| `export(options?)` | `ExportOptions` | `Promise<void>` | 导出 PDF / 图片 / HTML，详见[打印与导出](#打印与导出) |
+| `setPreviewMode(options)` | `PreviewModeOptions` | `void` | 进入独立预览面板模式。传入的 `pages` 若含循环页（`loopDataVariable`），预览时会自动按数据展开成 N 页 |
+| `exitPreviewMode()` | — | `void` | 退出预览模式，返回编辑器 |
+| `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` 的单个模板页。保存流程已自动折叠，通常无需手动调用 |
+
+### 事件参考
+
+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` 更可靠。
+
+### 基本使用示例
+
+```javascript
+const designer = document.getElementById('designer')
+
+designer.addEventListener('ready', () => {
+  // 设置模式
+  designer.setMode('template')
+
+  // 设置数据
+  designer.setTestData({
+    id: 1,
+    orderNo: 'ORD-001',
+    customerName: '张三',
+    items: [
+      { name: '产品A', price: 100, quantity: 2 },
+      { name: '产品B', price: 200, quantity: 3 }
+    ]
+  })
+
+  // 保存回调
+  designer.setOnSave(async (payload) => {
+    console.log('保存:', payload)
+    await fetch('/api/templates/save', {
+      method: 'POST',
+      headers: { 'Content-Type': 'application/json' },
+      body: JSON.stringify(payload)
+    })
+  })
+
+  // 开启自动保存（每 2 分钟）
+  designer.setAutoSave(true, 120000)
+})
+```
+
+### 打印时注入真实数据
+
+使用 `setVariables` 在打印/导出时覆盖预览数据中的字段：
+
+```javascript
+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 } })
+```
+
+### 独立预览面板
+
+当设计器嵌入第三方页面时，可切换到独立的**纯预览模式**——只渲染打印内容，不显示编辑器 UI。
+
+**适用于：** 插件/第三方页面嵌入时的打印预览、用户填写表单后的预览、无需编辑功能的只读场景。
+
+#### `setPreviewMode(options)`
+
+```typescript
+interface PreviewModeOptions {
+  pages: Page[]                              // 页面元素布局（必填）
+  canvasSize: { width: number; height: number } // 画布尺寸（必填）
+  canvasBackground?: string                  // 画布背景色，默认 '#ffffff'
+  testData?: Record<string, any>            // 测试数据
+  variables?: Record<string, any>           // 额外变量映射
+  watermark?: WatermarkSettings             // 水印配置
+}
+```
+
+#### 使用示例
+
+```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()` 会自动恢复进入预览前的编辑器状态（模板选择、编辑进度等）。
+
+---
+
+## 场景化模板库
+
+为降低业务人员上手门槛，模板下拉与空态页按**业务场景**分组展示内置示例模板，并支持搜索过滤。内置场景围绕无人机业务：
+
+| 场景 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 样式类。
+
+> 注：Web Component 构建已把全部样式（Tailwind 工具类 + 组件 scoped 样式）内联进 JS 并注入 shadow root，宿主不使用 Tailwind 时编辑面板与弹层同样完整渲染；自动注入仅作为兼容宿主样式的补充。
+
+**解决：** 插件自动检测并注入，**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 回调，保存功能将不可用
+```
+
+---
+
+## 传入数据格式
+
+### 基本要求
+
+`config.testData` / `setTestData(data)` 接收一个普通的 JSON 对象。**唯一必填字段是 `id`**。
+
+| 字段 | 类型 | 必填 | 说明 |
+|------|------|------|------|
+| `id` | `number` \| `string` | ✅ 是 | 业务数据的唯一标识，如报告 ID、订单 ID |
+| `templateId` | `string` | 否 | 绑定的模板 ID，不传则用当前已选模板 |
+| `name` | `string` | 否 | 数据名称 |
+| `variables` | `object` | 否 | 业务变量对象（推荐，用于组织数据） |
+| 任意自定义字段 | `any` | 否 | 也可直接在根级别存放变量 |
+
+### 两种组织方式（任选其一，自动兼容）
+
+#### 方式一：带 `variables` 包装（推荐）
+
+```json
+{
+  "id": 8,
+  "name": "测试报告",
+  "templateId": "tpl_report",
+  "variables": {
+    "title": "报告标题",
+    "customerName": "张三",
+    "items": [
+      { "name": "产品A", "price": 100, "quantity": 2 }
+    ],
+    "chartData": [
+      { "category": "一月", "value": 1200 }
+    ]
+  }
+}
+```
+
+模板绑定：`@title`、`@customerName`、`@items`、`@chartData`
+
+#### 方式二：扁平数据
+
+```json
+{
+  "id": 8,
+  "name": "测试报告",
+  "title": "报告标题",
+  "customerName": "张三",
+  "items": [
+    { "name": "产品A", "price": 100, "quantity": 2 }
+  ],
+  "chartData": [
+    { "category": "一月", "value": 1200 }
+  ]
+}
+```
+
+模板绑定：`@title`、`@customerName`、`@items`、`@chartData`
+
+> 两种方式等效。设计器内部优先在 `variables` 中查找，未找到则在根级别查找。
+
+### 支持的数据类型
+
+| 类型 | 示例 | 模板绑定 |
+|------|------|---------|
+| 字符串 | `"张三"` | `@customerName` |
+| 数字 | `100` | `@totalAmount` |
+| 布尔值 | `true` | `@isPaid` |
+| 数组 | `[{...}, {...}]` | `@items` |
+| 嵌套对象 | `{ user: { name: "李四" } }` | `@user.name` |
+
+### 表格数据
+
+表格元素需要三个维度的变量绑定：
+
+| 绑定属性 | 变量名示例 | 数据格式 | 说明 |
+|---------|-----------|---------|------|
+| `variable` | `@items` | `Array<Object>` | 表格行数据 |
+| `columnsVariable` | `@tableCols` | `Array<{field, header, width}>` | 列定义 |
+| `footerDataVariable` | `@tableFooter` | `Array<Object>` | 页脚汇总行 |
+
+```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" } }
+  ]
+}
+```
+
+### 图表数据
+
+```json
+{
+  "chartData": [
+    { "category": "一月", "value": 1200 },
+    { "category": "二月", "value": 1500 }
+  ]
+}
+```
+
+图表元素需在属性面板中配置：
+- **chartDataVariable**：`@chartData`
+- **chartXField**：`category`（X 轴字段名）
+- **chartYField**：`value`（Y 轴字段名）
+- **chartNameField**：`category`（饼图名称字段）
+
+### 完整示例数据
+
+```json
+{
+  "id": 8,
+  "name": "宝安机场飞行任务记录",
+  "templateId": "tpl_report_drone",
+  "createTime": "2026-05-01",
+  "variables": {
+    "dockname": "宝安国际无人机机场",
+    "dronesn": "6EE5NC104E0PY6",
+    "dronename": "M300 RTK",
+    "reportname": "宝安机场飞行任务记录报告",
+    "tasktype": "航线巡检",
+    "totalcount": 4,
+    "totaldistance": "48.6 km",
+    "conclusion": "本轮飞行任务覆盖宝安区重点航线，数据采集完整。",
+    "flightRecords": [
+      {
+        "time": "2026-04-02 09:30",
+        "taskname": "宝安港区A线巡检",
+        "dockname": "宝安国际无人机机场",
+        "distance": "12.5 km",
+        "image": "https://picsum.photos/id/1/200/80"
+      }
+    ],
+    "chartData": [
+      { "category": "一月", "value": 1200 },
+      { "category": "二月", "value": 1500 }
+    ]
+  }
+}
+```
+
+### 注意事项
+
+1. **`id` 字段**
+   - 业务数据的唯一标识，在保存回调中用于识别当前编辑的数据
+   - 不传则保存时 `payload.id` 为 `null`
+
+2. **`id` 与 `templateId` 的区别**
+   - `id`：业务数据的标识（报告中用作报告 ID）
+   - `templateId`：打印模板的标识，两者是完全不同的概念
+
+3. **变量命名**
+   - 使用 camelCase 命名，如 `customerName` 而非 `c`
+   - 避免特殊字符和空格
+   - 嵌套路径使用点号：`@user.profile.name`
+
+4. **数组数据**
+   - 表格和图表需要数组类型
+   - 数组元素应包含一致的字段结构：`items: [{name: "A", price: 100}, {name: "B", price: 200}]`
+
+5. **动态更新**
+   - Web Component 通过 `setSampleData()` / `setTestData()` 更新
+   - 数据更新后，画布中的变量绑定会自动重新解析
+
+---
+
+## 元素数据绑定
+
+### 变量语法
+
+| 语法 | 示例 | 说明 |
+|-----|------|------|
+| `@变量名` | `@customerName` | 直接引用变量 |
+| `{#变量路径}` | `{#order.items[0].name}` | 支持嵌套路径和数组索引 |
+
+### 各元素可绑定字段
+
+| 元素 | 绑定属性 | 示例 |
+|------|---------|------|
+| 文本 / 长文本 | `content` | `订单号: {#orderNo}` |
+| 图片 | `variable` | `@imageUrl` |
+| 表格 | `variable` + `columnsVariable` + `footerDataVariable` | `@items`, `@tableCols`, `@tableFooter` |
+| 自定义表格 | `customTableCells[].field` | `@customerName`（单元格字段） |
+| 条形码 | `variable` 或 `content` | `@barcode` |
+| 二维码 | `variable` 或 `content` | `@url` |
+| 图表 | `chartDataVariable` + `chartXField` + `chartYField` | `@chartData`, `category`, `value` |
+| 数据卡片 | `variable` | `@totalAmount` |
+| 进度条 | `variable` | `@progress` |
+| 日期 | `variable` | `@createTime` |
+
+---
+
+## 图片元素使用说明
+
+### 方式 1：直接输入图片 URL
+
+在属性面板的"图片地址"输入框填写 URL（支持 HTTP/HTTPS）。
+
+```
+https://example.com/logo.png
+```
+
+### 方式 2：本地上传（自动转 Base64）
+
+点击属性面板中的 **"上传图片"** 按钮或**双击画布上的图片元素**，从本地选择图片文件：
+- 自动转为 Base64 并填入图片地址
+- 限制最大 **2MB**
+- 支持 PNG、JPG、GIF、WebP 等格式
+
+### 方式 3：绑定变量
+
+将 `variable` 绑定到变量名，图片地址从数据中动态读取。
+
+| 绑定方式 | 示例 | 数据值要求 |
+|---------|------|-----------|
+| 静态变量 | `@logoUrl` | 字符串 URL 或 Base64 |
+| 数组元素 | `@flightRecords[0].image` | 该字段值为 URL 或 Base64 |
+
+**对应数据：**
+
+```json
+{
+  "variables": {
+    "logoUrl": "https://example.com/logo.png",
+    "avatarBase64": "data:image/png;base64,iVBORw0KGgo...",
+    "flightRecords": [
+      { "image": "https://picsum.photos/id/1/200/80" }
+    ]
+  }
+}
+```
+
+### 方式对比
+
+| 方式 | 适用场景 | 存储内容 |
+|------|---------|---------|
+| URL 输入 | 固定图片、CDN 资源 | URL 字符串 |
+| 本地上传 | 无公网链接的图片 | Base64 编码 |
+| 变量绑定 | 每条数据图片不同 | URL 或 Base64 |
+
+---
+
+## 保存回调 `onSave`
+
+传入 `onSave` 后，用户保存（`Ctrl+S` 或工具栏保存按钮）时设计器不再自动持久化，而是将组装好的数据通过回调交给用户自行处理。
+
+### 回调参数
+
+```typescript
+interface SavePayload {
+  id: string | null      // 模板 ID，null 表示新建
+  name: string           // 模板名称
+  data: Record<string, any>  // 模板数据（含 pages、canvasSize、watermark 等）
+  isNew: boolean         // 是否新建模板
+}
+```
+
+### 不同模式下 data 内容差异
+
+| 字段 | 模板模式 | 报告模式 |
+|------|---------|---------|
+| `pages` | ✅ | ✅ |
+| `canvasSize` | ✅ | ✅ |
+| `watermark` | ✅ | ✅ |
+| `guides` | ✅ | ✅ |
+| `unit` | ✅ | ✅ |
+| `showGrid` | ✅ | ✅ |
+| `headerHeight` / `footerHeight` | ✅ | ✅ |
+| `canvasBackground` | ✅ | ✅ |
+| `pageSpacingX` / `pageSpacingY` | ✅ | ✅ |
+| `testData` | ❌ | ✅ |
+
+### 使用示例
+
+```vue
+<template>
+  <XPrintDesigner
+    :mode="mode"
+    :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'
+    ? '/api/templates/save'
+    : '/api/reports/save'
+
+  const res = await fetch(endpoint, {
+    method: 'POST',
+    headers: { 'Content-Type': 'application/json' },
+    body: JSON.stringify(payload)
+  })
+
+  if (!res.ok) throw new Error('保存失败')
+
+  // 新建时获取后端返回的 ID
+  const result = await res.json()
+  if (payload.isNew && result.id) {
+    console.log('新模板 ID:', result.id)
+  }
+}
+</script>
+```
+
+> 不传 `onSave` 时，设计器走内置默认保存逻辑（根据 CRUD 配置调远程接口或存 localStorage）。
+
+---
+
+## 自动保存配置
+
+传入 `onSave` 后可同时开启自动保存。右下角会显示"最近保存: HH:MM:SS"。
+
+### Vue 组件
+
+自动保存通过 `config.autoSave` 配置（`XPrintDesigner` 无独立 props，统一走 `config`）：
+
+| 字段 | 类型 | 默认值 | 说明 |
+|------|------|--------|------|
+| `autoSave.enabled` | `boolean` | `false` | 是否开启 |
+| `autoSave.intervalMs` | `number` | `120000` | 间隔（毫秒），默认 2 分钟 |
+
+```vue
+<XPrintDesigner :config="{
+  testData: sampleData,
+  onSave: handleSave,
+  autoSave: { enabled: true, intervalMs: 120000 }
+}" />
+```
+
+### Web Component
+
+```javascript
+designer.setOnSave(handleSave)
+designer.setAutoSave(true, 120000)   // 每 2 分钟自动保存
+designer.setAutoSave(false)          // 关闭
+```
+
+> 自动保存仅在内容有变更时触发，连续未变更的周期内不会重复保存。
+
+---
+
+## 打印与导出
+
+### Web Component API
+
+#### `print(options)`
+
+```typescript
+interface PrintOptions {
+  mode: 'browser' | 'silent'
+  options?: {
+    silent?: boolean            // 静默打印（跳过浏览器打印对话框）
+    printerName?: string        // 指定打印机名称
+    copies?: number             // 打印份数，默认 1
+    duplex?: boolean            // 双面打印
+    pageRanges?: string         // 页码范围，如 '1-3'
+  }
+}
+```
+
+```javascript
+// 浏览器打印
+await designer.print({ mode: 'browser' })
+
+// 静默打印到指定打印机
+await designer.print({
+  mode: 'silent',
+  options: {
+    printerName: 'HP-LaserJet',
+    copies: 2
+  }
+})
+```
+
+#### `export(options)`
+
+```typescript
+interface ExportOptions {
+  type: 'pdf' | 'image' | 'html'
+  filename?: string            // 输出文件名（不含扩展名）
+}
+```
+
+```javascript
+// 导出 PDF
+await designer.export({ type: 'pdf', filename: '订单-2024' })
+
+// 导出图片
+await designer.export({ type: 'image', filename: '订单-2024' })
+
+// 导出 HTML
+await designer.export({ type: 'html', filename: '订单-2024' })
+```
+
+### 快捷键
+
+| 快捷键 | 功能 |
+|--------|------|
+| `Ctrl+S` | 保存 |
+| `Ctrl+P` | 打印 |
+| `Ctrl+Shift+P` | 预览 |
+| `Ctrl+Shift+E` | 导出 PDF |
+
+---
+
+## 模板数据结构
+
+当需要直接保存/加载完整模板时，使用以下数据结构。
+
+### 完整 JSON 结构
+
+```json
+{
+  "id": "tpl_001",
+  "name": "A4 订单模板",
+  "updatedAt": 1715251200000,
+  "permissions": {
+    "editable": true,
+    "deletable": true,
+    "copyable": true
+  },
+  "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` | ✅ 是 | 模板唯一 ID |
+| `name` | `string` | ✅ 是 | 模板名称 |
+| `updatedAt` | `number` | 否 | 更新时间戳（毫秒） |
+| `permissions` | `object` | 否 | `{ editable, deletable, copyable }` |
+| `data` | `object` | ✅ 是 | 模板设计数据 |
+| `ext` | `object` | 否 | 扩展数据（变量树等） |
+
+### `data` 字段
+
+| 字段 | 类型 | 必填 | 说明 |
+|-----|------|-----|------|
+| `pages` | `Page[]` | ✅ 是 | 页面列表，每页含 `elements` 数组 |
+| `canvasSize` | `{ width, height }` | ✅ 是 | 画布尺寸 px（默认 A4: 794×1123） |
+| `unit` | `'mm' \| 'px' \| 'pt' \| 'in' \| 'cm'` | 否 | 单位，默认 `'mm'` |
+| `watermark` | `WatermarkSettings` | 否 | 水印配置 |
+| `guides` | `Guide[]` | 否 | 辅助参考线 |
+| `zoom` | `number` | 否 | 缩放比例，默认 `1` |
+| `showGrid` | `boolean` | 否 | 显示网格 |
+| `headerHeight` | `number` | 否 | 页眉高度 px |
+| `footerHeight` | `number` | 否 | 页脚高度 px |
+| `pageSpacingX` | `number` | 否 | 水平页边距 px |
+| `pageSpacingY` | `number` | 否 | 垂直页边距 px |
+| `canvasBackground` | `string` | 否 | 画布背景色 |
+| `testData` | `object` | 否 | 测试数据（报告模式会保存，模板模式不保存） |
+
+---
+
+## 支持的元素类型
+
+| 类型 | 标识 | 说明 |
+|------|------|------|
+| 文本 | `text` | 静态文本或变量内容 |
+| 长文本 | `longtext` | 多行自动扩展文本，支持彩色标记语法 `[color=#xxx]` |
+| 富文本 | `richtext` | HTML 富文本格式化内容 |
+| 图片 | `image` | 图片显示（URL / Base64 / 变量绑定） |
+| 表格 | `table` | 数据表格，支持自动分页、页脚汇总、自定义脚本 |
+| 自定义表格 | `customTable` | 自由合并单元格、单元格内嵌图片/字段、逐格自定义样式 |
+| 嵌套表格 | `nestedtable` | 分组嵌套数据展示（父级标签 + 子级行列表） |
+| 条形码 | `barcode` | 一维条形码（CODE128、EAN13、UPC 等） |
+| 二维码 | `qrcode` | 二维码（支持 L/M/Q/H 纠错级别） |
+| 图表 | `chart` | ECharts 图表（柱状图/折线图/饼图/环形图/面积图） |
+| 数据卡片 | `datacard` | 单个关键指标数据展示（含趋势箭头） |
+| 进度条 | `progress` | 百分比进度展示 |
+| 列表 | `list` | 编号列表数据展示（横向/纵向布局） |
+| 日期 | `date` | 日期时间显示（可绑定变量或显示当前时间） |
+| 页码 | `pageNumber` | 页码显示（支持多种格式） |
+| 签名/印章 | `signature` | 印章图片或二维码，支持透明度 |
+| 线条 | `line` | 直线（支持实线/虚线/点线） |
+| 矩形 | `rect` | 矩形（支持圆角） |
+| 圆形 | `circle` | 圆形 |
+| 组合 | `group` | 多个元素的组合容器，作为整体移动/缩放/复制/删除（见[组合与取消组合](#组合与取消组合)） |
+
+---
+
+## 版本兼容性说明
+
+### 依赖版本矩阵
+
+| 组件包 | 要求版本 | 说明 |
+|--------|---------|------|
+| `vue` | `^3.5.0` | 核心框架 |
+| `pinia` | `^2.3.0` | 状态管理 |
+| `echarts` | `^6.0.0` | 图表库（按需引入） |
+| `lodash` | `^4.17.0` | 工具函数 |
+| `qrcode` | `^1.5.0` | 二维码生成 |
+| `jsbarcode` | `^3.12.0` | 条形码生成 |
+| `jspdf` | `4.2.x` | PDF 导出 |
+| `tailwindcss` | `^3.x` | CSS 框架（构建时依赖） |
+
+### 升级注意事项
+
+- **从 `0.2.x` 升级到 `0.3.x`**：`onSave` 回调签名变化，`payload.data` 中 `testData` 的保存规则改为由 `mode` 决定
+- **Vue 版本**：仅支持 Vue 3.5+，不支持 Vue 2.x
+- **Node 版本**：`vite build` 和 `vue-tsc` 需要 Node >= 18
+
+---
+
+## 常见问题排查
+
+### 1. 设计器加载后空白 / 无渲染
+
+**原因：** `ready` 事件未触发，或 Vue 集成方式未引入样式文件。
+
+**排查步骤：**
+1. Web Component 方式：样式已全部内联进 JS（含 Tailwind 工具类与组件样式），无需宿主引入任何 CSS；仍空白请检查控制台报错
+2. Vue 集成方式（`x-print-designer/vue`）：确认已引入 `x-print-designer/style.css`
+2. Web Component 方式需在 `ready` 事件后调用 API
+3. 检查浏览器控制台是否有报错
+
+### 2. 变量绑定不生效，显示为空或变量名
+
+**原因：** 变量路径与数据字段不匹配。
+
+**排查步骤：**
+1. 确认 `sampleData` / `setTestData` 中包含对应字段
+2. 检查变量名大小写是否一致（`@customerName` vs `customername`）
+3. 嵌套路径使用点号分隔：`@user.name`
+4. 确认数据格式：表格需要数组，图表需要 `Array<{category, value}>`
+
+### 3. 表格数据显示为空
+
+**原因：** 表格 `variable` 未绑定或数据格式不匹配。
+
+**排查步骤：**
+1. 确认表格元素的 `variable` 属性绑定了变量名
+2. 确认数据中该变量值为数组格式
+3. 如果使用 `columnsVariable`，确保列定义数组字段存在且包含 `{field, header}`
+
+### 4. 打印/导出 PDF 时样式错乱
+
+**原因：** 打印管线依赖 iframe 渲染 + 计算样式内联，部分样式可能未正确捕获。
+
+**排查步骤：**
+1. 优先使用预览（`Ctrl+Shift+P`）确认渲染效果
+2. 确认 PDF 导出使用的是 `export({ type: 'pdf' })` 而非浏览器打印
+3. 检查控制台是否有 `Failed to load` 相关错误
+
+### 5. 自定义表格预览时样式丢失
+
+**原因：** 列宽未持久化或表格容器 `overflow: hidden` 约束未解锁。
+
+**排查步骤：**
+1. 确认已保存模板（列宽需持久化到 `customTableColWidths`）
+2. 升级到最新版本（v0.3.1+ 已修复预览模式下列宽持久化和容器高度问题）
+
+### 6. 图表在预览/导出时显示空白
+
+**原因：** ECharts 异步渲染未完成，预览管线已截取快照。
+
+**排查步骤：**
+1. 升级到最新版本（已修复 ChartElement 异步渲染注册问题）
+2. 确认 `chartDataVariable` 绑定的数据格式正确
+3. 在编辑模式下确认图表正常显示后再预览
+
+### 7. `onSave` 回调未触发
+
+**原因：** 未正确传入 `onSave` 属性。
+
+**排查步骤：**
+1. Vue 组件确认 `:on-save="handleSave"` 正确绑定
+2. Web Component 确认在 `ready` 事件后调用 `setOnSave`
+3. 检查 `handleSave` 函数是否存在且无语法错误
+4. 确认未同时传入自建的 CRUD 配置（`onSave` 会覆盖内置保存逻辑）
+
+### 8. 自动保存不生效
+
+**原因：** 自动保存需要 `onSave` 回调。
+
+**排查步骤：**
+1. 确认同时传入了 `onSave` 和 `config.autoSave = { enabled: true }`（Vue 组件）或调用了 `setAutoSave(true)`
+2. 自动保存仅在内容有变更时触发，未修改时不会保存
+3. 检查 `autoSave.intervalMs` / `setAutoSave` 的间隔是否设置过短（频繁保存可能被节流）
+
+---
+
+## 技术栈
+
+| 技术 | 用途 |
+|------|------|
+| Vue 3 + TypeScript | 核心框架 |
+| Pinia | 状态管理 |
+| Tailwind CSS | 原子化 CSS |
+| ECharts 6 | 图表渲染 |
+| Monaco Editor | 代码/JSON 编辑器 |
+| jsPDF | PDF 生成 |
+| jsBarcode | 条形码生成 |
+| qrcode | 二维码生成 |
+| canvg | SVG → Canvas 转换 |
+| dom-to-image-more | DOM → 图片导出 |
+| jszip | ZIP 打包 |
+| vue-i18n | 国际化（中文/English） |
+| Vite | 构建工具 |