详情页:支持 detail.stageField: false 显式关闭自动状态进度条

[baozhoutao]

问题描述

详情页 / 记录页(plugin-detail 的 synth)会自动在记录顶部渲染一条"状态进度条"(Lightning Path 风格的状态步进器 record:path)。

判定逻辑在 packages/plugin-detail/src/synth/buildDefaultPageSchema.ts 的 detectStatusField():在没有显式 stage 提示时,会按名(status/stage/state/phase)或按类型(status/stage)自动命中一个字段。

痛点: 很多对象有一个名为 status 的 select 字段,但它表达的是非线性的状态集合(例如「正常 / 暂停 / 作废」这类彼此独立、没有先后顺序的状态),并不是有序的流程阶段。这种字段被自动命中后,会被强行渲染成顶部有序进度条,语义和视觉都不对,用户也没有任何办法关掉它。

之前的 hidePath 方案(#2062)要同时改 app-shell 接线 + synth + 跨仓库 framework 文档,过于复杂,已撤销。

方案描述(已修正承载位置)

⚠️ 修正: 最初设想把开关读在顶层 def.stageField,但 @objectstack/spec 的 ObjectSchema.create() 拒绝未知顶层键(NoExcessObjectKeys<T> → never,tsc 报错;build 期也拒,见 framework #1535)。作者根本无法在对象定义顶层设这个键,对真实对象不可达。已改为读 spec 现成的 detail 块。

spec 的 object.zod.ts(~711 行)有一个 .passthrough() 的 detail 块,描述就是 "Detail-page UI hints consumed by @object-ui/plugin-detail synth"(已有 renderViaSchema / hideReferenceRail / hideRelatedTab)。它是作者可达的 UI 提示落点(passthrough → 未知键合法通过校验并透传到客户端)。

给它一个显式退出(opt-out)信号:

• detail.stageField === false(或 null)→ detectStatusField() 直接返回 null,不渲染进度条,并跳过后续自动探测;
• detail.stageField 为字符串 → 指定具体字段;
• 顶层 def.stageField 保留为裸对象 / 单测的 back-compat 回退;detail.stageField 优先。

作者用法:

ObjectSchema.create({
  name: 'production_plan',
  detail: { stageField: false },   // 关闭顶部状态进度条
  fields: { status: Field.select({ options: [...] }) /* … */ },
});

改动范围:仅 objectui 单文件 packages/plugin-detail/src/synth/buildDefaultPageSchema.ts(+ 单测 + changeset)。detail 块本身是 .passthrough(),该键无需进 framework spec 即可生效,无跨仓库改动。默认行为零回归。

PR: #2066