JSONViewer
折叠、检查和复制结构化数据。中文惯用名：JSON 查看器。
稳定本期新增已接入
元信息
| 字段 | 值 |
|---|---|
| 规范 ID | component.json-viewer |
| 名称 | JSONViewer |
| 二级分类 | 媒体与内容（media） |
| 用途 | 折叠、检查和复制结构化数据 |
| 描述 | 中文惯用名：JSON 查看器。 |
预览
静态结构：等宽字体卡片（font-mono text-xs bg-muted）；对象 / 数组节点 <button data-slot="json-toggle">（chevron + 键名，折叠时显示摘要 […] N 项 / {…} N 键），叶子值按类型着色（string → text-success 带引号 / number → text-info / boolean → text-warning / null → text-muted-foreground）；expandedDepth 控制默认展开层数；copyable 根部复制按钮（复制格式化 JSON，成功变 √ 两秒）。
DSL 结构
{
"type": "JSONViewer",
"props": {
"data": {
"code": 0,
"data": {
"total": 128,
"items": [
{
"id": 1,
"name": "示例"
}
]
}
},
"expandedDepth": 2,
"copyable": true
}
}何时用
何时使用
- 折叠、检查和复制结构化数据：接口响应、状态快照、配置对象。
- 调试面板、开发工具类页面。
何时不用
- 面向终端用户的数据展示：用 Descriptions / Table。
- 编辑 JSON：本组件只读。
变体
| 变体 | 视觉形态 | 适用场景 |
|---|---|---|
| 默认展开一层 | expandedDepth=1 | 常规检查 |
| 全折叠 | expandedDepth=0 | 大对象概览 |
| 带复制 | 根部复制按钮 | 响应导出、分享 |
API 属性
| 属性 | 类型 | 默认值 | 说明 |
|---|---|---|---|
data | unknown | — | 结构化数据（对象 / 数组 / 原始值） |
expandedDepth | number | 1 | 默认展开深度（0 全部折叠） |
copyable | boolean | true | 根部是否显示复制按钮 |
className / style | string / CSSProperties | — | 通用：根节点 class 合并 / 内联样式 |
使用规范
- 大对象先用 expandedDepth=0 给概览，避免首屏渲染整棵树。
- 循环引用 / BigInt 等不可 JSON 序列化的值不支持（复制与摘要基于 JSON 语义）。
- 面向终端用户的信息不要原样倒 JSON（应整理为 Descriptions）。
正例
- ✓ 调试面板：页面 state 快照折叠检查 + 一键复制。
- ✓ 接口文档：示例响应折叠展示字段结构。
反例
- ✕ 用 JSONViewer 做业务数据主视图（应使用 Table / Descriptions）。
- ✕ 渲染未脱敏的用户数据（调试信息也需脱敏）。
Design Token 映射
不适用：组件 tokenRefs 为空：样式 Token 数据尚未接入，三层映射（Primitive → Semantic → Component）待样式 Token 接入后回填。