VSchema-UI

一个强大的 Vue 3 插件，通过 JSON Schema 声明式构建动态 UI。支持响应式数据、计算属性、事件处理、条件渲染、循环渲染、API 调用、WebSocket 等完整功能。

English | 简体中文

✨ 特性

🎯 声明式配置 - 通过 JSON Schema 定义组件结构，无需编写 Vue 模板
🔄 响应式数据 - 完整支持 Vue 3 响应式系统
📊 计算属性 - 支持表达式计算和派生状态
🎪 事件处理 - 灵活的事件绑定和动作系统
🔀 条件渲染 - 支持 if 和 show 指令
🔁 循环渲染 - 支持 for 指令遍历数组
📝 表单绑定 - 支持 model 双向绑定
🌐 API 调用 - 内置 fetch 动作和 initApi/uiApi 配置
🔌 WebSocket - 支持长连接和实时通信
📋 剪贴板 - 内置 copy 动作，兼容各种浏览器
🎰 插槽支持 - 支持默认插槽、具名插槽和作用域插槽
🔄 生命周期 - 支持 onMounted、onUnmounted、onUpdated 钩子
👁️ 监听器 - 支持 watch 监听状态变化
🧩 组件注册 - 支持注册自定义组件
🔒 安全 - 内置表达式安全检查，防止 XSS 攻击

📦 安装

pnpm add vschema-ui
# 或
npm install vschema-ui
# 或
yarn add vschema-ui

🚀 快速开始

方式一：全局注册插件

import { createApp } from 'vue';
import { VSchemaPlugin } from 'vschema-ui';
import App from './App.vue';

const app = createApp(App);
app.use(VSchemaPlugin);
app.mount('#app');

<template>
  <VSchema :schema="schema" />
</template>

方式二：按需导入组件

<template>
  <VSchema :schema="schema" />
</template>

<script setup lang="ts">
import { VSchema } from 'vschema-ui';
import type { JsonNode } from 'vschema-ui';

const schema: JsonNode = {
  data: { count: 0 },
  com: 'div',
  children: [
    { com: 'p', children: '计数: {{ count }}' },
    {
      com: 'button',
      events: { click: { set: 'count', value: '{{ count + 1 }}' } },
      children: '增加'
    }
  ]
};
</script>

方式三：创建自定义配置的组件

import { createVSchema } from 'vschema-ui';
import MyButton from './components/MyButton.vue';

// 创建带配置的 VSchema 组件
const VSchema = createVSchema({
  baseURL: 'https://api.example.com',
  components: {
    MyButton,  // 注册自定义组件
  },
  defaultHeaders: {
    'Authorization': 'Bearer token'
  }
});

export default VSchema;

基础示例

<template>
  <VSchema :schema="schema" />
</template>

<script setup lang="ts">
import type { JsonNode } from 'vschema-ui';

const schema: JsonNode = {
  data: { count: 0 },
  com: 'div',
  children: [
    { com: 'p', children: '计数: {{ count }}' },
    {
      com: 'button',
      events: { click: { set: 'count', value: '{{ count + 1 }}' } },
      children: '增加'
    }
  ]
};
</script>

3. 注入外部数据和方法

<template>
  <VSchema 
    :schema="schema" 
    :initial-data="initialData"
    :methods="externalMethods"
  />
</template>

<script setup lang="ts">
import type { JsonNode } from 'vschema-ui';

const schema: JsonNode = {
  data: { form: { username: '', password: '' } },
  com: 'div',
  children: [
    {
      com: 'input',
      model: 'form.username',
      props: { placeholder: '用户名' }
    },
    {
      com: 'button',
      events: {
        click: {
          script: 'await $methods.login(state.form.username, state.form.password);'
        }
      },
      children: '登录'
    }
  ]
};

const initialData = { appName: 'My App' };

const externalMethods = {
  login: async (username: string, password: string) => {
    console.log('登录:', username, password);
  }
};
</script>

📖 Schema 结构

VSchema 组件 Props

属性	类型	说明
`schema`	`JsonNode \| string`	JSON Schema 定义（对象或 JSON 字符串）
`config`	`GlobalConfig`	组件级别的配置（覆盖全局配置）
`initialData`	`object`	初始化数据，会与 schema.data 合并
`methods`	`object`	外部注入的方法，可在 script 动作中通过 `$methods` 访问

