vg-print 1.1.0 → 1.1.1

package/README.md

@@ -550,6 +550,88 @@ const onSave = ({ template, data, templateId }) => {
 - 通过 `default-lang` 设置初始语言（`cn` 默认为中文）；内部会同步 `vue-i18n` 与 `hiprint` 的语言。
 - 运行时可在页面右上角语言切换菜单切换（无需刷新）。
 
+## 数据源使用说明
+
+`FullDesigner` 内置了数据源管理与字段绑定能力，可用于将接口字段自动映射到设计器组件字段下拉中。
+
+### 入口与能力
+
+- 入口：二级工具栏点击“数据源”打开管理弹窗
+- 能力：数据源配置、测试获取、数据处理脚本、错误处理脚本、字段来源规则（全局/按组件类型）
+
+### 使用流程（推荐）
+
+1. 新增数据源并填写基础信息：
+   - 唯一名称
+   - 请求地址（URL）
+   - 请求方法（GET/POST/PUT/DELETE）
+2. 按需配置请求头、参数、发送数据：
+   - 类型支持：`string`、`number`、`boolean`、`expression`
+3. 编写“数据处理”脚本（`processCode`）并点击“测试链接”：
+   - 左侧显示原始返回（`rawResult`）
+   - 右侧显示处理结果（`processed`）
+4. 配置“字段来源规则”并保存：
+   - 看板全局：`manual` 或 `global`
+   - 组件规则：`manual` / `global` / `custom`
+5. 规则生效后，组件字段下拉会按规则自动展示字段列表
+
+### processCode / errorProcessCode 约定
+
+- `processCode` 函数形态：
+
+```js
+// (result, isSandbox, DSV, VFR) => { ...; return processed; }
+return result
+```
+
+- `errorProcessCode` 函数形态：
+
+```js
+// (error, isSandbox, DSV, $message, VFR) => { ... }
+$message.error(error.message)
+```
+
+### 字段结构约定
+
+推荐返回以下结构，字段下拉识别最稳定：
+
+```js
+[
+  { text: '字段显示名', field: '字段路径' }
+]
+```
+
+如果返回的是对象或对象数组，系统也会自动递归提取字段路径（如 `user.name`、`order.items`）。
+
+### 示例：将接口返回转换为字段列表
+
+```js
+return (result.data || []).map(item => ({
+  field: item.column_name,
+  text: item.table_comment || item.column_name
+}))
+```
+
+### 缓存与持久化策略（当前实现）
+
+- 数据源配置持久化：`KEY_VG_DATASOURCES`
+- 字段绑定规则持久化：`KEY_VG_FIELD_BINDINGS`
+- 数据源运行时缓存：`KEY_VG_DS_RUNTIME_CACHE`
+  - 仅缓存处理后数据（`processed`）
+  - 不缓存原始返回（`rawResult`）
+  - 默认 TTL：30 分钟
+  - 默认最大条目：20
+
+### 常见问题
+
+- 测试成功但没有字段：
+  - 检查 `processCode` 返回值是否为对象或对象数组
+  - 检查数据集 path 是否命中处理结果
+- 字段下拉未更新：
+  - 先“测试链接”生成字段，再“保存规则”
+- 表达式参数无效：
+  - `expression` 求值异常会被忽略，建议先用简单表达式验证
+
 ## 高级用法（hiprint）
 
 本库导出 `hiprint`，可直接创建与操作模板对象（`hiprint.PrintTemplate`）：

package/dist/{chunk-MW6X4KTL-BGX4AdvZ.js → chunk-MW6X4KTL-BXi3UvAj.js}

@@ -1,4 +1,4 @@
-import { l as b } from "./index-CFsMCiM-.js";
+import { l as b } from "./index-uN5-3hGS.js";
 function M(e) {
   return typeof e == "string" && /^data:image\/svg\+xml/i.test(e);
 }

package/dist/{chunk-Q2Z2CG2I-4zALoFop.js → chunk-Q2Z2CG2I-BwVO1E3F.js}

@@ -1,4 +1,4 @@
-import { W as a } from "./chunk-MW6X4KTL-BGX4AdvZ.js";
+import { W as a } from "./chunk-MW6X4KTL-BXi3UvAj.js";
 async function o(r, t) {
   let i = await a(r, t), e = new Image();
   return e.src = i.toDataURL(`image/${t.format}`, t.quality), await e.decode(), e.style.width = `${i.width / t.dpr}px`, e.style.height = `${i.height / t.dpr}px`, e;

package/dist/{chunk-Y7FY32AO-CBomeJj8.js → chunk-Y7FY32AO-Dbd6pbtx.js}

@@ -1,4 +1,4 @@
-import { W as m } from "./chunk-MW6X4KTL-BGX4AdvZ.js";
+import { W as m } from "./chunk-MW6X4KTL-BXi3UvAj.js";
 async function a(n, e) {
   let o = e.type;
   if (o === "svg") {

package/dist/{download-DTiI2jHs.js → download-EEjuwbYb.js}

@@ -1,5 +1,5 @@
-import { m as f } from "./chunk-Y7FY32AO-CBomeJj8.js";
-import { W as t } from "./chunk-MW6X4KTL-BGX4AdvZ.js";
+import { m as f } from "./chunk-Y7FY32AO-Dbd6pbtx.js";
+import { W as t } from "./chunk-MW6X4KTL-BXi3UvAj.js";
 async function w(n, e) {
   let c = ((e == null ? void 0 : e.format) || (e == null ? void 0 : e.type) || "").toLowerCase(), a = c === "jpg" ? "jpeg" : c || "png", i = (e == null ? void 0 : e.filename) || `snapdom.${a}`, o = { ...e || {}, format: a, type: a };
   if (o.dpr = 1, a === "svg") {