Files
eip4-platform/docs/skills/eip4-amis-pitfalls.md
zhengwr 1eb690124b 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>
2026-06-23 09:50:23 +08:00

60 lines
4.3 KiB
Markdown
Raw Permalink Blame History

This file contains ambiguous Unicode characters
This file contains Unicode characters that might be confused with other characters. If you think that this is intentional, you can safely ignore this warning. Use the Escape button to reveal them.
# 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` + 真渲染**双验证**再收工。