基础属性

属性	类型	说明
`com`	`string`	组件类型（HTML 标签或注册的组件名）
`props`	`object`	传递给组件的 props
`children`	`JsonNode[] \| string`	子节点或文本内容
`events`	`object`	事件处理器
`slots`	`object`	插槽定义

指令属性

属性	类型	说明
`if`	`string`	条件渲染（v-if）
`show`	`string`	显示/隐藏（v-show）
`for`	`string`	循环渲染，格式: `"item in items"` 或 `"(item, index) in items"`
`key`	`string`	循环项的 key
`model`	`string`	双向绑定（v-model）
`ref`	`string`	模板引用

数据和逻辑

属性	类型	说明
`data`	`object`	响应式数据定义（Schema 中声明）
`computed`	`object`	计算属性（值为表达式字符串）
`watch`	`object`	监听器
`methods`	`object`	方法定义

💡 data vs state: data 用于 Schema 中声明初始数据，运行时通过 state 访问当前状态

生命周期钩子

属性	类型	说明
`onMounted`	`Action \| Action[]`	组件挂载后执行
`onUnmounted`	`Action \| Action[]`	组件卸载前执行
`onUpdated`	`Action \| Action[]`	组件更新后执行

API 配置

属性	类型	说明
`initApi`	`string \| ApiConfig`	组件挂载时请求 API，返回数据与 `data` 合并
`uiApi`	`string \| ApiConfig`	组件挂载时请求 API，返回 JsonNode 替换 `children`

🎬 动作类型 (Actions)

Set 动作 - 修改状态

{ "set": "count", "value": "{{ count + 1 }}" }

Call 动作 - 调用方法

{ "call": "methodName", "args": ["{{ arg1 }}", "{{ arg2 }}"] }

Emit 动作 - 触发事件

{ "emit": "eventName", "payload": "{{ data }}" }

Fetch 动作 - API 调用

{
  "fetch": "https://api.example.com/data",
  "method": "POST",
  "body": { "key": "{{ value }}" },
  "then": { "set": "result", "value": "{{ $response }}" },
  "catch": { "set": "error", "value": "{{ $error.message }}" }
}

Copy 动作 - 复制到剪贴板

{
  "copy": "{{ shareUrl }}",
  "then": { "set": "copied", "value": true },
  "catch": { "set": "error", "value": "{{ $error.message }}" }
}

兼容性：优先使用 Clipboard API，自动降级到 execCommand

WebSocket 动作 - 长连接

{
  "ws": "wss://example.com/socket",
  "op": "connect",
  "id": "main",
  "onMessage": { "set": "lastMessage", "value": "{{ $response }}" }
}

If 动作 - 条件执行

{
  "if": "count > 10",
  "then": { "set": "message", "value": "大于10" },
  "else": { "set": "message", "value": "小于等于10" }
}

Script 动作 - 自定义脚本

{
  "script": "await $methods.login(state.form.username, state.form.password);"
}

可用变量： state, computed, $event, $response, $error, $methods

📝 表达式语法

使用 {{ expression }} 语法在字符串中嵌入表达式：

{
  "children": "你好，{{ user.name }}！",
  "props": {
    "class": "{{ isActive ? 'active' : 'inactive' }}",
    "disabled": "{{ loading }}"
  }
}

🌐 initApi 和 uiApi

initApi - 初始化数据

{
  "data": { "title": "加载中..." },
  "initApi": "/api/posts",
  "com": "div",
  "children": "{{ title }}"
}

uiApi - 动态 UI 加载

{
  "uiApi": "/api/page/{{ pageId }}",
  "com": "div",
  "children": "加载中..."
}

🎰 插槽支持

简单插槽

{
  "com": "MyCard",
  "slots": {
    "default": [{ "com": "p", "children": "内容" }],
    "header": [{ "com": "h3", "children": "标题" }]
  }
}

作用域插槽

{
  "com": "MyList",
  "slots": {
    "item": {
      "content": [{ "com": "span", "children": "{{ slotProps.item.name }}" }],
      "slotProps": "slotProps"
    }
  }
}

🧩 注册自定义组件

import { useComponentRegistry } from 'vschema-ui';
import MyButton from './MyButton.vue';

const registry = useComponentRegistry();
registry.register('MyButton', MyButton);

