agilebuilder-form

English | 简体中文

🎨 一个可嵌入任意 Vue3 应用的 Schema 驱动可视化表单构建器

最新版本 v1.0.2 - Schema 驱动的低代码表单解决方案

📖 目录

• 简介
• 核心特性
• 安装
• 快速开始
• 核心概念
• API 文档
• 内置控件
• 自定义控件
• 项目结构
• 开发指南
• 许可证

📝 简介

agilebuilder-form 是一个基于 Vue 3 和 TypeScript 开发的低代码表单构建器，采用 Schema 驱动的设计理念。它提供了可视化的表单设计器和运行时渲染器，让您可以通过拖拽的方式快速构建复杂表单，并将表单结构序列化为 JSON Schema 进行存储和传输。

适用场景

• 🏢 企业级应用：快速构建各类业务表单
• 📋 问卷调查：可视化设计调查问卷
• 🔧 配置管理：动态表单配置系统
• 📊 数据采集：灵活的数据收集工具

核心架构

三大核心模块

• FormDesigner：可视化设计器（左侧控件栏 + 中间画布 + 右侧配置面板）
• FormRuntime：运行态渲染器（根据 Schema 渲染真实表单 + FormData 收集）
• SchemaEngine：核心数据引擎（统一管理 FormSchema 结构）

完整数据流

ControlMeta → initialSchema() → SchemaNode → FormSchema → Designer/Runtime → FormData

✨ 核心特性

• 📦 开箱即用：内置 11 种基础控件，快速搭建表单
• 🎨 可视化设计：左中右三栏布局，拖拽式操作
• 🚀 Schema 驱动：JSON 描述表单结构，易于存储和传输
• 🔌 高度可扩展：插件化控件体系，规范化的扩展接口
• 💪 TypeScript：核心引擎层完整类型支持
• ⚡️ 响应式：基于 Vue3 响应式系统，数据变化自动更新
• 📊 FormData 收集：运行态支持 v-model，实时收集表单数据
• 🎯 表单级配置：支持标题、主题、描述等表单级信息
• 🌍 国际化支持：内置中英文语言包，支持自定义语言
• 🎭 主题定制：支持运行时动态主题切换

🚀 安装

NPM

npm install agilebuilder-form

Yarn

yarn add agilebuilder-form

PNPM

pnpm add agilebuilder-form

依赖要求

• Vue: ^3.5.0
• Element Plus: ^2.11.7
• Node.js: ^20.19.0 || >=22.12.0

🎯 快速开始

1. 安装依赖

npm install agilebuilder-form element-plus vue@^3.5.0

2. 引入样式

import 'element-plus/dist/index.css'
import 'agilebuilder-form/dist/ag-form.css'

3. 基础使用示例

<template>
  <div>
    <!-- 设计器 -->
    <FormDesigner :engine="engine" />
    
    <!-- 运行态（支持 v-model）-->
    <FormRuntime 
      :schema="engine.getSchema()" 
      v-model="formData"
    />
    
    <!-- 查看收集到的数据 -->
    <pre>{{ formData }}</pre>
  </div>
</template>

<script setup lang="ts">
import { ref } from 'vue'
import { 
  SchemaEngine, 
  FormDesigner, 
  FormRuntime, 
  registerBuiltinControls,
  type FormData
} from 'agilebuilder-form'
import 'element-plus/dist/index.css'
import 'agilebuilder-form/dist/ag-form.css'

// 注册内置控件
registerBuiltinControls()

// 创建引擎实例
const engine = new SchemaEngine()

// 配置表单信息
engine.updateInfo({
  title: '用户注册表单',
  theme: 'light',
  description: '请填写您的注册信息'
})

// FormData（自动收集）
const formData = ref<FormData>({})
</script>

📐 核心概念

FormSchema（表单结构）

FormSchema 是表单的完整数据结构，包含表单信息和控件树。

interface FormSchema {
  info: {
    title: string        // 表单标题
    theme: string        // 主题（light/dark）
    description?: string // 表单说明
    version?: string     // 版本号
  }
  controls: SchemaNode[]  // 控件树
}

