Storybook 按页面隐藏工具栏用 layoutCustomisations.showToolbar 在 Docs 页面禁用工具栏【免费下载链接】storybookStorybook is the industry standard workshop for building, documenting, and testing UI components in isolation项目地址: https://gitcode.com/GitHub_Trending/st/storybook导读本文讲解如何在 Storybook 中通过addons.setConfig的layoutCustomisations.showToolbar函数按当前页面状态如 docs 文档页、story 故事页动态控制顶部工具栏的显隐。你将掌握showToolbar的完整函数签名、可用的State参数、与用户偏好默认值的协作语义以及这套机制在 Storybook 源码中的实际实现路径从而为文档页、展示页等场景定制干净的阅读界面。本文对应官方文档 Features and behavior代码片段原文见 storybook-manager-toolbar-hide-on-docs.md。一、前置知识manager 配置文件与 addons.setConfigStorybook 的界面manager UI配置统一写在.storybook/manager.js或 TypeScript 项目使用manager.ts中通过storybook/manager-api导出的addons.setConfig传入配置对象import { addons } from storybook/manager-api; addons.setConfig({ // 布局相关配置 });配置对象中与布局相关的顶层字段包括navSize侧边栏宽度像素、bottomPanelHeight、rightPanelWidth、panelPosition面板位置bottom或right、enableShortcuts快捷键开关、showToolbar布尔值全局开关工具栏、theme、selectedPanel、initialActive、layoutCustomisations、sidebar与toolbar。其中showToolbar是静态布尔开关而layoutCustomisations提供了按页面动态决策的三种函数showSidebar、showPanel、showToolbar——本文的主角就是其中的showToolbar。二、layoutCustomisations 机制从静态开关到动态函数从类型定义可以确认layoutCustomisations的三个函数拥有统一的签名见 code/core/src/types/modules/api.tsexport interface API_LayoutCustomisations { showPanel?: (state: State, defaultValue: boolean) boolean | undefined; showSidebar?: (state: State, defaultValue: boolean) boolean | undefined; showToolbar?: (state: State, defaultValue: boolean) boolean | undefined; }每个函数接收两个参数参数类型说明stateState当前界面完整状态包含页面路径、视图模式、故事 ID、索引与布局信息详见下文defaultValueboolean用户偏好的默认值来自静态配置或用户在 UI 中的手动切换函数返回boolean表示是否显示对应 UI 元素返回undefined时表示不干预回退使用defaultValue。这一设计保证了自定义函数可以与用户的手动偏好共存函数只在它明确表态时生效。State中与布局决策最相关的字段如下官方文档 features-and-behavior.mdx 中完整列出字段类型说明示例值pathString当前展示页面的路径/story/components-button--defaultviewModeString当前页面是 story 还是 docsdocs或storysingleStoryBoolean当前页面是否为某组件唯一的 storytrue/falsestoryIdString当前 story 或 docs 页面的 idblocks-unstyled--docsindexObject包含每个 story 静态分析元数据的索引{ blocks-unstyled--docs: { tags: [autodocs] } }layoutObject当前布局状态见下—layout.isFullscreenBoolean预览画布是否处于全屏模式true/falselayout.panelPositionString面板位于预览下方还是侧边bottom/rightlayout.showNavBoolean用户是否希望看到侧边栏true/falselayout.showPanelBoolean用户是否希望看到面板true/falselayout.showToolbarBoolean用户是否希望看到工具栏true/false注意viewMode的取值并不只有docs和story在 layout.ts 中定义了isPagesViewMode判断viewMode 还可能取review等页面模式编写分支条件时应对此有所预期。三、核心案例在 Docs 页面始终隐藏工具栏官方代码片段 storybook-manager-toolbar-hide-on-docs.md 给出了完整可复制的实现。JavaScript 版本.storybook/manager.jsimport { addons } from storybook/manager-api; addons.setConfig({ layoutCustomisations: { // Always hide the toolbar on docs pages, and respect user preferences elsewhere. showToolbar(state, defaultValue) { if (state.viewMode docs) { return false; } return defaultValue; }, }, });TypeScript 版本.storybook/manager.tsimport { addons, type State } from storybook/manager-api; addons.setConfig({ layoutCustomisations: { // Always hide the toolbar on docs pages, and respect user preferences elsewhere. showToolbar(state: State, defaultValue: boolean) { if (state.viewMode docs) { return false; } return defaultValue; }, }, });这段代码的决策逻辑分为两层命中 docs 页面state.viewMode docs时强制返回false无论用户偏好如何工具栏都被隐藏。这适用于自动生成的 Autodocs 页面、自定义 MDX 文档页等所有 viewMode 为docs的页面。其他页面返回defaultValue即完全尊重用户的偏好设置静态配置中的showToolbar: true/false或用户通过快捷键/界面操作产生的临时状态不做任何干预。这种特殊页面强制、其余页面放行的写法是layoutCustomisations函数的标准使用模式。四、源码级原理自定义结果如何真正生效仅仅调用addons.setConfig并不会自动改变界面背后的调用链值得梳理以便理解何时生效、为何生效。1. 配置合并入口在 code/core/src/manager-api/modules/layout.ts 的getInitialOptions中用户通过provider.getConfig()拿到的layoutCustomisations会被合并进默认布局状态const { theme, selectedPanel, layoutCustomisations } userConfig; return { ...defaultLayoutState, layout: applyLayoutOptions(defaultLayoutState.layout, userConfig, !!singleStory), layoutCustomisations: { ...defaultLayoutState.layoutCustomisations, ...(layoutCustomisations ?? {}), }, // ... };默认状态下三个函数均为undefined见 layout.ts只有用户显式提供时才会覆盖。而layoutCustomisations在用户配置中的类型为PartialAPI_LayoutCustomisations见 code/core/src/types/modules/addons.ts即三个函数都是可选的。2. 自定义函数执行点在执行时manager API 提供了包装方法getShowToolbarWithCustomisationslayout.tsgetShowToolbarWithCustomisations(showToolbar: boolean) { const state store.getState(); if (isFunction(state.layoutCustomisations.showToolbar)) { return state.layoutCustomisations.showToolbar(state, showToolbar) ?? showToolbar; } return showToolbar; }这段实现直接印证了官方文档的行为说明只有配置了showToolbar函数时才执行自定义逻辑传入的第二个参数showToolbar正是用户默认值defaultValue返回值若为undefined则通过?? showToolbar回退到默认值这保证了函数可以不表态。3. 界面消费点最终结果在预览区域渲染时被消费。在 code/core/src/manager/components/preview/Preview.tsx 中const { showToolbar } options; const customisedShowToolbar api.getShowToolbarWithCustomisations(showToolbar);customisedShowToolbar随后直接决定工具栏组件ToolbarComp与相关头部元素是否渲染。换言之整个决策链路为manager.js配置 →getInitialOptions合并 →getShowToolbarWithCustomisations执行 →Preview组件消费渲染任何一环缺失都会导致配置不生效。五、进阶变体基于其他状态定制工具栏showToolbar函数可以访问完整的State因此能实现比docs 页面隐藏更精细的规则。以下变体同样可以放入layoutCustomisations.showToolbar只在 story 页面显示其余全部隐藏showToolbar(state, defaultValue) { return state.viewMode story ? true : false; }全屏模式下隐藏工具栏获得沉浸式预览showToolbar(state, defaultValue) { if (state.layout.isFullscreen) { return false; } return defaultValue; }针对特定 docs 页面隐藏showToolbar(state, defaultValue) { if (state.viewMode docs state.storyId blocks-unstyled--docs) { return false; } return defaultValue; }依据索引元数据隐藏带有特定 tag 的页面showToolbar(state, defaultValue) { if (state.index[state.storyId]?.tags?.includes(autodocs)) { return false; } return defaultValue; }在组合多个条件时建议保持先特殊后兜底的结构特殊场景返回固定布尔值其余情况返回defaultValue避免覆盖用户偏好。六、姊妹能力showSidebar 与 showPanellayoutCustomisations中的另外两个函数与showToolbar使用完全相同的模式可用于协调各区域显隐保证界面整体一致函数作用官方示例showSidebar切换左侧侧边栏含搜索与导航菜单显隐({ storyId }, defaultValue) storyId landing ? false : defaultValueshowPanel切换底部/右侧插件面板显隐类似模式基于path、viewMode等条件例如在 docs 页面同时隐藏工具栏与侧边栏可以获得接近纯文档阅读的体验addons.setConfig({ layoutCustomisations: { showToolbar(state, defaultValue) { return state.viewMode docs ? false : defaultValue; }, showSidebar(state, defaultValue) { return state.viewMode docs ? false : defaultValue; }, }, });重要警告官方文档以警示框标注showSidebar与showToolbar隐藏的是 Storybook 核心功能所依赖的界面元素。如果滥用可能导致无法导航。特别是通过showSidebar隐藏侧边栏时必须确保当前展示页面提供替代的导航途径如文档内的目录链接或页面内导航否则用户会陷入无法跳转的困境。七、相关静态配置与 URL 参数1. toolbar 命名空间控制单个工具项如果你不需要按页面动态隐藏整个工具栏而只想增删工具栏中的某个具体工具如全屏、缩放按钮可以使用toolbar命名空间以插件 id 为键控制显隐addons.setConfig({ toolbar: { fullscreen: { hidden: false }, title: { hidden: true }, zoom: { hidden: true }, }, });2. URL 参数无需改配置的临时控制features-and-behavior.mdx还列出了通过 URL 查询参数临时覆盖界面配置的方式适合调试与分享场景配置项Query 参数支持的值enableShortcutsshortcutsfalse全屏fulltrue、false显示侧边栏navtrue、false显示面板panelfalse、right、bottomselectedPaneladdonPanel任意面板 IDshowTabstabstrue—instrumentfalse、true—statuses分号分隔的状态值new、modified、related前缀!表示排除例如?navfalsepanelfalse可以快速获得只含预览画布的界面。这些参数作用于layout状态会作为defaultValue参与showToolbar等自定义函数的决策因此二者是协同关系而非互斥。八、总结在 Storybook 中按页面隐藏工具栏核心就三步在.storybook/manager.js或manager.ts中调用addons.setConfig在layoutCustomisations.showToolbar中基于state.viewMode等状态做判断特殊页面返回固定值、其余页面返回defaultValue以尊重用户偏好。该机制在源码层面由 layout.ts 的getShowToolbarWithCustomisations负责执行、由 Preview.tsx 负责消费类型契约定义于 api.ts。配合showSidebar、showPanel与toolbar命名空间你可以为 docs、story、全屏等不同场景构建各自合适的界面布局。更多完整 API 说明与配置表格可继续阅读 docs/configure/user-interface/features-and-behavior.mdx。【免费下载链接】storybookStorybook is the industry standard workshop for building, documenting, and testing UI components in isolation项目地址: https://gitcode.com/GitHub_Trending/st/storybook创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考