把散落的 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>
4.3 KiB
4.3 KiB
Skill: eip4-amis-pitfalls
EIP4 前端用 amis(JSON schema 配置 UI)。本 skill 汇集「写 / 改 amis schema 时会撞、且不真渲染就发现不了」的实战坑。绝大多数页面由转换器 / recipe 编译器生成,所以多数修复落在生成逻辑(Java),但症状表现为 amis 行为——下面按 amis 概念分组。
触发场景
- 生成或手改 amis 页面后:联动失效、选不中、显 id、空列表报错、行内编辑异常。
- 在 DesignerPage overlay 或 recipe 模板里调字段 / 事件 / 列。
- 排查「功能通了但 UI/UE 不对」。
铁律(先读这条)
- 必真渲染实测:任何 amis 改动都要 vite 反代 + Playwright / 浏览器逐屏看。功能点 e2e(落库 / status)≠ 视觉 / UE 走查——很多坑只在渲染时暴露。
- 线上 sdk.js 与 amis-fork 源码已漂移:以实际加载的 sdk 行为为准,别照搬某版源码 API;直接改 sdk 有全站回归险。
- 属性别凭记忆:amis 属性多且迭代快,查官方文档(context7 / amis.io),别幻觉出不存在的属性或事件名。
- 行为不确定先隔离钉死:建隔离
amis.embed手写最小 schema 跑真事件,确认机制后再写后端 / 转换器。 - 校验工具:
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,否则联动挂不上。
- 区分事件类型(
initedvschange),别一把抓全挂。 - 联动脚本要覆盖所有按钮模式(不只 FULL_AUTO,NO_S3 等也要)。
红线
- 改 amis 行为前先想清楚改的是「生成逻辑(转换器 / recipe)」还是「单页 overlay」——前者影响全站,必跑回归。
- schema 只能用注册过的组件 / 动作;改动后
validate+ 真渲染双验证再收工。