⚙️ 全局配置

import { createApp } from 'vue';
import { createVSchemaPlugin } from 'vschema-ui';

const app = createApp(App);

app.use(createVSchemaPlugin({
  baseURL: 'https://api.example.com',
  defaultHeaders: {
    'Authorization': 'Bearer token'
  },
  responseDataPath: 'data',
  // API 响应格式配置
  responseFormat: {
    codeField: 'code',      // 业务状态码字段名，默认 'code'
    msgField: 'msg',        // 消息字段名，默认 'msg'
    dataField: 'data',      // 数据字段名，默认 'data'
    successCode: 200,       // 业务成功状态码，默认 200，支持数组如 [0, 200]
  },
  components: {
    MyButton: MyButtonComponent
  }
}));

响应格式配置

VSchema 支持自定义后端 API 返回格式，默认格式为 { code, msg, data }：

// 自定义响应格式
responseFormat: {
  codeField: 'status',      // 后端使用 status 字段
  msgField: 'message',      // 后端使用 message 字段
  dataField: 'result',      // 后端使用 result 字段
  successCode: [0, 200],    // 0 和 200 都表示成功
}

当 API 返回的业务状态码不等于 successCode 时，会自动触发 catch 回调，错误信息从 msgField 字段提取。

🎹 事件修饰符

支持 Vue 事件修饰符语法：

{
  "events": {
    "click.prevent.stop": { "call": "handleClick" },
    "keyup.enter": { "call": "submit" },
    "keyup.ctrl.s": { "call": "save" }
  }
}

支持的修饰符：.prevent, .stop, .capture, .self, .once, .passive, .enter, .tab, .esc, .space, .up, .down, .left, .right, .ctrl, .alt, .shift, .meta

👁️ Watch 监听器

{
  "watch": {
    "searchText": { "call": "doSearch" },
    "user": {
      "handler": { "call": "onUserChange" },
      "immediate": true,
      "deep": true
    }
  }
}

🔐 安全特性

表达式求值器内置安全检查，禁止以下危险操作：

eval(), Function() 等代码执行
window, document, globalThis 等全局对象访问
constructor, __proto__ 等原型链操作
直接的 fetch, XMLHttpRequest 调用（请使用 fetch 动作）

📚 完整示例

计数器

{
  "data": { "count": 0 },
  "computed": { "double": "count * 2" },
  "com": "div",
  "children": [
    { "com": "p", "children": "计数: {{ count }}, 双倍: {{ double }}" },
    {
      "com": "button",
      "events": { "click": { "set": "count", "value": "{{ count + 1 }}" } },
      "children": "增加"
    }
  ]
}

待办事项

{
  "data": { "todos": [], "newTodo": "" },
  "methods": {
    "addTodo": {
      "if": "newTodo.trim()",
      "then": [
        { "set": "todos", "value": "{{ [...todos, { id: Date.now(), text: newTodo }] }}" },
        { "set": "newTodo", "value": "" }
      ]
    }
  },
  "com": "div",
  "children": [
    {
      "com": "input",
      "model": "newTodo",
      "props": { "placeholder": "添加任务..." },
      "events": { "keyup.enter": { "call": "addTodo" } }
    },
    {
      "com": "ul",
      "children": [
        {
          "for": "todo in todos",
          "key": "{{ todo.id }}",
          "com": "li",
          "children": "{{ todo.text }}"
        }
      ]
    }
  ]
}

🛠️ 开发

# 安装依赖
pnpm install

# 启动开发服务器
pnpm dev

# 运行测试
pnpm test

# 构建
pnpm build

📄 License

MIT

Name		Name	Last commit message	Last commit date
Latest commit History 51 Commits
.github/workflows		.github/workflows
demo		demo
docs		docs
src		src
.eslintrc.cjs		.eslintrc.cjs
.gitignore		.gitignore
.prettierrc		.prettierrc
AGENTS.md		AGENTS.md
CLAUDE.md		CLAUDE.md
LICENSE		LICENSE
README.en.md		README.en.md
README.md		README.md
package.json		package.json
pnpm-lock.yaml		pnpm-lock.yaml
tsconfig.json		tsconfig.json
vite.config.ts		vite.config.ts
vitest.config.ts		vitest.config.ts

License

maliang/vschema-ui

Folders and files

Latest commit

History

Repository files navigation