@jzg223/design-runtime 0.0.1 → 0.1.0-rc.2

package/CHANGELOG.md

@@ -3,6 +3,24 @@
 版本规则：semver。**破坏性改动**（`installDesignPlatform` 的参数、公开导出、组件 props）
 必须升大版本，并在本文件写清「宿主需要改什么」。
 
+## 0.1.0（未发布，分支 `feat/board`）
+
+目标：把**数据看板运行端**迁入本库（design-ui 负责设计与预览，本库负责执行）。立项 2026-10-27。
+
+- 组件：`DesignBoard`（+ `PartNode` / `PartRenderer` / `BoardChart`），覆盖 18 种部件、
+  自由布局（1920×1080 缩放）/ 栅格 / 移动端堆叠三种布局
+- 引擎单源：配置解析 / 布局样式 / 图表 option / 主题令牌 / 取数请求体抽成**零依赖**模块
+  （`src/board-engine/`，与 design-ui 逐字节一致，由 `test:board-fingerprint` 守住）
+- 渲染契约：`partRenderModel()` 输出外层/面板/标题/边距/装饰/类名，两端模板只照它铺 DOM
+- peer 新增：`echarts ^6.1.0`（**optional**，只有画图表时才动态加载）、
+  `@kjgl77/datav-vue3 ^1.7.4`（**optional**，边框/装饰部件，按编号懒加载）
+- 宿主注入新增：`board?: { http?, assetBaseUrl?, themeBaseUrl? }`
+- 多实例：参数 / 参数目录 / 取数缓存改为**每实例一份**（provide/inject），一页两个看板不串参数
+- 不包含：看板设计器、看板列表/授权、数据集配置（留在 design-ui）
+- 兼容性：对 0.0.1 的使用方**无破坏性改动**（只新增导出与可选注入字段）；
+  体积预算 1024 → 1536 KB（看板占 ~250 KB，其中 ~126 KB 是三个组件迁入后的 `.d.ts`）
+- 用例：`test:board` 42 + `test:board-render` 9 + `test:board-fingerprint` 9（全套 185 条）
+
 ## 0.0.1（2026-10-27 首次发布）
 
 首个对外可用版本。**本版本包含**：

package/README.md

