Voyager 侧边栏宽度调整指南：为 Gemini 与 AI Studio 定制界面布局-平芜编程栈

AI 应用
前端

【免费下载链接】voyager

Enhancement suite for Gemini, AI Studio, Claude & ChatGPT — plus a prompt manager for any websites, DeepSeek Harness included. / 面向 Gemini、AI Studio、Claude 与 ChatGPT 的增强套件；其中的提示词管理器可用于任意网站，如 DeepSeek Harness。

项目地址：https://gitcode.com/gh_mirrors/ge/voyager

点击查看免费下载

本篇指南围绕 Voyager 的侧边栏宽度调整功能展开：当 Gemini / AI Studio 侧边栏中的文件夹名称过长显示不全，或侧边栏挤占了过多对话空间时，你可以通过 Voyager 弹窗设置中的滑块自由调整宽度，并将偏好自动保存、跨页面生效。读完本文，你将掌握该功能的完整操作流程、支持的平台范围，以及它从滑块到 CSS 变量注入的底层实现原理。

功能概述：为什么需要调整侧边栏宽度

Gemini 与 AI Studio 的侧边栏默认宽度是固定的，而不同用户的真实使用场景差异很大：

文件夹名太长显示不全：使用 Voyager 的文件夹（Folders）功能整理会话后，长文件夹名会被截断，无法一眼看清归属；
侧边栏挤占聊天空间：在窗口较窄或需要专注阅读对话时，固定宽度的侧边栏会让内容区显得局促。

Voyager 提供的侧边栏宽度调整功能正是为解决这两类痛点而设计：既可以收窄以节省空间、聚焦对话，也可以加宽以完整显示长文件夹名称。

操作步骤：三步完成宽度调整

打开 Voyager 设置面板：点击浏览器右上角的扩展图标，打开 Voyager 的弹窗（Popup）界面；

找到侧边栏宽度选项：在设置面板的布局（Layout）区域中找到Sidebar width（侧边栏宽度）选项，它位于通用设置（General Settings）中，与聊天宽度、输入框宽度等调整项属于同一组布局类设置；
拖动滑块选择宽度：向左拖动收窄侧边栏，向右拖动加宽侧边栏，释放滑块后设置即刻生效。

宽度两端对应的效果：

窄（Narrow）：节省空间，把注意力集中在对话内容上；
宽（Wide）：一眼看清完整的文件夹名称，减少因截断带来的误点。

在弹窗中，侧边栏宽度滑块还带有一个启用开关（Switch）：关闭开关即可完全禁用自定义宽度并恢复站点默认布局。关闭时滑块区域会收起，保持面板整洁；数值徽标会实时显示当前选择的宽度（以像素为单位）。该交互由 WidthSlider.tsx 这个可复用组件实现，它与聊天宽度、编辑输入框宽度等设置共用同一套滑块交互逻辑。

支持的平台与适用范围

该功能同时支持两个平台（对应官方文档说明及源码中的平台判断逻辑）：

Google Gemini
Google AI Studio

两个平台由弹窗层根据当前站点上下文自动区分：在 usePopupLayoutSettings.ts 中，通过isAIStudio标志选择不同的存储键与取值范围——Gemini 侧使用百分比的兼容式宽度，AI Studio 侧使用独立的像素区间。因此同一套设置面板在不同站点上会呈现各自合理的宽度范围，互不干扰。

设置保存与生效机制

自动保存：拖动滑块完成调节后，数值会立即写入chrome.storage.sync，无需手动确认；
跨页面生效：设置会被同步存储，因此你在一次打开页面时调整的宽度，会在下次打开页面时自动应用（见官方英文文档）；
跨设备同步：由于使用chrome.storage.sync（而非local存储），登录同一 Chrome 账号的其它设备也会继承该偏好；
即时响应：内容脚本会监听存储变化（chrome.storage.onChanged），因此弹窗中拖动滑块后，当前已打开的 Gemini 页面也会实时应用新宽度，而不必刷新页面。

源码级原理：从滑块到 CSS 变量的完整链路

1. Gemini 侧：通过 CSS 变量接管原生宽度

Gemini 的侧边栏（<bard-sidenav>）原生宽度由 CSS 变量--bard-sidenav-open-width控制。Voyager 的内容脚本 src/pages/content/sidebarWidth/index.ts 的做法是：

