@wvdl/wvdl

WVDL 引擎，基于元数据驱动视图构建的解决方案，提供不限于引擎协议、核心方法、适配器、渲染器、运行时、工具链等功能。

引擎介绍

以元数据驱动视图构建的核心思路，使用 WVDL 描述页面/组件树与布局，通过微内核 + 插件化的方式提供可扩展、可移植、可校验的低代码能力，支持集中配置与运行时覆盖。

环境要求

• Node.js: 建议 ^20.19.0 || >=22.12.0，理论兼容16+版本
• Vue 3（使用 Vue 3 内核时）
• Element Plus（使用 Element Plus 适配器时）
• Vite（使用配套插件时）

快速开始

安装依赖

• npm/yarn/pnpm 场景：

  • package.json

    npm i @wvdl/wvdl
    # 或
    pnpm add @wvdl/wvdl
    # 或
    yarn add @wvdl/wvdl

• Workspace 场景（monorepo）：

  • package.json

    {
      "dependencies": {
        "@wvdl/wvdl": "workspace:*"
      }
    }

Vite 配置

全局引擎配置注入 + Element Plus 组件按需导入能力

• createEngineConfigVitePlugin 会在构建时注入 engine.config.ts，让运行时隐式消费全局配置；
• createElementPlusVitePlugins 自动完成 Element Plus 组件/样式按需导入。
  • 若平台已使用 Element Plus 官方按需加载插件，则无需此插件。

appRoot/vite.config.ts：

import { defineConfig } from "vite";
import vue from "@vitejs/plugin-vue";
import vueJsx from "@vitejs/plugin-vue-jsx";
import vueDevTools from "vite-plugin-vue-devtools";
import { createElementPlusVitePlugins, createEngineConfigVitePlugin } from "@wvdl/wvdl/vite";

export default defineConfig({
  plugins: [
    vue(),
    vueJsx(),
    // 全局引擎配置注入
    createEngineConfigVitePlugin(),
    // Element Plus 组件按需导入（非必须）
    createElementPlusVitePlugins({
      dts: "src/auto-imports.d.ts",
      componentsDts: "src/components.d.ts",
    }),
    vueDevTools(),
  ],
});

全局引擎配置

引擎配置文件，生产环境建议使用 engine.config.ts，避免每次传入 config。

appRoot/engine.config.ts：

import type { EngineConfig } from "@wvdl/wvdl";
import CustomInput from "./src/components/CustomInput";

export const engineConfig: EngineConfig = {
  // 引擎核心
  core: "Vue",
  // UI 适配器
  ui: "ElementPlus",
  // 注册全局自定义组件
  registry: [
    { tag: "CustomInput", component: CustomInput },
  ],
  dev: {
    // 是否启用运行时注册全局自定义组件，默认为 `true`，避免生产环境重复注册。
    enableRuntimeRegistry: false,
  },
  // 扩展
  extensions: {},
};

使用引擎渲染器

apps/vue-example/src/views/AboutView.vue：

<script setup lang="ts">
import { shallowRef } from "vue";
import CustomEnum from "../components/CustomEnum";
import NodeInspector from "../components/NodeInspector.vue";
import { EngineRenderer, type RenderSchema } from "@wvdl/wvdl";
import { sampleSchema } from "../schema/sampleSchema";

const enableDevRegistry = true;
const devRegistry = [
  { tag: "CustomEnum", component: CustomEnum },
];
const schemaRef = shallowRef<RenderSchema>(structuredClone(sampleSchema));
</script>

<template>
  <NodeInspector v-model:schema="schemaRef" />
  <!-- 开发环境可通过 props 实时覆盖，与全局引擎配置文件不冲突，建议开发调试时使用，需要构建发布时建议删除 props 上的配置。 -->
  <EngineRenderer
    :schema="schemaRef"
    :registry="devRegistry"
    :enable-runtime-registry="enableDevRegistry"
  />
