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

4.3 KiB
Raw Blame History

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