aj-form-designer 使用教程
aj-form-designer 是一个面向 View UI Plus 表单的可视化设计器。它专注于表单字段、两列栅格、表单 Schema 和 Vue 单文件组件生成，不覆盖通用页面布局组件。
控件的完整列表见控件配置参考，Schema 字段定义见 FormSchema 参考。需要将生成代码接入已有工程或了解旧格式迁移时，请参阅开发与集成指南。
1. 启动项目
在项目目录执行：
npm install
npm run dev
打开终端提示的本地地址。页面分为三部分：左侧是组件面板，中间是表单画布，右侧是属性面板。
2. 设计一个表单
从左侧展开组件分类，将字段拖到中间画布。
- 根画布可放置字段和“两列栅格”；
- 两列栅格的列内只能放字段；
- 字段或整行可以在画布中重新排序；
- 选中字段后，可用顶部的复制、删除、撤销和重做按钮编辑。
目前支持文本框、数字框、下拉选择、单选组、多选组、日期/时间、开关、滑块、评分、颜色选择和 Button。
3. 配置表单与字段
未选中任何字段时，右侧显示表单整体配置，可修改标签位置与标签宽度。
选中字段后，可配置字段名、显示标签和必填状态。字段名是最终表单数据的键，必须唯一，例如：
name
status
createdAt
不同字段还有专用配置：
Input：单行、多行或密码类型，以及占位提示；DatePicker：日期、日期范围、日期时间和显示格式；Select、RadioGroup、CheckboxGroup：选项列表；- 所有字段：高级 JSON 属性，会作为 View UI Plus 组件 props 保存并传给控件。Button 的点击动作单独保存，不会作为组件 prop 传入。
选择类字段每行一个选项，格式为 标签=值：
草稿=draft
发布=published
数量=number:12
启用=boolean:true
没有类型前缀的值是字符串。number: 和 boolean: 用于确保生成 Schema 后仍保留数值和布尔类型。
4. 配置 Button
Button 只会在画布中出现一次，生成组件也只会生成这一个 Button，不会额外注入固定的提交或重置按钮。
右侧属性面板可选择三种点击行为：
- 普通按钮：仅保留 Button 外观和 View UI Plus props。
- 触发事件：填写事件名，例如
save。生成组件会在点击时调用：
emit("save", formData);
- 自定义 JS：输入点击函数体。可使用
formData、emit和event，例如：
if (!formData.name) {
window.alert("请填写名称");
return;
}
emit("save", formData);
自定义 JS 不会在设计器的预览窗口执行，只会写入下载的 Vue SFC。请只填写可信代码；业务接口请求、路由跳转和权限判断通常更适合由宿主页面监听事件后处理。
5. 表单预览
点击顶部“预览”按钮可以填写当前表单，并使用“校验并查看数据”检查必填字段。校验通过后会显示当前数据 JSON。
预览底部的“重置”和“校验并查看数据”是设计器辅助工具，不会被写进生成组件。
6. Schema 导入、编辑与导出
点击“Schema”可查看和编辑当前 JSON；点击“导入”可以读取本地 .json 文件；点击“导出 Schema”可保存当前设计，之后可再次导入继续编辑。
一个简化的 Schema 示例：
{
"version": 1,
"props": {
"labelPosition": "right",
"labelWidth": 100
},
"items": [
{
"id": "name",
"kind": "field",
"field": "name",
"label": "名称",
"required": true,
"widget": {
"type": "Input",
"props": {
"placeholder": "请输入名称"
}
}
}
]
}
导入时会校验字段名唯一性、支持的组件类型，以及两列栅格必须恰好两列且总宽度为 24。
旧版通用设计器数据也可以导入：工具会迁移可识别的 Form、FormItem、Row、Col 与表单字段；无法安全转换的组件会显示迁移提示。
导入结构、字段默认值和旧版迁移边界见 FormSchema 参考 与开发与集成指南。
7. 生成 Vue 单文件组件
点击“生成 SFC”可查看最终 Vue 3 组件，并下载为 GeneratedForm.vue。
生成代码假定宿主工程已经注册 View UI Plus。若宿主工程采用按需注册，需自行注册 Schema 实际使用的组件，例如 Form、FormItem、Input、Select、Button、Row 和 Col。事件动作会传出当前 formData 的副本。生成的 required 用于表单项的必填标记；当前 SFC 生成器不会生成与设计器预览相同的校验规则或提交/重置按钮。
事件型 Button 的使用示例：
<GeneratedForm @save="saveForm" />
<script setup lang="ts">
function saveForm(formData: Record<string, unknown>): void {
// 调用接口、跳转页面或执行其它业务逻辑
}
</script>
8. 建议的使用方式
将 Schema JSON 保存到业务项目的配置目录，使用设计器持续维护表单；生成 SFC 后纳入业务源码和代码审查。对于接口调用、权限、路由和复杂联动，优先使用 Button 事件交由宿主组件实现，避免将大量业务逻辑直接写入自定义 JS。