x-print-designer 0.4.28 → 0.4.42

package/README.md

@@ -83,6 +83,80 @@ pnpm build:wc
 
 **适用于：** 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
@@ -788,6 +862,324 @@ el.setCrudMode('remote') // 保存/删除/加载走远程 API；local 为默认
 
 ---
 
+## 工具函数（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 回调，保存功能将不可用
+```
+
+---
+
 ## 传入数据格式
 
 ### 基本要求

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

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

package/dist/{JsBarcode-DnTB2TYK.js → JsBarcode-DJOhOA0M.js}

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

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

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

package/dist/{browser-CGxtUZAc.js → browser-Dzsc4Gy5.js}

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

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

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