SchemaNode（控件节点）

SchemaNode 描述单个控件的结构。

interface SchemaNode {
  id: string                  // 唯一 ID
  type: string                // 控件类型
  field?: string              // 字段名（用于 FormData）
  props: Record<string, any>  // 控件属性
  style?: Record<string, any> // 控件样式
  children?: SchemaNode[]     // 子节点（容器控件）
}

FormData（表单数据）

FormData 是用户填写的表单数据，以键值对形式存储。

type FormData = Record<string, any>

// 示例
{
  "username": "张三",
  "email": "[email protected]",
  "age": 25,
  "gender": "male"
}

📚 API 文档

核心引擎

SchemaEngine

表单 Schema 的核心引擎类，负责管理表单结构和状态。

class SchemaEngine {
  // 构造函数
  constructor(initialSchema?: FormSchema)
  
  // 获取完整 Schema
  getSchema(): FormSchema
  
  // 更新表单信息
  updateInfo(info: Partial<FormInfo>): void
  
  // 添加节点
  addNode(parentId: string | null, node: SchemaNode, index?: number): boolean
  
  // 更新节点
  updateNode(id: string, updates: Partial<SchemaNode>): boolean
  
  // 删除节点
  removeNode(id: string): boolean
  
  // 移动节点
  moveNode(id: string, targetParentId: string | null, index?: number): boolean
  
  // 查找节点
  findNode(id: string): SchemaNode | null
  
  // 清空表单
  clear(): void
  
  // 事件监听
  on<K extends keyof EngineEvents>(event: K, handler: Function): void
  off<K extends keyof EngineEvents>(event: K, handler: Function): void
}

使用示例：

import { SchemaEngine } from 'agilebuilder-form'

const engine = new SchemaEngine()

// 更新表单信息
engine.updateInfo({
  title: '我的表单',
  theme: 'light'
})

// 添加控件
engine.addNode(null, {
  id: 'input_1',
  type: 'input',
  field: 'username',
  props: { label: '用户名', placeholder: '请输入用户名' }
})

// 监听变化
engine.on('node:added', (payload) => {
  console.log('节点已添加:', payload)
})

UI 组件

FormDesigner

可视化表单设计器组件。

Props:

• engine (SchemaEngine, 必填): Schema 引擎实例
• showControlTabs (boolean, 可选, 默认: true): 是否显示左侧控件分类标签

<FormDesigner 
  :engine="engine" 
  :showControlTabs="true"
/>

FormRuntime

表单运行时渲染器组件。

Props:

• schema (FormSchema, 必填): 表单 Schema
• modelValue (FormData, 可选): 表单数据（支持 v-model）

Events:

• update:modelValue: 表单数据更新事件

<FormRuntime 
  :schema="engine.getSchema()" 
  v-model="formData"
/>

控件注册

registry

全局控件注册中心。

// 注册单个控件
registry.register(controlMeta)

// 批量注册
registry.registerAll([control1, control2])

// 替换所有控件
registry.replaceAll([control1, control2])

// 获取控件
const control = registry.get('input')

// 获取所有控件
const allControls = registry.getAll()

// 检查控件是否存在
const exists = registry.has('input')

registerBuiltinControls()

注册所有内置控件的便捷函数。

import { registerBuiltinControls } from 'agilebuilder-form'

registerBuiltinControls()

useControl()

控件操作的 Hook 函数。

import { useControl } from 'agilebuilder-form'

const { register, get, getAll, has } = useControl()

Schema 工具函数

serialize()

将 FormSchema 序列化为 JSON 字符串。

import { serialize } from 'agilebuilder-form'

const jsonString = serialize(schema)

hydrate()

从 JSON 字符串还原 FormSchema。

import { hydrate } from 'agilebuilder-form'

const schema = hydrate(jsonString)

createEmptySchema()

创建空的 FormSchema。

import { createEmptySchema } from 'agilebuilder-form'

const emptySchema = createEmptySchema()

createSampleSchema()

创建示例 FormSchema。

import { createSampleSchema } from 'agilebuilder-form'

