Beekeeper Studio JSON 侧边栏完全指南：以 JSON 视角查看行数据、内联展开外键并支持正则搜索-育师

Beekeeper Studio JSON 侧边栏完全指南：以 JSON 视角查看行数据、内联展开外键并支持正则搜索

【免费下载链接】beekeeper-studioModern and easy to use SQL client for MySQL, Postgres, SQLite, SQL Server, and more. Linux, MacOS, and Windows.项目地址: https://gitcode.com/GitHub_Trending/be/beekeeper-studio

JSON 侧边栏（JSON Sidebar）是 Beekeeper Studio 中一项面向"行级数据"的高效查看工具：它可以把数据表格中的任意一条记录以标准 JSON 格式完整呈现，支持宽表、复杂 Schema 与嵌套字段的阅读，还能点击外键就地展开关联记录、用模糊文本或正则表达式过滤字段。读完本文，你将掌握 JSON 侧边栏的两种打开方式、关系内联展开、文本/正则搜索，以及其背后的组件结构与过滤、展开、解析等底层实现原理。

快速上手：两种方式打开 JSON 侧边栏

在任何数据表格中，JSON 侧边栏可以通过以下两种方式之一打开（见官方文档 docs/user_guide/json-sidebar.md）：

右键任意数据行，选择See Details（查看详情）——这是最直觉的操作路径，面向当前聚焦的行；
点击应用标题栏右侧的停靠（dock-right）图标——打开侧边栏后，它会跟随当前选中的行或表数据联动更新。

打开后，当前记录会以 JSON 对象的形式呈现在右侧侧边栏中。其核心价值在于：宽表（wide tables）（列数极多、横向滚动困难的表）、复杂 Schema（多层级嵌套的列结构）以及嵌套字段（如 JSON/JSONB 列、数组、对象组合）都能在 JSON 视图中一目了然。

查看与复制：它就是标准 JSON

JSON 侧边栏渲染的正是普通 JSON 文本——没有私有格式、没有魔改标记。这意味着：

你可以直接在侧边栏中阅读任意字段的完整值与嵌套层级；
当你得到满意的数据后，直接复制即可（文档原话："simply copy the data -- it's normal JSON!"），可无缝粘贴到编辑器、接口调试工具或脚本中继续使用。

侧边栏顶部的⋮ 菜单还提供了几个与查看/复制相关的常用操作（源码见 JsonViewer.vue）：

菜单项	作用
Copy Visible	把当前可见（过滤后）的 JSON 文本复制到剪贴板
Collapse all / Expand all	一键折叠或展开全部嵌套层级
Always Expand Foreign Keys	切换"默认自动展开外键"开关（默认关）
Wrap Text	切换长行文本是否自动换行

内联查看关系：点击外键就地展开

对于 join 表、或者依赖大量关联来组织数据的 Schema（文档特别点名了 Ruby on Rails 风格的数据模型），JSON 侧边栏提供了一种轻量级的关系浏览方式：

直接点击 JSON 中的外键，即可**就地（in-line）**展开对应的关联记录，无需切换标签页、也无需手写 JOIN 查询。

实现上，所有可展开的外键路径会作为expandablePaths传入侧边栏，组件定位到该键所在行后，用 CodeMirror 的Decoration.replace替换为可点击的expandable-value小部件（带下拉箭头图标），点击后通过expandPath事件回调，将{ path, tableKey }结构传给上层以懒加载并内嵌关联数据。这部分逻辑位于 jsonViewer.ts 的createExpandableTextDecoration/ExpandableTextWidget，以及findKeyPosition/findValueInfo两个定位辅助函数（jsonViewer.ts）。

如果你希望每次打开记录时都自动展开第一层外键，可以在侧边栏菜单中打开Always Expand Foreign Keys；对应地，JsonViewer.vue 在dataId更新时会遍历expandablePaths，将深度为 1 的外键全部自动展开。

（完整的交互演示可参考仓库中的视频文件 json-sidebar-fks.mp4。）

用文本或正则表达式搜索字段

侧边栏顶部的搜索框同时支持两种过滤模式：

模糊文本搜索：直接输入任意文本，按字段路径（如actor.firstName）做大小写不敏感的包含匹配，把不相关的字段从 JSON 视图中过滤掉；
正则表达式搜索：以/正则/标志位的格式输入（例如/^address/或/date/i），即可按正则匹配字段路径，精确定位你关心的数据。

搜索框的占位提示在源码中写得很明确——Filter keys by text or /regex/（JsonViewer.vue），输入经过 500ms 防抖后生效（JsonViewer.vue），并且搜索结果会实时联动过滤右侧 JSON 视图。搜索关键字也会随标签页持久化，切换标签页后自动恢复（见下文"状态持久化"）。

正则解析的底层实现

