form-schema-renderer

form-schema-renderer

一个 Vue 3 组件库，支持 JSON Schema 表单渲染和可视化表单设计器。

A Vue 3 component library that supports JSON Schema form rendering and a visual form designer.

✨ 特性 / Features

• 📋 JSON Schema 自动渲染表单 — 根据 JSON Schema 配置自动生成表单
• 🎨 可视化表单设计器 — 拖拽排序、属性配置，所见即所得
• 🔀 条件可见逻辑（visibleIf） — 支持 equals/notEquals/exists/greaterThan/lessThan/greaterThanOrEqual/lessThanOrEqual 操作符
• 🔗 逻辑组合 — 支持 allOf（全部满足）/ anyOf（任一满足）组合条件
• 🌍 多语言支持 — 内置中/英文，标签和描述支持 { zh, en } 对象格式
• 🧩 自定义 Widget — input / textarea / number / select / checkbox / date / file / rich-text
• ✅ AJV Schema 验证 — 基于 ajv 的实时表单验证
• 📁 文件上传支持 — 内置文件选择与上传处理
• 🔄 设计配置自动转换 — configToSchema() 将设计器配置自动转换为标准 JSON Schema

📦 安装 / Install

npm install form-schema-renderer

Peer Dependencies

ajv 已内置为库依赖，无需业务侧单独安装。

🚀 快速使用 / Quick Start

渲染模式 / Render Mode

通过 JSON Schema 配置自动渲染表单：

<script setup lang="ts">
import { ref } from 'vue'
import { FormRenderer } from 'form-schema-renderer'
import 'form-schema-renderer/style.css'

const schema = ref({
  type: 'object',
  properties: {
    name: { type: 'string', title: '姓名' },
    age: { type: 'number', title: '年龄' }
  }
})
const formData = ref({})
</script>

<template>
  <FormRenderer :schema="schema" v-model="formData" />
</template>

设计器模式 / Designer Mode

可视化拖拽设计表单，自动生成 JSON Schema：

<script setup lang="ts">
import { ref } from 'vue'
import { FormRenderer, configToSchema } from 'form-schema-renderer'
import type { FormDesignConfig } from 'form-schema-renderer'

const designConfig = ref<FormDesignConfig>({ fields: [] })

// Convert design config to JSON Schema
const { schema, uiSchema } = configToSchema(designConfig.value)
</script>

<template>
  <FormRenderer mode="design" v-model:designConfig="designConfig" />
</template>

独立使用设计器 / Standalone Designer

<script setup lang="ts">
import { ref } from 'vue'
import { FormDesigner } from 'form-schema-renderer'
import type { FormDesignConfig } from 'form-schema-renderer'

const config = ref<FormDesignConfig>({ fields: [] })
</script>

<template>
  <FormDesigner v-model="config" />
</template>

📖 API 参考 / API Reference

FormRenderer Props

FormRenderer Events

🎨 设计器配置格式 / Designer Config

FormDesignConfig

interface FormDesignConfig {
  title?: string | { zh: string; en: string }  // Form title
  fields: FormFieldConfig[]                      // Field list
}

FormFieldConfig

FieldOption

interface FieldOption {
  label: string | { zh: string; en: string }
  value: string | number
}

🔀 条件可见 / Conditional Visibility

通过 visibleIf 配置字段的条件显示逻辑。

支持的操作符 / Supported Operators

逻辑组合 / Logic Combination

使用 allOf（所有条件满足）或 anyOf（任一条件满足）组合多个条件：

{
  "visibleIf": {
    "logic": "allOf",
    "conditions": [
      { "field": "gender", "operator": "equals", "value": "Male" },
      { "field": "age", "operator": "greaterThanOrEqual", "value": 18 }
    ]
  }
}

📤 导出 / Exports

// Components
export { FormRenderer } from 'form-schema-renderer'
export { FormDesigner } from 'form-schema-renderer'

// Utilities
export { configToSchema } from 'form-schema-renderer'

// Types
export type { FormDesignConfig, FormFieldConfig, FieldOption, VisibleIfCondition, VisibleIfRule, SchemaConvertResult } from 'form-schema-renderer'

🛠 开发 / Development

# Install dependencies
npm install

# Development mode
npm run dev

# Demo site (port 5173)
npm run dev:demo

# Build library
npm run build

# Build demo site
npm run build:demo

# Run tests
npm run test

🔧 技术栈 / Tech Stack

• Vue 3 — Composition API + <script setup>
• TypeScript — 类型安全
• Vite — 构建工具
• Naive UI — 表单组件库
• AJV — JSON Schema 验证
• vuedraggable — 拖拽排序

📄 License

MIT