FormX

中文 | English

文档站 | GitHub | npm packages

FormX 是一个面向复杂业务系统的 Headless 动态表单引擎。它把“表单逻辑”和“界面渲染”拆开：核心包只负责 schema、联动规则、校验、远程资源、路径解析和状态计算；UI 包再把这些状态转换成框架无关的视图模型；最后由 Vue、React 或具体组件库皮肤负责渲染。

它适合那些普通表单库很难维护的场景：多层对象、对象数组、字段组、复杂联动、动态显隐、动态必填、远程选项、运行时 schema patch、异步校验、设计器生成 JSON 配置等。

为什么做 FormX

很多后台和低代码系统的表单最终会变成“逻辑写在组件里、联动散落在 watch 里、校验和 UI 强绑定”的结构。FormX 的目标是让表单变成一份可保存、可审查、可复用、可由设计器生成的 JSON DSL，同时保留足够强的运行时能力。

核心原则：

• Headless first：核心引擎不依赖 Vue、React、Element Plus 或业务项目 i18n。
• JSON driven：字段、布局、联动、校验、资源请求都可以由 JSON schema 描述。
• 复杂联动可维护：支持 rulesV2、showWhen、requiredWhen、optionsFrom、compute 等规则形态。
• UI 可替换：同一套 engine 可以接 Element Plus、Ant Design、React、自定义组件或设计器预览。
• 发布包边界清晰：不同使用者可以只安装核心引擎，也可以安装完整 Vue + Element Plus 套餐。

包结构

@formxjs/core
  -> @formxjs/ui-core
    -> @formxjs/vue-core
      -> @formxjs/vue-ep
        -> @formxjs/vue

包	定位
@formxjs/core	纯逻辑引擎：schema、规则编译执行、校验、资源、路径、表达式、诊断。
@formxjs/ui-core	框架无关 UI 协议：FormView、FieldView、容器视图、字段组命令。
@formxjs/vue-core	Vue 运行时桥接：响应式 engine/view 状态、composables、暴露 API。
@formxjs/vue-ep	Vue + Element Plus 皮肤：字段渲染、容器渲染、样式。
@formxjs/vue	Vue 默认入口：重导出常用 engine、类型、Vue runtime 和 EP 皮肤。

快速开始

pnpm add @formxjs/vue vue element-plus

import { FormX, FormXEngine } from '@formxjs/vue'
import '@formxjs/vue-ep/style.css'

const schema = {
  version: '1.0.0',
  model: { name: '', status: 'active' },
  fields: [
    {
      id: 'name',
      type: 'input',
      label: 'Name',
      props: { placeholder: 'Enter a name' },
      rules: [{ required: true, message: 'Name is required' }]
    },
    {
      id: 'status',
      type: 'select',
      label: 'Status',
      props: {
        options: [
          { label: 'Active', value: 'active' },
          { label: 'Paused', value: 'paused' }
        ]
      }
    }
  ]
}

const engine = new FormXEngine({ schema })

<template>
  <FormX :schema="schema" :engine="engine" />
</template>

单独使用核心引擎

import { FormXEngine } from '@formxjs/core'

const engine = new FormXEngine({ schema })
engine.dispatch('init')
engine.setValue('name', 'Ada')

const ok = await engine.validate()
const values = engine.getValues()
const errors = engine.getErrors()

@formxjs/core 可以在 Node、浏览器、设计器、测试环境或任意前端框架中使用。

开发

pnpm install
pnpm test
pnpm typecheck
pnpm build
pnpm dev
pnpm docs:dev
pnpm docs:build

示例项目：

pnpm --filter @formxjs/example-vue-ep-basic dev

@formxjs/example-vue-ep-basic 目前是一个 Vue + Element Plus Workbench，不再只是三五个字段的入门页。它包含多份接近真实后台业务的复杂 schema，并补充了远程资源 mock、校验策略切换、实时模型/错误/状态/诊断面板，覆盖全量控件、连接配置、数据保护策略、深层联动、权限矩阵、optionsFrom 和运行时 setOptions 等场景。

文档站：

pnpm docs:dev
pnpm docs:build

