# 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` + 真渲染**双验证**再收工。