const sampleSchema = createSampleSchema()

国际化

setLocale()

设置当前语言。

import { setLocale } from 'agilebuilder-form'

setLocale('en') // 切换到英文
setLocale('zh-CN') // 切换到中文

getLocale()

获取当前语言。

import { getLocale } from 'agilebuilder-form'

const currentLocale = getLocale() // 'zh-CN'

t()

翻译函数。

import { t } from 'agilebuilder-form'

const text = t('designer.controlPanel.title') // '控件面板'

主题定制

setRuntimeThemeStyles()

设置运行时主题样式。

import { setRuntimeThemeStyles } from 'agilebuilder-form'

setRuntimeThemeStyles({
  '--ag-form-primary-color': '#409eff',
  '--ag-form-border-radius': '4px'
})

resetRuntimeThemeStyles()

重置运行时主题样式。

import { resetRuntimeThemeStyles } from 'agilebuilder-form'

resetRuntimeThemeStyles()

🎨 内置控件

输入控件 (inputControl)

| 控件 | 类型 | 说明 | 主要属性 | |------|------|------|----------| | input | 输入框 | 单行文本输入 | label, placeholder, maxlength, clearable | | textarea | 多行输入 | 多行文本输入 | label, placeholder, rows, maxlength | | number | 数字输入 | 数字输入框 | label, min, max, step, precision | | select | 下拉选择 | 下拉选择器 | label, options, multiple, clearable | | radio | 单选框 | 单选框组 | label, options | | checkbox | 多选框 | 多选框组 | label, options | | date | 日期选择 | 日期选择器 | label, format, valueFormat, type | | time | 时间选择 | 时间选择器 | label, format, isRange | | switch | 开关 | 开关控件 | label, activeText, inactiveText |

布局控件 (layoutControl)

| 控件 | 类型 | 说明 | 主要属性 | |------|------|------|----------| | row | 横向布局 | 横向布局容器 | gutter, justify, align |

静态展示 (staticControl)

| 控件 | 类型 | 说明 | 主要属性 | |------|------|------|----------| | text | 静态文本 | 纯文本展示 | content, fontSize, color |

🔧 自定义控件

控件结构

一个完整的自定义控件需要包含 4 个文件：

your-control/
├── runtime.vue      # 运行态组件（支持 v-model）
├── designer.vue     # 设计态组件（可选中）
├── config.vue       # 配置面板组件
└── export.ts        # 导出 ControlMeta

ControlMeta 定义

import type { ControlMeta, SchemaNode } from 'agilebuilder-form'

export const yourControl: ControlMeta = {
  type: 'your-type',           // 控件类型（唯一标识）
  category: 'inputControl',    // 控件分类
  label: '你的控件',            // 显示名称
  icon: 'Edit',                // 图标（Element Plus 图标名）
  isContainer: false,          // 是否为容器控件
  
  // 初始化 Schema
  initialSchema: (): SchemaNode => ({
    id: `your_${Date.now()}`,
    type: 'your-type',
    field: 'yourField',        // 如果是输入控件
    props: {
      label: '标签',
      placeholder: '请输入'
    }
  }),
  
  // 组件引用
  designer: YourDesigner,      // 设计态组件
  runtime: YourRuntime,        // 运行态组件
  config: YourConfig,          // 配置面板组件
  
  // 国际化（可选）
  locales: {
    'zh-CN': {
      'controls.yourType.label': '你的控件'
    },
    'en': {
      'controls.yourType.label': 'Your Control'
    }
  }
}

注册自定义控件

import { registry } from 'agilebuilder-form'
import { yourControl } from './your-control/export'

// 注册单个控件
registry.register(yourControl)

// 或批量注册
registry.registerAll([yourControl, anotherControl])

详见 控件开发指南

📁 项目结构