过滤逻辑的核心在 jsonViewer.ts 的deepFilterObjectProps与 utils.ts 的toRegexSafe：

export function toRegexSafe(input: string) { const match = input.match(/^\/(.+)\/([a-z]*)$/); if (!match) return null; try { return new RegExp(match[1], match[2]); } catch (e) { return null; } }

输入以/开头并以/标志位结尾时，被识别为正则并编译为RegExp（非法正则返回null，退化为普通文本处理）；
否则按普通模糊文本处理：path.toLowerCase().includes(filter.toLowerCase())；
过滤发生在字段路径上（如address.city），而非值内容——这一点与文档"找到你想要的数据"的定位一致：先缩小字段范围，再在剩余的 JSON 中精读值。

（交互演示可参考仓库中的视频文件 json-sidebar-regex.mp4。）

源码剖析：侧边栏如何工作

从源码结构看，JSON 侧边栏由两层组件 + 一组数据工具函数构成，理解这套结构有助于你判断它的行为边界与可扩展点。

1. 容器组件`JsonViewerSidebar.vue`

JsonViewerSidebar.vue 负责与全局应用状态对接：

订阅三个AppEvent（定义于 AppEvent.ts）：updateJsonViewerSidebar（接收新行数据）、jsonViewerSidebarExpandPath（转发外键展开）、jsonViewerSidebarValueChange（转发 JSON 值编辑结果）；
维护value / expandablePaths / editablePaths / signs / dataId / filter等状态，并通过UpdateOptions结构统一更新（jsonViewer.ts 中定义了该接口）；
按jsonViewerSidebar-${tabId}为每个标签页分别持久化搜索过滤词（SmartLocalStorage），切换标签页时自动恢复，关闭标签页时清除。

2. 渲染组件`JsonViewer.vue`

JsonViewer.vue 负责把记录渲染成可交互的 JSON 编辑器：

基于 CodeMirror 的text-editor组件，language-id="json"，内置 JSON 语法高亮、代码折叠（fold-gutters）；
通过JsonSourceMap.stringify(value, null, 2)生成格式化 JSON，同时利用json-source-map建立文本位置 ↔ 对象路径的映射，这是外键点击、可编辑区域定位、行号标记（lineGutters）的共同基础；
支持局部可编辑：editablePaths范围内的值可以在侧边栏内直接编辑，编辑内容经过 JSON 解析校验后通过bks-json-value-change事件回写（非法 JSON 会以错误 marker 标出，见 JsonViewer.vue）。

3. JSON 列自动解析：`parseRowDataForJsonViewer`

数据库返回的行数据通常是字符串，侧边栏显示前会经过 jsonViewer.ts 的parseRowDataForJsonViewer处理：

数据类型为JSON/JSONB的列直接JSON.parse；
非 JSON 类型的列，若字符串以{…}或[…]包裹，也会尝试解析为对象/数组；
解析失败仅记录警告日志，不阻断查看，保证容错。

4. 长文本截断与二进制值

超过globals.maxDetailViewTextLength的字符串默认截断显示，行尾渲染为带 "Show more" 的truncatable-value小部件，点击即恢复完整内容（jsonViewer.ts）；
TypedArray / Buffer 等二进制值会按binaryEncoding配置（$bksConfig.ui.general.binaryEncoding）转为可读字符串（JsonViewer.vue），避免在 JSON 视图中出现乱码或不可序列化对象。

5. 端到端测试覆盖

仓库中保留了对应的 E2E 测试骨架 jsonSideBar.test.ts：测试流程先连接 PostgreSQL、执行SELECT * FROM actor WHERE actor_id IN (1, 2);、等待结果行渲染，再验证侧边栏的可见性（当前测试标记为skip，注释中说明仍需处理试用弹窗与侧边栏文件），但它完整还原了"建连 → 查询 → 打开 JSON 侧边栏"的真实使用链路，可作为复现该功能的手动操作清单。

小结

JSON 侧边栏是 Beekeeper Studio 面向"单条记录深读"场景的标配工具：右键或标题栏图标即可打开；宽表、复杂 Schema、嵌套字段一屏尽览；数据即标准 JSON，复制即用；外键可点击内联展开，配合"默认自动展开外键"开关，适合 join 密集型的 Rails 风格数据模型；顶部的搜索框同时支持模糊文本与/regex/正则两种过滤模式。其底层由 JsonViewerSidebar.vue 与 JsonViewer.vue 两级组件驱动，借助 json-source-map 实现位置映射，再由 jsonViewer.ts 提供路径定位、深过滤、JSON 列解析、长文本截断等能力——既实用，也具备清晰的二次理解与扩展路径。

创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考

Beekeeper Studio JSON 侧边栏完全指南：以 JSON 视角查看行数据、内联展开外键并支持正则搜索