数据源面板 plugin-view-data-source

约 1741 字大约 6 分钟

...

2026-09-28

插件说明

在设计器中挂载一个可拖拽的数据源窗口（DragBox）+ 字段树 + 字段选择弹窗（Picker），将字段拖入属性面板参数或元素 DOM 完成字段绑定。不连数据库，数据源是前端配置。

核心能力：

可拖拽移动 / 缩放 / 最小化 / 隐藏的 DragBox 面板，toolbar 自动插入显隐图标
多数据源可折叠树列表，defaultExpand 控制默认展开，按需懒加载
内置「添加数据源」弹窗：JSON 数据（自动识别样本/字段）、Schema、接口请求（含高级参数与「测试请求」字段预览）
树形嵌套字段：对象（user.address.city）与数组（items[].name）无限层级
从 sampleData 或 schema 自动推断字段树；字段实时搜索、跨数据源全局搜索
拖拽字段到「字段名」参数或元素 DOM 上自动绑定 field（首次设置、再次追加）
字段名 Tag 盒子（默认开启）：多选、拖拽排序、删除；表格列 columnField 同样支持
点击字段项直接设置选中元素 field（enableClickToSetField，默认关闭）
UI 完全自定义：panelRender / fieldItemRender / pickerRender / fieldTagRender，支持 Vue / React / jQuery / 原生 JS
模板实例扩展 bindDataSource / printFromDataSource 等；运行时 API 挂载到 designerUtils.dataSource

无第三方依赖（UI 基于 sv-print 的 DragBox 组件）。

npm install @sv-print/plugin-view-data-source

注意

插件包含 UI 组件，必须引入样式文件：import '@sv-print/plugin-view-data-source/dist/style.css';

示例代码

import '@sv-print/plugin-view-data-source/dist/style.css'; // 必须引入样式文件
import dataSourcePlugin from '@sv-print/plugin-view-data-source';

await hiprint.register({
  // 需在设计器初始化前完成注册
  plugins: [
    dataSourcePlugin({
      sources: [
        {
          name: 'order',
          title: '订单数据',
          sampleData: {
            orderNo: 'A001',
            amount: 99.5,
            customer: { name: '张三', phone: '13800000000' },
            items: [{ sku: 'S1', qty: 2 }],
          },
          // 自动推断字段树: orderNo / amount / customer.name / items[].sku ...
        },
        {
          name: 'api',
          title: '接口字段',
          defaultExpand: false, // 默认折叠, 首次展开时懒加载
          request: { url: '/api/user/fields', dataPath: 'data.list' }, // request 数据源懒加载：未加载时 getFields 返回空数组
        },
      ],
    }),
  ],
});

静态字段写法：

dataSourcePlugin({
  sources: [
    {
      name: 'default',
      data: [
        { field: 'name', label: '姓名', type: 'string' },
        { field: 'age', label: '年龄', type: 'number' },
      ],
    },
  ],
});

高级用法

PluginConfig 主要参数

参数	类型	默认	说明
`sources`	`DataSourceItem[]`	-	数据源配置
`requestAdapter`	`(config) => Promise<any>`	-	全局自定义请求适配器（如换用 axios）
`enableFieldTagBox`	`boolean`	`true`	字段名参数替换为 Tag 盒子（多选/排序/删除）
`fieldTagRender`	`(ctx) => void`	-	自定义 Tag 盒子渲染
`enableTemplateExtend`	`boolean`	-	是否启用模板数据源扩展（bindDataSource 等）
`enableFieldPicker`	`boolean`	-	是否启用字段名参数弹窗选择
`enableClickToSetField`	`boolean`	`false`	点击字段项时设置选中元素 field
`pickerMultiple`	`boolean`	`false`	弹窗多选模式（选择后默认不自动关闭）
`pickerCloseOnSelect`	`boolean`	-	选择后是否关闭弹窗（默认：单选关、多选不关）
`onFieldSet`	`(field, element, kind) => boolean \| void`	-	字段应用到元素/tagbox 时回调，返回 `false` 拦截
`panelRender` / `fieldItemRender` / `pickerRender`	`(ctx) => void`	-	面板 / 字段项 / 弹窗自定义渲染
`dragBoxStyle`	`string`	-	DragBox 样式
`defaultShow`	`boolean`	-	是否默认显示数据源窗口
`icon`	`string`	-	数据源图标 class
`dragBoxOrder` / `dragBoxInsert`	`number` / `(list, item) => any[]`	`1`	toolbar 图标插入位置（`dragBoxInsert` 优先级更高）