动态创建一个<style id="gv-sidebar-width-style">注入页面（ensureStyleEl）；
将用户设定的宽度写入:root与bard-sidenav的--bard-sidenav-open-width变量，并附带!important以确保覆盖站点默认值；
同时维护--bard-sidenav-open-closed-width-diff与--gv-sidenav-shift两个派生变量，用于计算侧边栏展开/收起时的位移量，保证顶栏的模式切换器（mode switcher）能跟随加宽后的侧边栏平移对齐，不会出现错位。

启用开关关闭或页面卸载时，脚本会移除注入的样式元素（removeStyles），干净地恢复站点原始布局。

2. 参数范围与默认值

Gemini 与 AI Studio 两套宽度配置定义在 src/pages/popup/utils/layoutSettings.ts，具体如下：

平台	最小值	最大值	默认值	滑块步长
Google Gemini	15%（约 180px）	45%（约 540px）	26%（约 312px）	8px
Google AI Studio	240px	600px	280px	8px

说明：

Gemini 侧内部以百分比为基准（15%–45%），并保留一个 1200px 的“历史基线”用于旧版本像素值的兼容换算（LEGACY_BASELINE_PX = 1200，默认 26% 即 312px）；
当从旧版本迁移时，如果存储中是一个看起来像百分比的小数值，normalizePercent/normalizeSidebarPx会先将其换算为像素再收敛到合法区间，防止越界；
最终注入 Gemini 页面的实际宽度采用clamp(200px, {n}vw, 800px)形式，既保留了早期vw百分比的行为，又限制在 200px–800px 的物理区间内，避免在超宽屏上失控；
AI Studio 侧则是纯像素区间（240px–600px），由AI_STUDIO_SIDEBAR_PX常量定义，同样在写入前经过clampNumber收敛。

3. 存储键、升级路径与旧数据兼容

内容脚本启动时会读取geminiSidebarWidth与启用标志两个键（具体键名定义在 src/core/types/common.ts 的StorageKeys中）：

区分“从未设置”与“显式关闭”：读取时特意不带默认值，以便识别键是否存在。对于老用户（从未见过启用开关、但此前已自定义过宽度），会走自动启用的升级路径：只要检测到自定义宽度且无启用标志，就自动开启功能并把开关状态写回存储；
归一化回写：若读取到的旧值超出新范围，会先归一化再回写存储，保证新旧版本数据一致；
存储变更监听：chrome.storage.onChanged监听器负责在弹窗调整时实时重新注入样式，或在该功能被关闭时移除样式。

4. 兼容性细节：点击穿透与侧边栏切换守卫

加宽侧边栏会带来一个隐蔽问题：Gemini 的top-bar-actions等顶部操作层在侧边栏位移后可能覆盖住真实控件。内容脚本在注入的样式中针对bard-mode-switcher、top-bar-actions等容器设置了精细的pointer-events白名单——容器整体穿透，但其中的按钮、链接、输入框、search-nav-button、side-nav-sparkle-button、side-nav-menu-button等真实可交互控件仍保持可点击，并用z-index保证它们位于顶层。

此外，脚本还实现了侧边栏切换点击守卫（setupSidebarToggleHitGuard）：当用户在捕获阶段点击了侧边栏切换按钮的区域、却被覆盖层拦截时，守卫会通过document.elementsFromPoint判断真实目标，阻止默认行为并手动调用真实切换按钮的click()，确保加宽后依然能正常展开/收起侧边栏。这些细节均有测试用例覆盖，见 sidebarWidthCentering.test.ts。

常见问题与使用建议

侧边栏宽度与“自动隐藏”类设置的关系：弹窗的布局区域中还有“侧边栏自动隐藏”等行为开关（见 PopupLayoutSettings.tsx），它们与宽度调整互相独立、可叠加使用，可按需组合出适合自己的布局；
宽度设置没生效？请确认弹窗中侧边栏宽度的启用开关处于打开状态——若开关关闭，内容脚本不会注入任何样式；调整后新值会通过存储监听实时应用，若遇到个别页面未即时刷新，刷新一次页面即可；
关于各语言文档：本指南基于阿拉伯语文档 docs/ar/guide/sidebar.md 与英文文档 docs/en/guide/sidebar.md 编写，其余语言版本可在docs/{zh,ja,es,fr,pt,ru,ko,zh_TW}/guide/目录下找到对应译文。

掌握侧边栏宽度调整后，你可以在 Gemini 与 AI Studio 中自由权衡“信息密度”与“专注空间”，让 Voyager 的文件夹管理、会话组织等功能在真正舒适的界面宽度下工作。