外观
新增表单规范
新开发的业务新增表单默认使用 KvFormDrawer,从页面右侧滑出;新增与编辑共用同一表单时统一使用抽屉。开发人员使用 AI 时,只需描述业务字段和逻辑,无需反复指定容器。
用户明确指定其他形式或已有明确设计要求时,按要求实现并记录例外原因。删除确认、操作确认、消息提示、登录/注册页面和导航抽屉不属于此规则。历史业务表单在明确的迁移任务中逐步调整。
AI 规则如何生效
模板包含 AGENTS.md、.agents/skills/kevairy-ui/SKILL.md 和其 references/form-drawer.md。根指南提供默认规则,Skill 提供实现步骤和示例入口;它们跟随代码进入生成项目。
Codex 使用仓库的 AGENTS.md 作为项目指导。团队使用其他 AI 工具时,应在该工具支持的项目规则入口引用这些文件,并验证实际加载情况,不要假定所有工具都会自动读取它们。详细规范保留一份,通过引用维护。
规则提供开发指导,代码审查负责确认执行。本阶段不新增自动识别业务表单的 CI 拦截规则;后续可在明确检查范围和历史例外后接入。
标准实现
运行模板后访问 /examples/crud-workspace。对应源码 src/views/examples/crud-workspace/index.vue 展示新增、编辑、初始快照、修改检测、校验、提交锁定、保存成功关闭和列表刷新。
- 复用与
KvDrawer一致的标题和底部操作区。默认mode="drawer",宽度 720px;复杂工作台显式使用mode="page"占满菜单旁的内容区,小屏自动全宽;只有明确需要自定义宽度时才传size。 - 页面负责表单字段、校验、权限、详情加载、请求和错误提示;组件负责容器、标准按钮与关闭保护。
- 提交开始时同步锁定,finally 恢复;失败保留输入,成功关闭并刷新列表。
- 每次打开建立初始快照,计算
dirty。关闭动画完成后重置字段和校验,避免旧数据残留。
Props、Slots、Events 和实例方法统一以 KvFormDrawer API 为准。历史 KvDialog 表单不作为新功能的默认示例。
交付与审查
- 未指定容器的新业务新增表单使用
KvFormDrawer;其他形式有明确用户要求或设计依据。 - 验证必填校验、提交期间防重复操作、保存成功刷新、保存失败保留输入。
- 验证点击外部遮罩默认可关闭;有修改时取消、关闭按钮、遮罩和 Esc 均提示确认;“继续编辑”保留数据,“放弃修改”后再次打开没有残留,提交期间不能关闭。
- 验证桌面从右侧打开、小屏全宽、长表单独立滚动且操作区可见。
在新会话中仅输入“新增一个用户表单”,检查 AI 是否读取规则并默认选择 KvFormDrawer。若未生效,先检查工具规则入口、指令覆盖和当前依赖是否包含该组件。
模板分发
源仓库修改 apps/template 的规则、Skill 和示例后,通过同步脚本生成发布快照。包含本组件的版本发布前,先为组件分配新版本并发布,再同步和发布依赖该版本的模板;不要将使用新 API 的模板指向尚未包含该 API 的旧组件版本。维护流程见同步脚手架模板。