src/
├── core/                      # 核心引擎层（不依赖 UI）
│   ├── schema/               # Schema 数据引擎
│   │   ├── types.ts          # FormSchema, SchemaNode, FormData
│   │   ├── engine.ts         # SchemaEngine 核心类
│   │   ├── ops.ts            # add/update/remove 操作
│   │   ├── io.ts             # serialize/hydrate
│   │   ├── finder.ts         # 节点查找工具
│   │   └── validator.ts      # 数据校验
│   ├── registry/             # 控件注册中心
│   │   ├── types.ts          # ControlMeta, ControlCategory
│   │   ├── index.ts          # registry 单例
│   │   └── i18n.ts           # 国际化注册
│   ├── events/               # 事件系统
│   ├── history/              # 历史记录（撤销/重做）
│   ├── theme/                # 主题系统
│   └── utils/                # 工具函数
├── designer/                 # 设计器 UI（左中右布局）
│   ├── DesignerShell.vue     # 设计器外壳
│   ├── ControlPanel.vue      # 左侧控件面板
│   ├── CanvasView.vue        # 中间画布
│   ├── ConfigPanel.vue       # 右侧配置面板
│   └── FormConfigPanel.vue   # 表单配置面板
├── runtime/                  # 运行态 UI（支持 FormData）
│   ├── index.vue             # 运行态主容器
│   └── RenderRuntimeNode.vue # 节点渲染器
├── components/               # 组件库
│   ├── controls-common/      # 通用配置组件
│   │   ├── config-common/    # 配置组件
│   │   └── form-common/      # 表单组件
│   └── controls/             # 内置控件
│       ├── input/            # 输入框
│       ├── textarea/         # 多行输入
│       ├── number/           # 数字输入
│       ├── select/           # 下拉选择
│       ├── radio/            # 单选框
│       ├── checkbox/         # 多选框
│       ├── date/             # 日期选择
│       ├── time/             # 时间选择
│       ├── switch/           # 开关
│       ├── row/              # 横向布局
│       └── text/             # 静态文本
├── i18n/                     # 国际化
│   └── locales/              # 语言包
│       ├── zh-CN.ts          # 中文
│       └── en.ts             # 英文
├── styles/                   # 样式文件
└── types/                    # TypeScript 类型定义

🛠️ 开发指南

本地开发

# 克隆项目
git clone https://github.com/mexhfl/agilebuilder-form.git

# 安装依赖
npm install

# 启动开发服务器
npm run dev

# 访问 http://localhost:5174

构建

# 构建生产版本
npm run build

# 类型检查
npm run type-check

# 构建并检查类型
npm run build-with-check

测试

# 运行测试
npm test

发布到 NPM

# 1. 更新版本号
npm version patch  # 或 minor, major

# 2. 构建
npm run build

# 3. 登录 npm
npm login

# 4. 发布
npm publish

📖 相关文档

使用文档

• 组件库使用文档 - 如何在项目中使用
• NPM 发布指南 - 发布流程说明
• 快速发布指南 - 3分钟快速发布

开发文档

• 架构设计文档 - 深入理解系统架构
• 控件开发指南 - 如何开发自定义控件
• 容器控件指南 - 容器控件开发
• 国际化架构 - 国际化系统设计
• 国际化使用 - 国际化使用指南
• 运行时主题 - 主题定制指南

其他文档

• 重构完成报告 - v2.0 变化说明
• MVP 功能说明 - 详细功能介绍
• 项目清单 - 完成度统计

📖 查看所有文档

🎓 技术栈

• Vue 3 - 渐进式 JavaScript 框架
• TypeScript - JavaScript 的超集
• Element Plus - Vue 3 组件库
• Vite - 下一代前端构建工具
• Vue I18n - Vue 国际化插件
• Mitt - 事件总线
• Lodash-ES - 工具函数库

🤝 贡献

欢迎贡献代码、报告问题或提出建议！

1. Fork 本仓库
2. 创建特性分支 (git checkout -b feature/AmazingFeature)
3. 提交更改 (git commit -m 'Add some AmazingFeature')
4. 推送到分支 (git push origin feature/AmazingFeature)
5. 开启 Pull Request

📄 许可证

本项目基于 MIT 许可证开源。

Copyright (c) 2025 ag-form Contributors

🔗 链接

• NPM 包
• GitHub 仓库
• 问题反馈
• 更新日志

Made with ❤️ by ag-form team