feat(cli): 新增 eip4-amis-pitfalls skill
把散落的 amis 实战坑收敛成「写 amis schema 的 agent」可直接用的规则 + 必实测铁律: 单选 selectedItems 是 Option 对象非数组、树 >100 节点虚拟列表破坏选中、 空列表兜底 items:[]、quickEdit.needConfirm 须显式 false、 行级按钮 dialog 按 name 自动回填同名字段、onEvent 需按钮 id 等。 manifest 登记为第 7 个 skill,由 initInstallsAllBundledSkillsWithoutDrift 守护端到端可装。 Co-Authored-By: Claude Opus 4.8 (1M context) <noreply@anthropic.com>
This commit is contained in:
59
docs/skills/eip4-amis-pitfalls.md
Normal file
59
docs/skills/eip4-amis-pitfalls.md
Normal file
@@ -0,0 +1,59 @@
|
||||
# Skill: eip4-amis-pitfalls
|
||||
|
||||
EIP4 前端用 amis(JSON schema 配置 UI)。本 skill 汇集「写 / 改 amis schema 时会撞、且不真渲染就发现不了」的实战坑。**绝大多数页面由转换器 / recipe 编译器生成**,所以多数修复落在生成逻辑(Java),但症状表现为 amis 行为——下面按 amis 概念分组。
|
||||
|
||||
## 触发场景
|
||||
|
||||
- 生成或手改 amis 页面后:联动失效、选不中、显 id、空列表报错、行内编辑异常。
|
||||
- 在 DesignerPage overlay 或 recipe 模板里调字段 / 事件 / 列。
|
||||
- 排查「功能通了但 UI/UE 不对」。
|
||||
|
||||
## 铁律(先读这条)
|
||||
|
||||
1. **必真渲染实测**:任何 amis 改动都要 vite 反代 + Playwright / 浏览器逐屏看。功能点 e2e(落库 / status)**≠** 视觉 / UE 走查——很多坑只在渲染时暴露。
|
||||
2. **线上 sdk.js 与 amis-fork 源码已漂移**:以实际加载的 sdk 行为为准,别照搬某版源码 API;直接改 sdk 有全站回归险。
|
||||
3. **属性别凭记忆**:amis 属性多且迭代快,查官方文档(context7 / amis.io),别幻觉出不存在的属性或事件名。
|
||||
4. **行为不确定先隔离钉死**:建隔离 `amis.embed` 手写最小 schema 跑真事件,确认机制后再写后端 / 转换器。
|
||||
5. **校验工具**:`POST {{EIP4_BASE_URL}}/api/page/schema/validate`(不写库);`GET {{EIP4_BASE_URL}}/api/page/schema/components` 查注册组件 / 动作(未注册会被 typed 校验拒)。
|
||||
|
||||
## 引用列 / picker / select 联动
|
||||
|
||||
- **picker 显名**:用 form `initApi`(**不要** service 包裹,service 破坏 fetch 时序)+ 引用字段返 `{_id, _label}` 对象(自带 label 不依赖二次拉取)。**禁全局递归 schema filter**(崩过)。
|
||||
- **单选 select 取联动源**:`event.data.selectedItems` 是 **Option 对象,不是数组** → 写 `selectedItems.FIELD`,**别加 `[0]`**(只有多选才是数组)。引用联动 fill 失败,十有八九是这。
|
||||
- 联动 / 校验动作要锚定 `onEvent.actions[]`。
|
||||
- CHAR(36) 外键值常带尾空格 → 匹配不上,要 **trim**。
|
||||
|
||||
## 树(tree / tree-select / treeGrid)
|
||||
|
||||
- **选不中**:>100 节点触发 amis 虚拟列表,`valueSet.has` 走对象身份判断 → 选中 / 高亮失效。设 `virtualThreshold` 关虚拟,或避免一次性渲染大树。
|
||||
- **点一次发两请求**:别同时写 `onEvent.change` 里 reload **和** `api: node=${tree}` 自动重拉,二者叠加双触发;去掉显式 reload。
|
||||
- 加节点用弹窗表单(含多必填列),顶级节点省略 parentid;「加子节点」预填父名要 `canAccessSuperData:false` + 显式传 data。
|
||||
- 树形维护对应实体 type=101 → 用 tree-select + onlyLeaf。
|
||||
|
||||
## CRUD 列表 / 空数据
|
||||
|
||||
- 列表 data 必须是**数组**;后端空结果 `{result:{}}` 要兜底成 `items:[]`,否则 amis 报红横幅 `data.items 必须是数组`。
|
||||
- **别直接绑外键 id 当显示列**(会显裸 id):用计算 / columnsql 显示列,或按列名映射目标表取名(如 DEPARTID→SYS_DEPART、ORGID→SYS_ORG)。
|
||||
- 点整行选中:`checkOnItemClick: true`。
|
||||
|
||||
## 行内编辑 / 主子表
|
||||
|
||||
- `quickEdit.needConfirm` 必须**显式 `false`**——amis 默认会强注一个 confirm 步骤,不写就每格都要点确认。
|
||||
- 派生列公式里的 `|` 会破坏表达式切分;深嵌套表达式可能 StackOverflowError,求值要兜底。
|
||||
- 多行子表用 `${index}` 按行隔离,防字段串台。
|
||||
|
||||
## 对话框 / 表单 / 附件
|
||||
|
||||
- 🔑 **行级按钮打开的 dialog 表单,会按字段 name 自动回填该行同名字段**:命名冲突会意外带入行数据,起名时留意。
|
||||
- 附件双态:只读 / 编辑都用 `input-file` + `staticOn: ${__readonly}`(**别**用 each / service 拼),契约字段 `{id, name, value, url, sizeKb}`;保真层大写 `DOCUMENT` 要归一为 amis 小写。
|
||||
|
||||
## onEvent 事件挂载
|
||||
|
||||
- 要挂事件的工具栏 / 按钮**必须有 id**,否则联动挂不上。
|
||||
- 区分事件类型(`inited` vs `change`),别一把抓全挂。
|
||||
- 联动脚本要覆盖**所有**按钮模式(不只 FULL_AUTO,NO_S3 等也要)。
|
||||
|
||||
## 红线
|
||||
|
||||
- 改 amis 行为前先想清楚改的是「生成逻辑(转换器 / recipe)」还是「单页 overlay」——前者影响全站,必跑回归。
|
||||
- schema 只能用注册过的组件 / 动作;改动后 `validate` + 真渲染**双验证**再收工。
|
||||
@@ -29,6 +29,11 @@
|
||||
"file": "eip4-acl-manage.md",
|
||||
"name": "eip4-acl-manage",
|
||||
"description": "菜单/角色/用户组授权(/api/admin/*)"
|
||||
},
|
||||
{
|
||||
"file": "eip4-amis-pitfalls.md",
|
||||
"name": "eip4-amis-pitfalls",
|
||||
"description": "amis 前端实战坑:引用/树/列表/行内编辑/对话框/事件 + 必实测铁律"
|
||||
}
|
||||
]
|
||||
}
|
||||
|
||||
Reference in New Issue
Block a user