@@ -198,6 +198,58 @@ transformTableConfig(config, '100%', {
 
 回归用例：`npm run test:table`（32 条，零依赖，跑的是 `dist` 产物，离线可跑）。
 
+## 数据看板（0.1.0）
+
+把 design-ui 里**设计好的看板**在业务宿主里渲染出来（设计/预览留在 design-ui，本库只负责执行）。
+
+### 1. 装依赖（两个 **optional** peer，用不到就不用装）
+
+```bash
+pnpm add @jzg223/design-runtime
+pnpm add echarts                   # 看板里有「图表」部件才需要（^6）
+pnpm add @kjgl77/datav-vue3        # 看板里有「边框/装饰」部件才需要（^1.7）
+```
+
+两者都是**动态 import**：不进本库产物，也不会进不用看板的宿主首屏。
+
+### 2. 注入看板能力（都可缺省）
+
+```ts
+installDesignPlatform({
+  http,                                  // 主 http（看板默认也用它）
+  board: {
+    http: boardHttp,                     // 可选：看板接口在别的服务时单独指
+    assetBaseUrl: '/server',             // 可选：素材直链前缀（asset: 引用），缺省同源
+    themeBaseUrl: '/board/theme/',       // 可选：主题 CSS 目录，缺省这个值
+  },
+})
+```
+
+### 3. 用
+
+```vue
+<DesignBoard code="EMP_BIGSCREEN" lang="zh-CHS" />
+```
+
+- 配置来源：`GET /design/board/info/queryByCode?code=`；
+- 部件取数：`POST /design/board/data/query`（同查询自动合并 + 1.5s 合并窗口，刷新用工具栏按钮）；
+- 参数目录：`GET /design/board/dataset/paramsBySets?ids=`（筛选控件的类型/可选值以数据集声明为准）；
+- 素材：`GET /design/board/asset/file?path=`（**不经 http**，拼成 `<img src>`）；
+- 主题：外部 CSS（`<themeBaseUrl>/<code>.css`，按需 `<link>`），库内只有 `:root` 级兜底 + 3 套内置。
+  47 套主题（651 KB）**不随包发**——它要能在部署后替换/新增。
+
+### 4. 三件要知道的事
+
+1. **必须先保存再看**：运行端只认 `code`，未保存的草稿没有 code（设计端的"预览"同理）。
+2. **多实例安全**：参数/取数缓存是 `provide/inject` 的**每实例一份**（不是模块级单例），
+   一页放两个看板不会串参数。
+3. **DataV 边框/装饰是懒加载的**：整包里 25 个组件按编号 `defineAsyncComponent` 映射，
+   配置里没用到就不会下载（`@kjgl77/datav-vue3` 解包 720 KB，是单入口整包，没有子路径导出）。
+
+回归用例：`npm run test:board`（引擎 42 条）+ `test:board-render`（组件 SSR 冒烟 9 条）+ `test:board-fingerprint`（双端指纹 9 条）。
+`test:board-fingerprint` 会去读同工作区的 `design-ui` 引擎做**逐字节对比**——两边任一被改却没同步就红；
+单独 clone 本库时找不到 `design-ui`，它会打印 SKIP 并成功退出。
+
 ## 开发
 
 ```bash

package/dist/board/api.js

@@ -0,0 +1,57 @@
+import { getHostBoard, requireHttp } from "../host.js";
+import { assetUrl } from "../board-engine/asset.js";
+function boardHttp() {
+  return getHostBoard().http ?? requireHttp();
+}
+function boardAssetBaseUrl() {
+  return String(getHostBoard().assetBaseUrl ?? "");
+}
+function unwrap(res) {
+  if (res && typeof res === "object" && "code" in res && "data" in res) {
+    return res.data;
+  }
+  return res;
+}
+async function fetchBoardInfo(code) {
+  if (!code) return null;
+  const res = await boardHttp().get("/design/board/info/queryByCode", {
+    params: { code },
+    silent: true
+  });
+  const data = unwrap(res);
+  return data && data.boardCode ? data : null;
+}
+async function fetchBoardData(body) {
+  try {
+    const res = await boardHttp().post("/design/board/data/query", body, { silent: true });
+    return unwrap(res) ?? null;
+  } catch (error) {
+    console.warn("[design-board] 部件取数失败：", error);
+    return null;
+  }
+}
+async function fetchBoardParams(ids) {
+  if (!ids) return [];
+  try {
+    const res = await boardHttp().get("/design/board/dataset/paramsBySets", {
+      params: { ids },
+      silent: true
+    });
+    const list = unwrap(res);
+    return Array.isArray(list) ? list : [];
+  } catch (error) {
+    console.warn("[design-board] 参数目录取数失败（筛选控件退化为手填）：", error);
+    return [];
+  }
+}
+function boardAssetUrl(value) {
+  return assetUrl(value, boardAssetBaseUrl());
+}
+export {
+  boardAssetBaseUrl,
+  boardAssetUrl,
+  boardHttp,
+  fetchBoardData,
+  fetchBoardInfo,
+  fetchBoardParams
+};

package/dist/board/board-chart.vue.js

@@ -0,0 +1,7 @@
+import _sfc_main from "./board-chart2.vue.js";
+/* empty css                 */
+import _export_sfc from "../_virtual/_plugin-vue_export-helper.js";
+const BoardChart = /* @__PURE__ */ _export_sfc(_sfc_main, [["__scopeId", "data-v-ab9edc2c"]]);
+export {
+  BoardChart as default
+};

package/dist/board/board-chart2.vue.js

@@ -0,0 +1,93 @@
+import { defineComponent, ref, onMounted, onBeforeUnmount, watch, openBlock, createElementBlock, toDisplayString, createCommentVNode } from "vue";
+const _hoisted_1 = {
+  key: 0,
+  class: "drb-chart__error"
+};
+const _sfc_main = /* @__PURE__ */ defineComponent({
+  __name: "board-chart",
+  props: {
+    option: { default: null }
+  },
+  emits: ["chart-click"],
+  setup(__props, { expose: __expose, emit: __emit }) {
+    const props = __props;
+    const emit = __emit;
+    const hostEl = ref(null);
+    const errorText = ref("");
+    let chart = null;
+    let observer = null;
+    let disposed = false;
+    async function loadEcharts() {
+      return import("./echarts.js");
+    }
+    function render() {
+      if (!chart) return;
+      const option = props.option;
+      if (!option || !Object.keys(option).length) {
+        chart.clear();
+        return;
+      }
+      chart.setOption(option, true);
+      chart.off("click");
+      chart.on("click", (payload) => emit("chart-click", payload));
+      resize();
+    }
+    function resize() {
+      if (!chart) return;
+      try {
+        chart.resize();
+      } catch {
+      }
+    }
+    onMounted(async () => {
+      if (!hostEl.value) return;
+      try {
+        const mod = await loadEcharts();
+        if (disposed || !hostEl.value) return;
+        const echarts = (mod == null ? void 0 : mod.default) ?? mod;
+        chart = echarts.init(hostEl.value);
+        render();
+        if (typeof ResizeObserver !== "undefined") {
+          observer = new ResizeObserver(() => resize());
+          observer.observe(hostEl.value);
+        }
+        window.addEventListener("resize", resize);
+      } catch (error) {
+        errorText.value = "图表不可用：宿主未安装 echarts（optional peer）";
+        console.error(
+          "[design-board] 加载 echarts 失败：请宿主执行 `pnpm add echarts`（^6；与 @vben/plugins 里那份同版本）。",
+          error
+        );
+      }
+    });
+    onBeforeUnmount(() => {
+      disposed = true;
+      window.removeEventListener("resize", resize);
+      if (observer) {
+        try {
+          observer.disconnect();
+        } catch {
+        }
+        observer = null;
+      }
+      if (chart) {
+        chart.dispose();
+        chart = null;
+      }
+    });
+    watch(() => props.option, () => render(), { deep: true });
+    __expose({ resize });
+    return (_ctx, _cache) => {
+      return openBlock(), createElementBlock("div", {
+        ref_key: "hostEl",
+        ref: hostEl,
+        class: "drb-chart"
+      }, [
+        errorText.value ? (openBlock(), createElementBlock("div", _hoisted_1, toDisplayString(errorText.value), 1)) : createCommentVNode("", true)
+      ], 512);
+    };
+  }
+});
+export {
+  _sfc_main as default
+};

package/dist/board/context.js

@@ -0,0 +1,15 @@
+import { inject } from "vue";
+const DESIGN_BOARD_CTX = Symbol("design-board-ctx");
+function useBoardContext() {
+  const ctx = inject(DESIGN_BOARD_CTX, null);
+  if (!ctx) {
+    throw new Error(
+      "[design-board] 缺少看板上下文：part-node / part-renderer 必须放在 <DesignBoard> 内部使用"
+    );
+  }
+  return ctx;
+}
+export {
+  DESIGN_BOARD_CTX,
+  useBoardContext
+};

package/dist/board/datav-map.js

@@ -0,0 +1,66 @@
+import { defineAsyncComponent } from "vue";
+const componentCache = /* @__PURE__ */ new Map();
+let datavModulePromise = null;
+let stylePromise = null;
+function loadDatavModule() {
+  if (!datavModulePromise) {
+    datavModulePromise = import("@kjgl77/datav-vue3").then((mod) => {
+      const exports = mod && mod.default && typeof mod.default === "object" && !mod.BorderBox1 ? mod.default : mod;
+      return exports;
+    }).catch((error) => {
+      datavModulePromise = null;
+      throw error;
+    });
+  }
+  return datavModulePromise;
+}
+function ensureDatavStyle() {
+  if (!stylePromise) {
+    stylePromise = import("@kjgl77/datav-vue3/dist/style.css").catch((error) => {
+      stylePromise = null;
+      console.warn("[design-board] datav 样式加载失败（边框/装饰会缺描边）：", error);
+      return null;
+    });
+  }
+  return stylePromise;
+}
+function lazyDatavComponent(name) {
+  const cached = componentCache.get(name);
+  if (cached) return cached;
+  const component = defineAsyncComponent(async () => {
+    await ensureDatavStyle();
+    const module = await loadDatavModule();
+    const resolved = module[name];
+    if (!resolved) {
+      console.warn(`[design-board] datav 组件 ${name} 不存在（@kjgl77/datav-vue3 版本不匹配？）`);
+      return { name: `Missing${name}`, render: () => null };
+    }
+    return resolved;
+  });
+  componentCache.set(name, component);
+  return component;
+}
+function datavBorderComponent(n, fallback = 8) {
+  const index = Number(n);
+  const safe = Number.isInteger(index) && index >= 1 && index <= 13 ? index : fallback;
+  return lazyDatavComponent(`BorderBox${safe}`);
+}
+function datavDecorationComponent(n, fallback = 5) {
+  const index = Number(n);
+  const safe = Number.isInteger(index) && index >= 1 && index <= 12 ? index : fallback;
+  return lazyDatavComponent(`Decoration${safe}`);
+}
+function preloadDatav() {
+  return ensureDatavStyle().then(() => loadDatavModule());
+}
+function resetDatavCache() {
+  componentCache.clear();
+  datavModulePromise = null;
+  stylePromise = null;
+}
+export {
+  datavBorderComponent,
+  datavDecorationComponent,
+  preloadDatav,
+  resetDatavCache
+};

package/dist/board/design-board.vue.js

@@ -0,0 +1,172 @@
+import _sfc_main from "./design-board2.vue.js";
+import { resolveComponent, openBlock, createElementBlock, normalizeStyle, createElementVNode, normalizeClass, toDisplayString, Fragment, renderList, createTextVNode, createCommentVNode, createBlock } from "vue";
+/* empty css                  */
+/* empty css                  */
+import _export_sfc from "../_virtual/_plugin-vue_export-helper.js";
+const _hoisted_1 = ["data-board-theme"];
+const _hoisted_2 = { class: "tb-title" };
+const _hoisted_3 = {
+  key: 0,
+  class: "tb-params"
+};
+const _hoisted_4 = ["onClick"];
+const _hoisted_5 = { class: "tb-ops" };
+const _hoisted_6 = ["value"];
+const _hoisted_7 = ["value"];
+const _hoisted_8 = {
+  key: 0,
+  class: "watermark"
+};
+const _hoisted_9 = {
+  key: 1,
+  class: "board-empty"
+};
+function _sfc_render(_ctx, _cache, $props, $setup, $data, $options) {
+  const _component_part_node = resolveComponent("part-node");
+  return openBlock(), createElementBlock("div", {
+    ref: "stage",
+    class: "board-view",
+    "data-board-theme": $options.themeCode,
+    style: normalizeStyle($options.stageStyle)
+  }, [
+    createElementVNode("div", {
+      class: normalizeClass(["board-toolbar", { "is-hidden": $data.toolbarHidden, "is-mobile": $options.isMobile }])
+    }, [
+      createElementVNode("span", _hoisted_2, toDisplayString($data.board.boardName || "看板"), 1),
+      $options.activeParams.length ? (openBlock(), createElementBlock("span", _hoisted_3, [
+        (openBlock(true), createElementBlock(Fragment, null, renderList($options.activeParams, (p) => {
+          return openBlock(), createElementBlock("span", {
+            key: p.code,
+            class: "tb-param"
+          }, [
+            createTextVNode(toDisplayString(p.code) + " = " + toDisplayString(p.value), 1),
+            createElementVNode("i", {
+              class: "tb-param__x",
+              title: "清除该参数",
+              onClick: ($event) => $options.clearParam(p.code)
+            }, "×", 8, _hoisted_4)
+          ]);
+        }), 128)),
+        createElementVNode("a", {
+          class: "tb-clear",
+          onClick: _cache[0] || (_cache[0] = (...args) => $options.clearAllParams && $options.clearAllParams(...args))
+        }, "清空")
+      ])) : createCommentVNode("", true),
+      createElementVNode("span", _hoisted_5, [
+        createElementVNode("select", {
+          class: "tb-lang",
+          value: $data.locale,
+          onChange: _cache[1] || (_cache[1] = ($event) => $options.onLocaleChange($event.target.value))
+        }, [
+          (openBlock(true), createElementBlock(Fragment, null, renderList($data.locales, (l) => {
+            return openBlock(), createElementBlock("option", {
+              key: l.code,
+              value: l.code
+            }, toDisplayString(l.label), 9, _hoisted_7);
+          }), 128))
+        ], 40, _hoisted_6),
+        createElementVNode("button", {
+          type: "button",
+          class: "tb-btn",
+          title: "刷新数据",
+          onClick: _cache[2] || (_cache[2] = (...args) => $options.refresh && $options.refresh(...args))
+        }, [..._cache[6] || (_cache[6] = [
+          createElementVNode("svg", {
+            viewBox: "0 0 16 16",
+            width: "14",
+            height: "14",
+            "aria-hidden": "true"
+          }, [
+            createElementVNode("path", {
+              fill: "currentColor",
+              d: "M13.5 8a5.5 5.5 0 1 1-1.6-3.9l-1.7 1.7h4.6V1.2l-1.5 1.5A7 7 0 1 0 15 8h-1.5z"
+            })
+          ], -1)
+        ])]),
+        createElementVNode("button", {
+          type: "button",
+          class: "tb-btn",
+          title: "全屏",
+          onClick: _cache[3] || (_cache[3] = (...args) => $options.toggleFullscreen && $options.toggleFullscreen(...args))
+        }, [..._cache[7] || (_cache[7] = [
+          createElementVNode("svg", {
+            viewBox: "0 0 16 16",
+            width: "14",
+            height: "14",
+            "aria-hidden": "true"
+          }, [
+            createElementVNode("path", {
+              fill: "currentColor",
+              d: "M1 1h5v1.5H3.06L6.5 5.94 5.44 7 2.5 4.06V6.5H1V1zm14 14h-5v-1.5h2.94L9.5 10.06 10.56 9l2.94 2.94V9.5H15V15z"
+            })
+          ], -1)
+        ])]),
+        createElementVNode("button", {
+          type: "button",
+          class: "tb-btn",
+          title: "隐藏工具栏",
+          onClick: _cache[4] || (_cache[4] = ($event) => $data.toolbarHidden = true)
+        }, [..._cache[8] || (_cache[8] = [
+          createElementVNode("svg", {
+            viewBox: "0 0 16 16",
+            width: "14",
+            height: "14",
+            "aria-hidden": "true"
+          }, [
+            createElementVNode("path", {
+              fill: "currentColor",
+              d: "M8 3c3 0 5.6 1.7 7 5-1.4 3.3-4 5-7 5S2.4 11.3 1 8c1.4-3.3 4-5 7-5zm0 1.5C5.9 4.5 4 5.7 2.7 8c1.3 2.3 3.2 3.5 5.3 3.5s4-1.2 5.3-3.5C12 5.7 10.1 4.5 8 4.5zm0 1.2a2.3 2.3 0 1 1 0 4.6 2.3 2.3 0 0 1 0-4.6z"
+            })
+          ], -1)
+        ])])
+      ])
+    ], 2),
+    $data.toolbarHidden ? (openBlock(), createElementBlock("div", {
+      key: 0,
+      class: "show-toolbar",
+      title: "显示工具栏",
+      onClick: _cache[5] || (_cache[5] = ($event) => $data.toolbarHidden = false)
+    }, "⚙")) : createCommentVNode("", true),
+    createElementVNode("div", {
+      class: "board-scroll",
+      style: normalizeStyle($options.scrollStyle)
+    }, [
+      createElementVNode("div", {
+        class: "canvas-holder",
+        style: normalizeStyle($options.holderStyle)
+      }, [
+        createElementVNode("div", {
+          class: "board-canvas",
+          style: normalizeStyle($options.canvasStyle)
+        }, [
+          (openBlock(true), createElementBlock(Fragment, null, renderList($options.topParts, (p) => {
+            return openBlock(), createBlock(_component_part_node, {
+              key: p.id,
+              "extra-class": "view-part",
+              part: p,
+              page: $data.config.page,
+              "all-parts": $options.visibleParts,
+              "theme-code": $data.config.page.chartTheme,
+              "refresh-key": $data.refreshKey,
+              "params-version": $data.paramsVersion,
+              narrow: $options.narrow || $options.stacked,
+              stacked: $options.stacked
+            }, null, 8, ["part", "page", "all-parts", "theme-code", "refresh-key", "params-version", "narrow", "stacked"]);
+          }), 128)),
+          $data.config.page.watermark ? (openBlock(), createElementBlock("div", _hoisted_8, toDisplayString($data.config.page.watermark), 1)) : createCommentVNode("", true)
+        ], 4)
+      ], 4)
+    ], 4),
+    !$data.board.id && !$data.loading ? (openBlock(), createElementBlock("div", _hoisted_9, [
+      _cache[9] || (_cache[9] = createElementVNode("span", {
+        class: "board-empty__icon",
+        "aria-hidden": "true"
+      }, "!", -1)),
+      createElementVNode("p", null, toDisplayString($data.errorMessage || "看板不存在或没有访问权限"), 1)
+    ])) : createCommentVNode("", true)
+  ], 12, _hoisted_1);
+}
+const designBoard = /* @__PURE__ */ _export_sfc(_sfc_main, [["render", _sfc_render], ["__scopeId", "data-v-16c3c220"]]);
+export {
+  designBoard as default
+};