docs(runner): Error Boundaries 一条改为可达的 SchemaErrorBoundary (#3635)

[yinlianghui]

Fixes#3635

裁决依据:该单 2026-08-08 的 PM 重裁 (A')(issue comment 5223449796)—— 就地改正为 import { SchemaErrorBoundary } from '@object-ui/react',并按其第 3 条讲清内建/外层边界分工。零 API 成本,未新增任何公开导出。

⚠️ 下文 JSX 尖括号后特意加空格:GitHub 正文消毒器在存储时会把「< 紧跟字母」当 HTML 标签吃掉。文件里无空格。

修前(全文引用)

### 2. Error Boundaries
Wrap components in error boundaries:
```typescriptimport { ErrorBoundary } from'@object-ui/components'<ErrorBoundary><SchemaRendererschema={schema} /></ErrorBoundary>```

@object-ui/components没有ErrorBoundary 导出(grep -rn 'ErrorBoundary' packages/components/ 全包零命中),故该示例整体不可执行。

前提更正:本单原诊断的第三条断言不成立

原单据「packages/react/src/index.ts 里搜 Boundary 零命中」判定 SchemaErrorBoundary 未公开导出,并由此得出「Runner 依赖面上无任何可 import 的错误边界」。该测量方法对星号再导出失明:

packages/react/src/index.ts:9 export * from './SchemaRenderer';
packages/react/src/SchemaRenderer.tsx:131 export class SchemaErrorBoundary extends Component< …

export * 携带该类,但字面量 Boundary 不出现在入口文件里。runner 直接依赖 @object-ui/react(workspace:*),因此可达的错误边界今天就存在,零改动 —— 这把处置从「删节 / 新造 API」变成了本 PR 的零成本就地改正。

修后

改用 SchemaErrorBoundary,并补齐两段行文(裁决第 3 条要求,不写成「再包一层保险」的模糊句):

1. SchemaRenderer自身已对每个被渲染组件内建一层边界(packages/react/src/SchemaRenderer.tsx:447-468),单个 widget 抛出只降级为行内 "failed to render" 提示 + Retry 按钮,不会白屏;链接到已记载此行为的 /docs/guide/architecture-overview(该页 :115 已写 "wrapped in a per-component ErrorBoundary")。
2. 内建边界的 JSX 在 :447 才构造,SchemaRenderer 在此之前做的事 —— 求值 visibleOn / disabled 等动态表达式、经注册表解析组件类型 —— 都在它之外,那里的抛出会越过内建边界向外传播。故外层边界并非纯冗余,它多保护的正是这一类失败。

另注明两个可选 prop(均据实现核对):componentType 决定 fallback 文案里的组件名,resetKey 变化时清除错误并重挂子树(componentDidUpdate 的自动恢复路径)。

验证(先预测后运行,五条全中)

预测	结果
从 runner.mdx 逐字提取的 import 行 + 文档 JSX 形状,经真实 node_modules 解析(走 exports/types)tsc → 绿	✅ import { SchemaErrorBoundary } from '@object-ui/react' → exit 0
反向对照:同装置换成修前那个符号名 → 红(证明上条非空转假绿)	✅ error TS2305: Module '"@object-ui/react"' has no exported member 'ErrorBoundary'. exit 2
行文所述两个 prop 真实存在 → 绿	✅ componentType="grid" + resetKey={…} 一并 tsc exit 0
修后坏形态 grep 归零	✅ from '@object-ui/components' → 0;@object-ui/app-shell → 0;文件内 4 处 ErrorBoundary 全部是 SchemaErrorBoundary
check-doc-links + check-control-bytes 绿	✅ 真实退出码各为 0(Links are valid across 7 scan roots. / OK (scanned 3684 tracked text file(s)))

门禁敏感度反证(本 PR 新引入一条内部链接,故须证明 linkchecker 不是「静默放过」):临时追加一条同形但不存在的 /docs/... 路由,check-doc-links 报
- [docs-route] content/docs/utilities/runner.mdx:604 -> /docs/guide/architecture-overview-THIS-DOES-NOT-EXIST,真实退出码 1;还原后与备份 diff 一致、再跑复绿。故上表末条的绿是真检出。

过程说明:该反证首轮我用了 node … | tail -4 后读 $?,读到的是 tail 的退出码(0),把红当成了绿。已改用捕获 $? 重跑,上面所有退出码均为未经管道遮蔽的真实值。

控制字符自扫:grep -naP '[\x00-\x08\x0b\x0c\x0e-\x1f]' content/docs/utilities/runner.mdx 零命中(gate 扫描面之外的自查)。

范围

• 单文件单 hunk:content/docs/utilities/runner.mdx(+16 / -4)。
• ⛔ 未碰任何包源码 —— 未新增导出、未改 packages/react。本 PR 只是引用一个早已随 @object-ui/react 发布的符号,不产生新的 semver 契约(这正是裁决 (b) 原本想守护、而 (A') 完整满足的那条红线)。
• 无 changeset:改动只在站点文档 content/,@object-ui/site 本就在 .changeset/config.json 的 ignore 列表内。
• 文件互斥:content/docs/utilities/runner.mdx: Best Practices 的「Environment Configuration」小节复活了 #3538 刚删掉的环境变量面,且与同页「reads no environment variables」直接矛盾 #3617 / PR docs(runner): 删掉 Best Practices 里复活的环境变量配置面 (#3617) #3633 已合入 main;本 PR 锚定 0cf8f0f70 按内容重定位,不依赖行号。content/docs/utilities/runner.mdx §Add Custom Routes 教读者用 react-router-dom 改写 App.tsx,但 runner 不依赖它,路由是手写的 history.pushState #3618(同页 ### Add Custom Routes)未碰。

未立新 issue(与原派发口径的差异,已获重裁确认)

原派发要求另立「@object-ui/react 是否公开导出 SchemaErrorBoundary」特性 issue。未提交 —— 其前提已被上述测量证伪(该导出已存在),立单等于向路线图提交一个已成立的问题。先搜重确认无既有同类单(is:open SchemaErrorBoundary、is:open ErrorBoundary export react 均只命中 #3635 本身)。重裁第 2 条已确认此判断。

---

🤖 Generated with Claude Code

https://claude.ai/code/session_01GTRjn8xBqp75dk7kFupVRt

---

Generated by Claude Code

[vercel]

The latest updates on your projects. Learn more about Vercel for GitHub.

1 Skipped Deployment

Project	Deployment	Actions	Updated (UTC)
objectui	Ignored		Aug 8, 2026 9:08am