</template>

Schema 示例（节选）

appRoot/src/schema/sampleSchema.ts：

import type { RenderSchema } from "@wvdl/wvdl";

export const sampleSchema: RenderSchema = {
  version: "0.2.0",
  id: "page",
  type: "page",
  metaType: "Page",
  style: { tag: "ElContainer", layout: [[14, 10]] },
  dynamicService: {
    version: "0.2.0",
    serviceList: [
      {
        id: "loadForm",
        serviceId: "getFormData",
        trigger: "onMount",
        resultTo: "data.form",
      },
    ],
  },
  children: [
    {
      id: "field-name",
      type: "component",
      version: "0.2.0",
      metaType: "Div",
      style: { tag: "CustomInput", location: "1_1_12" },
      data: { modelValue: "引擎", placeholder: "请输入名称" },
      events: {
        "update:modelValue": "(value) => { data.modelValue = value; }",
      },
    },
  ],
};

运行时数据与通信机制（新增）

动态服务触发与数据落点

• dynamicService.serviceList 支持 onMount、onVisible、onEvent、manual 四类触发方式。
• resultTo 会把服务结果写入页面共享数据（如 data.list），供组件直接绑定或二次处理。
• onEvent 支持跨组件广播触发，用于多组件/父子表的联动场景。

页面共享数据注入

引擎渲染器会把页面共享数据注入到组件树中，自定义组件可通过 inject(PAGE_DATA_KEY) 获取：

import { inject, computed } from "vue";
import { PAGE_DATA_KEY } from "@wvdl/wvdl";

const pageData = inject(PAGE_DATA_KEY, computed(() => ({})));
const rows = computed(() => pageData.value?.data?.list ?? []);

onEvent 通讯示例

// A 组件：触发事件
events: {
  click: "(ctx) => { ctx.emit('list:reload', { keyword: data.keyword }); }",
},

// B 组件：监听事件并执行动态服务
dynamicService: {
  serviceList: [
    {
      id: "reloadList",
      trigger: "onEvent",
      event: "list:reload",
      serviceId: "queryList",
      resultTo: "data.list",
    },
  ],
},

进阶（初步集成时可忽略）

Schema 结构约定

• version 主版本号必须与引擎主版本号一致。
• style.layout 用二维数组声明网格，行列和不得超过 24。
• 子节点有布局时必须提供 style.location（形如 row_col_span）。

全局配置 vs 运行时注册

• 全局配置：通过 engine.config.ts 提供 registry，由 Vite 插件注入，适合线上环境。
• 运行时注册：通过 EngineRenderer 的 registry + enableRuntimeRegistry 动态注入，适合开发调试。

建议：

• 生产环境以集中配置为主，运行时注册可关闭。
• 开发环境可通过 props 临时覆盖。

Vite 插件说明

增强引擎能力的 Vite 插件。

• createEngineConfigVitePlugin()
  注入 engine.config.ts 到 @wvdl/core/engine-config，避免每次传入 config。

• createElementPlusVitePlugins()
  自动按需导入 Element Plus 组件和样式，并生成类型声明。

ESLint 配置说明

使用仓库内置的 Vue ESLint 基线配置

appRoot/eslint.config.ts：

import { vueConfig } from "@wvdl/wvdl/eslint";

export default [
  ...vueConfig,
];

事件脚本安全限制

事件脚本会被编译执行，默认禁止以下内容：

• 访问 window、document、globalThis、Function、eval、import、require 等
• 使用 this

违规将抛出 INVALID_SCHEMA 类型错误。

非 SFC 场景挂载（可选）

适用于脚本化渲染、自动化测试或第三方宿主集成。

import { mountEngine } from "@wvdl/wvdl";
import { sampleSchema } from "./schema/sampleSchema";

mountEngine({
  host: "#app",
  schema: sampleSchema,
  core: "Vue",
  ui: "ElementPlus",
  registry: [],
});