docs/ 是 VitePress 文档站，包含中英文介绍和可直接运行的 FormX 示例：基础表单、联动、远程选项、字段组、校验和纯核心引擎。示例代码使用公开包名和通用演示数据，方便用户直接理解和验证 FormX 的运行方式。

npm 包发布和 GitHub Pages 文档部署见 PUBLISHING.md。

当前状态

FormX 目前处于开源仓库抽离和 npm 发布准备阶段。核心引擎、UI 协议、Vue runtime、Element Plus 皮肤已经拆包；后续重点会放在测试覆盖、文档完善、更多示例、发布流水线和设计器集成。

---

English

Documentation | GitHub | npm packages

FormX is a headless dynamic form engine for complex business applications. It separates form logic from UI rendering: the core package owns schema parsing, rule execution, validation, remote resources, path resolution, and state calculation; UI packages convert that state into framework-neutral view models; renderer packages then bind those view models to Vue, React, or specific component libraries.

FormX is designed for forms that quickly outgrow simple field configuration: nested objects, arrays of objects, field groups, conditional visibility, dynamic required state, remote options, runtime schema patches, async validation, and JSON generated by visual designers.

Why FormX

In many admin systems and low-code platforms, form logic eventually spreads across component state, watchers, validators, and UI-specific code. FormX keeps the form behavior in a JSON DSL that can be stored, reviewed, reused, generated by a designer, and rendered by different UI stacks.

Core principles:

• Headless first: the engine does not depend on Vue, React, Element Plus, or app-level i18n.
• JSON driven: fields, layout, linkage, validation, and resources can be described by schema.
• Maintainable complex linkage: supports rulesV2, showWhen, requiredWhen, optionsFrom, compute, and more.
• Replaceable UI: the same engine can power Element Plus, Ant Design, React, custom renderers, or designer previews.
• Clear package boundaries: users can install only the engine or the full Vue + Element Plus stack.

Packages

@formxjs/core
  -> @formxjs/ui-core
    -> @formxjs/vue-core
      -> @formxjs/vue-ep
        -> @formxjs/vue

Package	Role
@formxjs/core	Headless engine: schema, rules, validation, resources, paths, expressions, diagnostics.
@formxjs/ui-core	Framework-neutral UI protocol: FormView, FieldView, containers, field-group commands.
@formxjs/vue-core	Vue runtime bridge: reactive engine/view state, composables, exposed APIs.
@formxjs/vue-ep	Vue + Element Plus skin: field rendering, container rendering, styles.
@formxjs/vue	Default Vue entry that re-exports the common engine, types, runtime, and EP skin.

Quick Start

pnpm add @formxjs/vue vue element-plus

import { FormX, FormXEngine } from '@formxjs/vue'
import '@formxjs/vue-ep/style.css'

const schema = {
  version: '1.0.0',
  model: { name: '' },
  fields: [
    { id: 'name', type: 'input', label: 'Name', rules: [{ required: true }] }
  ]
}

const engine = new FormXEngine({ schema })

<template>
  <FormX :schema="schema" :engine="engine" />
</template>

Development

pnpm install
pnpm test
pnpm typecheck
pnpm build
pnpm dev
pnpm docs:dev
pnpm docs:build

Example project:

pnpm --filter @formxjs/example-vue-ep-basic dev

@formxjs/example-vue-ep-basic is now a Vue + Element Plus workbench instead of a minimal starter form. It includes multiple complex schemas modeled after realistic admin workflows and adds mocked remote resources, validation policy controls, and live values/errors/state/diagnostics inspectors. It covers the full component showcase, connection configuration, data protection policy, deep linkage, permission matrix, optionsFrom, and runtime setOptions scenarios.

Documentation site:

pnpm docs:dev
pnpm docs:build

docs/ is a VitePress site with bilingual introductions and runnable FormX examples for basic forms, linkage, remote options, field groups, validation, and the headless core engine. The examples use public package names and generic demo data so users can understand and verify FormX directly.

See PUBLISHING.md for npm publishing and GitHub Pages deployment.

FormX is currently being prepared for open-source release and npm publishing. The package split is in place; the next work areas are tests, documentation, examples, publishing automation, and designer integration.