DataSourceItem 数据源

属性	类型	说明
`name`	`string`	数据源名称（唯一标识）
`title`	`string`	显示名称，默认同 `name`
`data`	`DataSourceField[]`	静态字段数据
`rawData`	`any`	原始数据（配合 `data` 提供打印数据）
`sampleData`	`any`	数据样本，自动推断字段树
`schema`	`object`	JSON Schema，自动解析为字段树
`request`	`DataSourceRequestConfig`	请求配置：`url/method/params/data/headers/dataPath/fieldMap/autoParse`
`fetcher`	`() => Promise<any>`	自定义取数函数（优先级最高）
`asPrintData`	`boolean`	fetcher 返回的数据直接作为打印数据
`defaultExpand`	`boolean`	多数据源树列表中是否默认展开，默认 `true`

取数优先级：fetcher() → request（url/method/headers/dataPath 提取）→ data → sampleData（推断）→ schema。

运行时 API（designerUtils.dataSource）

方法	说明
`refresh(name?)`	刷新全部 / 指定数据源
`getFields(name?)` / `getFieldTree(name?)`	获取扁平字段列表 / 字段树
`setFields(fields, name?)`	手动设置字段（面板立即更新，refresh 不冲掉）
`getSources()` / `getSource(name)`	获取数据源列表 / 单个
`addSource(config)` / `removeSource(name)`	动态添加 / 移除数据源（同名覆盖会清除手动字段与缓存）
`showPicker(callback?, options?)`	弹窗选择字段；`options.onlyFields` 限定可选字段完整路径
`closePicker()`	关闭弹窗
`show()` / `hide()` / `toggle()`	面板显隐（与 toolbar 图标高亮态同步）
`search(keyword)`	跨数据源搜索（仅已加载字段）

模板扩展方法

方法	说明
`bindDataSource(name?)`	绑定数据源，设置 `template.fields`，字段名参数自动变为 select
`printFromDataSource(name?, options?)`	取数并浏览器打印
`print2FromDataSource(name?, options?)`	取数并静默打印
`getHtmlFromDataSource(name?)`	取数并生成 HTML
`getDataSourceData(name?)`	获取打印数据（未注册 / 加载失败时抛出错误）
`restoreDataSource()`	恢复被覆盖的原生方法（销毁模板等清理时调用）

不传 name 时使用全部数据源：单数据源直接返回其数据，多数据源对象浅合并（非对象数据挂到数据源名下）。

工具函数导出

import {
  parseData, // 从数据样本推断字段树
  parseSchema, // 从 JSON Schema 解析字段树
  flattenFields, // 树形字段扁平化
  getByPath, // 按路径取值, 支持 items[].name
  buildPath, // 生成嵌套字段路径
  getFullPath, // 还原数组子项的完整路径
  findNodeInTree, // 在字段树中查找指定 path 节点
  resolveColumnFieldPaths, // 解析表格列字段的可用字段路径列表
} from '@sv-print/plugin-view-data-source';

存储与拖拽协议

字段拖拽 MIME：application/x-dataSourceField，payload 为 { source, field, label, type, parent }
写入 tagbox 后双写：options.field（逗号分隔字符串，兼容内核）+ options.dsFieldTags（结构化 JSON，新事实来源，多源同名消歧）；表格列对应 options.columnField + options.dsColumnFieldTags，两套存储互不干扰
老模板仅有 options.field 字符串时也能正常回显，自动从 path 匹配数据源 label
拖拽到元素 DOM：首次拖拽设置为该字段，再次拖拽追加为多字段（按 source + field 联合去重）

注意事项

view-ele-tools 工具条上的「数据源」按钮调用 designerUtils.dataSource.showPicker，需先安装本插件
request 类型数据源懒加载：未加载时 getFields 返回空数组，展开分组 / refresh / showPicker / getDataSourceData 均会触发加载
自定义 fieldItemRender 时整个字段树由回调完全接管（展开/折叠、选中交互需自行处理）；panelRender 与 fieldItemRender 不能同时提供，深度自定义优先用 panelRender

版权所有

版权归属：sv-print

许可证：署名 4.0 国际 (CC-BY-4.0)