vg-print 1.1.408 → 1.1.504

package/README.md

@@ -124,10 +124,10 @@ setSocketIo(io)
 
 也可直接使用 `window.io = io`（等价）。
 
-### 可选依赖：数据源（axios）
+### 可选依赖：请求型数据源（axios）
 
 - 本库默认不内置 `axios`，以减少默认安装体积。
-- 仅当你需要“数据源管理/接口取数/字段联动”能力时，才需要安装并注入：
+- 仅当你需要通过数据源配置发起接口请求、测试链接或执行数据处理时，才需要安装并注入：
 
 ```bash
 npm i axios
@@ -142,7 +142,7 @@ import { setHttpClient } from 'vg-print'
 setHttpClient(axios)
 ```
 
-未安装/未注入时，“数据源”入口会自动禁用；即使误触发也不会导致项目报错。
+如果只使用 `data-sources` 外部传入数据，不需要安装 axios；未传外部数据源且未注入 axios 时，请求型“数据源”入口会自动提示依赖缺失，不会影响设计器其他功能。
 
 ### 可选插件：条码/二维码（@vg-print/plugin-bwip-js）
 
@@ -197,7 +197,7 @@ hiprint.register({
 - `save` 保存（拆分按钮的主键）
 - `edit-template` 打开“编辑模板数据”对话框
 - `edit-data` 打开“编辑打印数据”对话框
-- `lang-change` 语言切换（值为语言码：`cn`、`en`、`de`、`es`、`fr`、`it`、`ja`、`ru`、`cn_tw`）
+- `lang-change` 语言切换（值为语言码：`cn`、`en`、`cn_tw`）
 - `feedback` 反馈/帮助
 
 ### 插槽（Slots）
@@ -331,7 +331,7 @@ const onSaveDirect = () => designer.value?.save()
 - `showPrinterSelect: boolean` 是否显示“打印机选择”下拉区域，默认 `true`
 - `modalShow: boolean` 弹窗显隐（支持 `v-model:modalShow`）
 - `width: string | number` 弹窗宽度（默认 `'80%'`）
-- `defaultLang: string` 组件内 i18n 语言（Standalone 时使用）；支持 `cn`、`en`、`de`、`es`、`fr`、`it`、`ja`、`ru`、`cn_tw`；默认 `cn`
+- `defaultLang: string` 组件内 i18n 语言（Standalone 时使用）；支持 `cn`、`en`、`cn_tw`；默认 `cn`
 
 预览头部标题使用
 
@@ -363,40 +363,6 @@ const onSaveDirect = () => designer.value?.save()
 - 但只有“异常/进度”场景才会带 message 或 payload
 - 普通状态（如 show:start 、 render:done 、 image:done ）没有额外信息，所以就是 undefined
 
-```ts
-type PreviewShowOptions = {
-  width?: string | number
-  dialogTitle?: string
-  dialogTitleHtml?: string
-  showPdf?: boolean
-  showImg?: boolean
-  showPrint2?: boolean
-  showPrinterSelect?: boolean
-  showTitle?: boolean
-  pdfOptions?: object
-  imageOptions?: object
-  directPrintOptions?: object
-  browserPrintOptions?: object
-  onClick?: (type: 'pdf' | 'img' | 'print' | 'print2' | 'close') => void
-  onClose?: () => void
-  onRender?: () => void
-  callBackOptions?: {
-    statusCallback?: (status: {
-      type:
-        | 'show:start' | 'show:ready'
-        | 'render:start' | 'render:done' | 'render:error'
-        | 'pdf:start' | 'pdf:progress' | 'pdf:done' | 'pdf:error'
-        | 'image:start' | 'image:progress' | 'image:done' | 'image:error'
-        | 'print:start' | 'print:done' | 'print:error'
-        | 'directPrint:start' | 'directPrint:progress' | 'directPrint:done' | 'directPrint:error'
-        | 'close'
-      message?: string
-      payload?: any
-    }) => void
-  }
-}
-```
-
 ### 使用示例（单独使用）
 
 ```vue
@@ -549,60 +515,6 @@ import 'vg-print/style.css'
 
 环境要求：Vue 3、Node >= 18.18。无需单独安装 `vue-plugin-hiprint`，本库已内置并导出 `hiprint` 能力。
 
-## 快速开始
-
-```js
-// main.ts
-import { createApp } from 'vue'
-import App from './App.vue'
-import vgPrint from 'vg-print'
-import 'vg-print/style.css'
-
-createApp(App).use(vgPrint).mount('#app')
-```
-
-```vue
-<template>
-  <FullDesigner
-    ref="designer"
-    :hi-host="'http://127.0.0.1:17521'"
-    :hi-token="'your-token'"
-    :hi-auto-connect="true"
-  />
-
-  <el-button @click="preview">预览</el-button>
-  <el-button @click="printBrowser">浏览器打印</el-button>
-  <el-button @click="exportPdf">导出 PDF</el-button>
-  <el-button @click="exportImage">导出图片</el-button>
-  <el-button @click="directPrint">直接打印（需客户端）</el-button>
-</template>
-
-<script setup>
-import { ref } from 'vue'
-const designer = ref(null)
-
-// 预览
-const preview = () => designer.value.preView()
-// 浏览器打印
-const printBrowser = () => designer.value.printView()
-// 导出 PDF
-const exportPdf = () => designer.value.toPdf()
-// 导出图片
-const exportImage = () => designer.value.toImage()
-// 直接打印（需客户端已连接）
-const directPrint = () => designer.value.print()
-
-// 连接控制与参数设置
-const setHostToken = () => designer.value.setHiwebSocket('http://127.0.0.1:17521', 'token')
-// 主动连接客户端
-const connect = () => designer.value.connect()
-// 断开客户端
-const disconnect = () => designer.value.disconnect()
-// 关闭自动连接策略
-const disableAutoConnect = () => designer.value.disAutoConnect()
-</script>
-```
-
 ## API（FullDesigner）
 
 ### 属性（Props，含描述）
@@ -610,9 +522,10 @@ const disableAutoConnect = () => designer.value.disAutoConnect()
 - `hi-host: string` 客户端服务地址；示例 `http://127.0.0.1:17521`，用于直连打印
 - `hi-token: string` 客户端鉴权令牌；与客户端配置一致时方可直连打印
 - `hi-auto-connect: boolean` 是否自动连接客户端；默认 `true`，为 `false` 时需手动调用 `connect()`
-- `initial-template: object` 初始化模板 JSON；为空时使用内置示例模板
+- `initial-template: object` 初始化模板 JSON；组件会先完成设计器页面的首次渲染，再将模板数据加载进去；为空时使用内置示例模板
 - `initial-print-data: object | array` 初始化打印数据；支持对象或数组，运行时变更会即时生效
-- `default-lang: string` 默认语言；支持 `cn`、`en`、`de`、`es`、`fr`、`it`、`ja`、`ru`、`cn_tw`；默认 `cn`
+- `data-sources: Array | object` 外部传入的数据源字段元数据；支持直接传入字段列表、表结构字段列表或带 `dataSets`/`fields` 的完整结构，用于设计器字段选择器；不传时继续使用数据源配置中的请求方式
+- `default-lang: string` 默认语言；支持 `cn`、`en`、`cn_tw`；默认 `cn`
 - `config: object` 设计器引擎配置；会在初始化前注入到 `hiprint.setConfig(config)`（同时写入 `window.HIPRINT_CONFIG`）。常用字段：
   - `showAdsorbLine: boolean` 是否显示吸附参考线（拖动/缩放时的对齐辅助线）
   - `showPosition: boolean` 是否显示元素坐标提示（移动元素时显示位置）
@@ -707,18 +620,6 @@ const disableAutoConnect = () => designer.value.disAutoConnect()
 - `disconnect()` 断开客户端连接
 - `disAutoConnect()` 关闭自动连接策略；阻止自动重连
 
-### 事件（Emits，含描述）
-
-- `save` 保存模板与数据；回调参数结构：
-
-```js
-{
-  template,   // 模板 JSON
-  data,       // 当前打印数据（对象或数组）
-  templateId  // 模板标识（若存在）
-}
-```
-
 示例：
 
 ```vue
@@ -728,14 +629,30 @@ const disableAutoConnect = () => designer.value.disAutoConnect()
     :initial-print-data="rows"
     default-lang="cn"
     @save="onSave"
+    @onDesigned="onDesigned"
   />
 </template>
 
 <script setup>
+/*  保存方法
+  template,   // 模板 JSON
+  data,       // 当前打印数据（对象或数组）
+  templateId  // 模板标识（若存在）
+*/
 const onSave = ({ template, data, templateId }) => {
   // 调用接口持久化到数据库
   // await api.saveTemplate({ template, data, templateId })
 }
+/*  设计器渲染完成后执行自定义逻辑
+  designer,    // hiprint.PrintTemplate 实例
+  template,    // 当前模板 JSON
+  source       // initial / incoming / library / json
+*/
+const onDesigned = ({ designer, template, source }) => {
+  // 设计器页面与初始模板已经完成加载
+  console.log(source, designer, template)
+  // 也可以在这里继续调用 designer.update(...) 或其他设计器方法
+}
 </script>
 ```
 
@@ -746,12 +663,96 @@ const onSave = ({ template, data, templateId }) => {
 
 ## 数据源使用说明
 
-`FullDesigner` 内置了数据源管理与字段绑定能力，可用于将接口字段自动映射到设计器组件字段下拉中。
+`FullDesigner` 内置了数据源管理与字段选择能力，可将接口返回字段集中整理，并在设计器字段属性中快速选择。
+
+### 外部传入数据源字段元数据（无需请求接口）
+
+如果业务系统已经取得表结构信息，不希望由 `vg-print` 再次请求接口，可以通过 `data-sources` 直接传入字段名和字段描述元数据。组件会根据这些元数据生成字段树，供设计器属性面板中的字段选择器使用；这种方式不依赖 axios，也不会把外部数据写入本地数据源配置。
+
+```vue
+<template>
+  <FullDesigner
+    :data-sources="designerDataSources"
+  />
+</template>
+
+<script setup>
+import { ref } from 'vue'
+
+// data-sources 用于设计态字段选择器，只传字段元数据，不传实际业务数据
+const designerDataSources = ref([
+  {
+    id: 'patient-info',
+    name: '患者信息',
+    groupName: '业务数据',
+    desc: '患者基本信息',
+    fields: [
+      { text: '主键', field: 'id' },
+      { text: '病人姓名', field: 'patientName' },
+      { text: '病人年龄', field: 'patientAge' },
+      { text: '科室名称', field: 'department.name' }
+    ]
+  },
+  {
+    id: 'fee-details',
+    name: '费用明细',
+    groupName: '业务数据',
+    desc: '患者费用明细',
+    fields: [
+      { text: '收费项目', field: 'itemName' },
+      { text: '金额', field: 'amount' }
+    ]
+  }
+])
+</script>
+```
+
+字段选择器中会按“业务数据 → 患者基本信息/患者费用明细 → 字段”展示。外层分类使用 `groupName`，默认数据集名称优先使用 `desc`；字段元数据变化后，字段树会随组件属性更新。
+
+如果需要自定义字段显示名称或多个数据集，可以直接传入完整数据集结构：
+
+```js
+const designerDataSources = [
+  {
+    id: 'patient-info',
+    name: '患者信息',
+    groupName: '业务数据',
+    desc: '患者基本信息',
+    dataSets: [
+      {
+        id: 'patient',
+        name: '患者资料',
+        fields: [
+          { text: '病人姓名', field: 'patientName' },
+          { text: '科室名称', field: 'department.name' }
+        ]
+      }
+    ]
+  }
+]
+```
+
+如果后端返回的是表结构记录，转换为可绑定字段：
+
+```js
+const designerDataSources = [
+  {
+    id: 'patient-info',
+    name: '患者信息',
+    groupName: '业务数据',
+    desc: '患者信息表',
+    data: [
+      { column_name: 'id', column_comment: '主键' },
+      { column_name: 'patientName', column_comment: '病人姓名' }
+    ]
+  }
+]
+```
 
 ### 入口与能力
 
 - 入口：二级工具栏点击“数据源”打开管理弹窗
-- 能力：数据源配置、测试获取、数据处理脚本、错误处理脚本、字段来源规则（全局/按组件类型）
+- 能力：数据源配置、分类管理、测试获取、数据处理脚本、错误处理脚本、字段树选择
 
 ### 使用流程（推荐）
 
@@ -764,10 +765,8 @@ const onSave = ({ template, data, templateId }) => {
 3. 编写“数据处理”脚本（`processCode`）并点击“测试链接”：
    - 左侧显示原始返回（`rawResult`）
    - 右侧显示处理结果（`processed`）
-4. 配置“字段来源规则”并保存：
-   - 看板全局：`manual` 或 `global`
-   - 组件规则：`manual` / `global` / `custom`
-5. 规则生效后，组件字段下拉会按规则自动展示字段列表
+4. 为数据源填写“分类名称”（不填写时使用唯一名称），便于在字段选择器中归类查找。
+5. 在设计器组件的“字段名”输入框后点击选择按钮，按“分类 → 数据集 → 字段”的树结构选取字段，选中后会自动回填。
 
 ### processCode / errorProcessCode 约定
 
@@ -787,7 +786,7 @@ $message.error(error.message)
 
 ### 字段结构约定
 
-推荐返回以下结构，字段下拉识别最稳定：
+推荐返回以下结构，字段树识别最稳定：
 
 ```js
 [
@@ -806,26 +805,6 @@ return (result.data || []).map(item => ({
 }))
 ```
 
-### 缓存与持久化策略（当前实现）
-
-- 数据源配置持久化：`KEY_VG_DATASOURCES`
-- 字段绑定规则持久化：`KEY_VG_FIELD_BINDINGS`
-- 数据源运行时缓存：`KEY_VG_DS_RUNTIME_CACHE`
-  - 仅缓存处理后数据（`processed`）
-  - 不缓存原始返回（`rawResult`）
-  - 默认 TTL：30 分钟
-  - 默认最大条目：20
-
-### 常见问题
-
-- 测试成功但没有字段：
-  - 检查 `processCode` 返回值是否为对象或对象数组
-  - 检查数据集 path 是否命中处理结果
-- 字段下拉未更新：
-  - 先“测试链接”生成字段，再“保存规则”
-- 表达式参数无效：
-  - `expression` 求值异常会被忽略，建议先用简单表达式验证
-
 ## 高级用法（hiprint）
 
 本库导出 `hiprint`，可直接创建与操作模板对象（`hiprint.PrintTemplate`）：
@@ -994,10 +973,6 @@ import {
 // 连接客户端（需要先启动客户端）
 connect()
 
-// 检查客户端是否已连接
-console.log(isClientConnected())
-
-
 // 1) 创建模板实例（可复用）
 const tpl = createTemplate(tmplJson)