ObjectInspector 对象查看器

RenderObjectInspector 是开发和调试阶段使用的对象查看器。它用于枚举对象属性、查看值预览、展开嵌套节点、复制路径和值，并配合运行时诊断、布局检查和上下文调试定位问题。

它不是业务数据展示控件。业务页面展示对象应使用表单、表格、树或详情组件；ObjectInspector 用于开发工具、诊断窗口和调试页面。

API 总览

import {  RenderObjectInspector,  type ObjectInspectorDebugNode,  type ObjectInspectorOptions,} from 'ds-ui'

API	类型	用途
`RenderObjectInspector`	class	调试对象查看器，枚举对象属性、展开嵌套节点、复制路径和值。
`ObjectInspectorOptions`	type	构造参数。
`ObjectInspectorDebugNode`	type	树节点调试数据结构。

最小装配顺序是：传入 label 和要查看的 value，再按对象规模配置 maxProperties、expansionBatchSize、propertyGroupSize。ObjectInspector 会持有 value 引用，关闭调试窗口时必须释放它。

适用场景

查看应用上下文、页面上下文和弹窗上下文。
查看页面 state、store 快照、controller 状态。
查看组件 debugState()。
查看运行时诊断快照。
查看 API 返回值结构。
检查关闭页面后是否仍有对象被引用。

最小示例

const inspector = new RenderObjectInspector({  label: 'demoState',  value: {    patient: { id: 'p001', name: '李安然' },    tags: ['住院', '重点'],  },  maxProperties: 200,  expansionBatchSize: 80,  adaptiveTreeHeight: true,})

label 是根路径名称。复制节点时会作为路径前缀。

构造参数

参数	类型	默认值	说明
`value`	`unknown`	必填	要查看的根对象或值。
`label`	`string`	`'root'`	根节点路径名称。
`treeHeight`	`number`	内部默认值	树区域固定高度。
`adaptiveTreeHeight`	`boolean`	`false`	是否根据可用空间自适应树和详情布局。
`maxProperties`	`number`	`160`	单个对象最多枚举的属性数量。
`copyMaxProperties`	`number`	`maxProperties`	复制对象值时最多输出的属性数量。
`expansionBatchSize`	`number`	`80`	展开子节点时每批加载的数量。
`propertyGroupSize`	`number`	`500`	大量属性时的分组大小。
`stringMaxLength`	`number`	`160`	预览字符串最大长度。
`includePrototype`	`boolean`	`true`	是否显示原型链相关信息。

树节点信息

每个 debug node 包含：

字段	说明
`key`	TreeView 使用的稳定节点 key。
`label`	节点显示文本。
`path`	可复制路径，例如 `demoState.patient.tags[0]`。
`type`	值类型，例如 Object、Array、string、number。
`preview`	值摘要。
`expandable`	是否可展开。
`loaded`	子节点是否已加载。
`loading`	是否正在分批加载。
`children`	已加载的子节点。

详情面板

右侧详情面板用于查看当前选中节点的完整调试信息：

Path：完整路径。
Type：类型。
Value：当前值预览。
Descriptor：属性描述符信息。
Error：读取属性时的错误。

详情区的目标是让开发者不用只靠树节点短文本判断对象内容。

大对象处理

ObjectInspector 面向调试，不应该一次性展开几十万属性。大对象应通过几个参数控制：

参数	建议
`maxProperties`	控制每个对象最多枚举多少属性。
`propertyGroupSize`	大数组或大对象按区间分组，例如 `[[Properties 0-499]]`。
`expansionBatchSize`	展开时分批创建节点，减少单次卡顿。
`stringMaxLength`	防止超长字符串挤爆详情和树节点。
`copyMaxProperties`	防止复制超大对象导致 UI 卡顿。

推荐调试大状态对象时先看摘要层，再逐级展开，不要展开根对象下所有分支。

复制规则

调试工具的复制结果必须能直接用于沟通和定位问题。复制节点时应包含完整路径和值。

示例：

demoState.patient.name: '李安然'
demoState.patient.tags[0]: '住院'

数组路径使用括号形式，不使用 tags.0。这样更接近 JavaScript 访问语义，也方便开发者定位。

复制对象节点时，可以输出该节点下的结构化值，但会受 copyMaxProperties 限制。超过限制时应输出摘要，避免复制操作卡住应用。

和 Layout Inspector 配合

Layout Inspector 通常会在选中 render 节点后展示：

当前节点基本信息。
debugState()。
附近 app context。
runtime paint request 摘要。

这些对象可以通过 ObjectInspector 展开。排查 UI 问题时，推荐流程：

用 Layout Inspector 选中异常组件。
查看组件 rect、type 和层级。
展开 debugState()。
查看 selected、hover、scroll、visible range 等内部状态。
复制异常节点路径和值，用于 issue 或调试记录。

和 App Context 配合

查看上下文时，ObjectInspector 关注两件事：

key 是否在正确层级。
value 是否是预期对象。

常见问题：

页面级对象误放到应用级上下文。
弹窗没有继承调用页面上下文。
key 描述过于模糊，调试时无法判断来源。
页面关闭后上下文仍被 popup 或闭包引用。

和 Runtime Diagnostics 配合

Runtime Diagnostics Panel 的详情区使用 ObjectInspector 展开 request 和 hotspot 数据。重点看：

target
kind
reason
stack
dirtyLayers
layoutTargets
paintTargets

如果 stack 指向某个组件 setter 或 performLayout()，就可以回到对应组件检查是否反复写入相同状态。

安全和脱敏

ObjectInspector 可以查看任意对象，因此要注意：

不要在生产业务主流程中暴露任意对象查看能力。
诊断窗口对外提供快照前应脱敏。
患者信息、账号 token、接口凭证、完整病历内容不应直接出现在可导出快照中。
对超大文本和二进制数据应展示摘要，不展示完整内容。

生命周期

ObjectInspector 会持有 value 引用。关闭检查器窗口时必须释放检查器本身，避免它继续持有大对象。

对于页面级调试窗口：

页面关闭时关闭 ObjectInspector 窗口。
不要把页面对象复制到全局诊断服务中长期保存。
快照只保存摘要对象，不保存活的 controller、DOM、canvas 或大型缓存。

常见错误

复制结果只有 key 没有 value

调试复制必须包含路径和值，否则无法用于问题沟通。对象节点应复制结构化摘要，叶子节点应复制完整路径和值。

展开大对象卡顿

降低 maxProperties 和 expansionBatchSize，设置 propertyGroupSize，并避免从根对象一次性展开所有分支。

树节点可以省略，但详情面板和复制值应尽量提供完整值或明确的截断标识。

关闭页面后内存仍被持有

检查 ObjectInspector 是否仍然打开，或者诊断快照是否保存了活对象引用。调试工具应保存普通 JSON 摘要，而不是业务对象实例。