@wenext/schema-form 重构实践
1. 背景
原实现名为 @wenext/json-form,入口同时包含:
- JSON Forms Vue 适配
- Element Plus renderer
- Tailwind 和 Element Plus 样式
- 图片上传
- 多语言编辑和翻译
- ZIP 资源解析
- 颜色选择器
- 与特定业务平台相关的文案和接口上下文
这种结构可以服务一个固定业务,但会带来三个问题:
- “通用 JSON Form”与实际的业务表单能力不匹配。
- 核心入口会静态引入所有 UI 和业务扩展。
- 业务工具接口、UI 控件和 JSON Forms 生命周期相互耦合。
本次重构将包名调整为 @wenext/schema-form,保留单 npm 包,通过 package.exports 实现分层加载。
2. 目标架构
@wenext/schema-form
├── core
│ ├── SchemaForm
│ ├── JSON Schema / UI Schema 类型
│ ├── vanillaRenderers 默认注册
│ ├── renderer 注册
│ ├── 校验配置
│ └── 数据变更事件
│
└── element-plus
├── basic
│ ├── Input
│ ├── Select
│ ├── Checkbox
│ ├── Slider
│ ├── Group
│ ├── Flow
│ └── Array
│
└── advanced
├── ColorPicker
├── Upload
└── MultiLangInput这里没有拆分成多个 npm 包,原因是这些能力属于同一套 Schema Form 体系;但核心、基础控件和高阶控件拥有独立入口。SchemaForm 默认合并 vanillaRenderers 与调用方传入的 Element Plus renderer,覆盖旧包的默认行为。
3. 入口约定
| 入口 | 职责 | 是否引入 Element Plus |
|---|---|---|
@wenext/schema-form | core 默认入口 | 否 |
@wenext/schema-form/core | core 显式入口 | 否 |
@wenext/schema-form/element-plus | 基础 + 高阶控件 | 是 |
@wenext/schema-form/element-plus/basic | 基础控件 | 是 |
@wenext/schema-form/element-plus/advanced | 高阶控件 | 是 |
根入口不引入 Element Plus,但会提供 JSON Forms vanilla renderer。用户需要显式选择 Element Plus renderer:
import { SchemaForm } from '@wenext/schema-form'
import { elementPlusRenderers } from '@wenext/schema-form/element-plus'这样未被 Element Plus 覆盖的 Schema 控件仍有 vanilla fallback,同时不会加载 Element Plus、颜色选择器和上传控件。
4. 核心数据流
用户操作
↓
Element Plus renderer
↓
useJsonFormsControl / useJsonFormsArrayControl
↓
handleChange(path, value)
↓
JsonForms change
↓
SchemaForm update:modelValue控件不得直接修改 control.data 或外部 modelValue。
本次同时修复了原输入控件使用初始化快照的问题:输入值改为由当前 control 数据驱动,外部 model 更新能够重新反映到控件。
5. 高阶控件原则
颜色选择器、多语言输入、上传控件属于基于 Element Plus 的高阶通用控件,不放入 core,也不绑定 Wenext 平台接口。
它们只定义 adapter contract,由宿主项目通过 SchemaForm.services 提供实现。
上传
interface UploadAdapter {
upload(file: File | Blob): Promise<{ url: string }>
}翻译
interface TranslationAdapter {
translate(options: {
sourceText: string
sourceLang: string
targetLangs: string[]
// Legacy aliases are also supplied during migration.
langs?: string[]
text?: string
}): Promise<Record<string, string>>
}ZIP 解析
interface ArchiveAdapter {
extract(file: File): Promise<Map<string, File>>
}控件只负责交互和表单值转换,不负责 adapter 的网络请求、文件解析或平台鉴权。
多语言控件优先从 UI Schema options 读取 langOptions、defaultRequiredLang 和 inputAttrs;为兼容旧包,也会回退读取 SchemaForm.config.langOptions。翻译和文本解析仍通过 adapter 注入。
const config = {
langOptions: [
{ label: 'English', value: 'en' },
{ label: '简体中文', value: 'zh-CN' },
],
}6. 依赖策略
peerDependencies
以下依赖需要与宿主共享实例:
vue@jsonforms/core@jsonforms/vue@jsonforms/vue-vanillaelement-plus@element-plus/icons-vuevue3-colorpicker(仅 advanced 能力需要)
Element Plus 及高阶控件依赖标记为 optional peer,保证 core 用户不会被强制安装 UI 依赖。
devDependencies
Vite、Vue 编译插件、TypeScript、类型生成工具以及 Element Plus/高阶控件的开发依赖只用于构建和类型检查,不会被打入 runtime dependencies。
已移除的耦合
@jsonforms/vue-vanilla:作为 core 的必要 peer,提供旧包默认的 vanilla fallback- 颜色选择器统一使用
vue3-colorpicker,支持纯色和渐变色;作为 advanced entry 的可选 peer dependency dayjs/maska/ 自定义 AJV 工具:不再进入当前发布入口- Tailwind UI 实现:按旧包保留,用于维持控件和布局的既有视觉样式
- OSS、翻译、ZIP 的具体实现:改为外部 adapter
7. 样式策略
core 不导入 CSS。
Element Plus 层输出自身及高阶颜色控件所需的局部样式,并由宿主显式引入:
import 'element-plus/dist/index.css'
import '@wenext/schema-form/element-plus/styles.css'Element Plus 基础样式由宿主项目负责,避免组件包重复打包完整 Element Plus CSS。 颜色选择器样式会随 element-plus/styles.css 一起输出;宿主仍需安装 vue3-colorpicker,但不需要额外手动引入其 CSS。
8. 构建与发布检查
本包使用多入口构建:
pnpm typecheck
pnpm build
npm pack --dry-run --ignore-scripts验收重点:
- 根入口不包含 Element Plus 和 advanced 控件代码。
element-plus/basic不依赖颜色选择器和上传 adapter。- advanced 控件只通过 adapter 使用上传、翻译和 ZIP 能力。
- 生成的类型声明与 exports 路径一致。
- 发布包不包含 source map 和旧的 dist 深层路径。
9. 迁移关系
| 原 API | 新 API |
|---|---|
VueFormRender | SchemaForm |
elementPlusRenderers | @wenext/schema-form/element-plus |
OSSContext.upload | UploadAdapter |
ToolsContext.translate | TranslationAdapter |
ToolsContext.unzip | ArchiveAdapter |
mutil-lang-input | MultiLangInput,producer 推荐 multi-lang-input |
旧的 mutil-lang-input producer 名称在 advanced renderer 中暂时保留兼容识别,但新配置应使用 multi-lang-input。