Storybook 实战基于 Story 标签按需隐藏插件面板addon panel的layoutCustomisations.showPanel指南【免费下载链接】storybookStorybook is the industry standard workshop for building, documenting, and testing UI components in isolation项目地址: https://gitcode.com/GitHub_Trending/st/storybook本篇技术指南围绕 Storybook 的 manager 侧 APIaddons.setConfig与layoutCustomisations.showPanel展开讲解如何针对特定 Story如带showcase、kitchensink标签的展示型Story自动隐藏 addon 面板让展示页回归纯粹的画布体验。读完你将掌握showPanel的函数签名、State参数各字段含义、与showSidebar/showToolbar的组合用法以及其底层在 manager-api 中的真实实现原理。为什么需要按 Story 隐藏 addon 面板Storybook 在查看 Story 时默认在画布下方或右侧显示 addon 面板用于呈现 Controls、Actions、Interactions、A11y 等插件的 UI相关面板见 interaction-testing、accessibility-testing、controls 等文档。但对于专门用来展示组件多种变体或使用示例的 Story例如组件画廊页、kitchen-sink 页、landing 页面板往往没有实际调试价值反而挤占画布空间、干扰演示效果。此时需要一种按 Story 维度精细控制面板显隐的能力而不是全局一刀切地开关面板。Storybook 的 manager 配置项layoutCustomisations.showPanel正是为此设计它是一个以当前 UI 状态为输入、返回是否显示面板的高阶函数可以读取当前 Story 的标签tags、viewMode、storyId等上下文决定false隐藏或回退到用户的默认偏好。layoutCustomisationsAPI 总览layoutCustomisations是addons.setConfig下的一个命名空间用于对 Storybook 三大 UI 区域做条件化显隐控制。从源码类型定义 api.ts 可以看到它的完整结构export interface API_LayoutCustomisations { showPanel?: (state: State, defaultValue: boolean) boolean | undefined; showSidebar?: (state: State, defaultValue: boolean) boolean | undefined; showToolbar?: (state: State, defaultValue: boolean) boolean | undefined; }三个回调函数签名一致接收完整的 UIState与一个defaultValue表示当前是否显示的默认值返回true/false覆盖默认行为返回undefined则视为不干预。该配置通过 addons.ts 中的layoutCustomisations?: PartialAPI_LayoutCustomisations挂载到addons.setConfig的参数类型上。官方文档 features-and-behavior.mdx 中给出的三个配置项及其作用如下配置项类型作用showSidebarFunction条件控制侧边栏显隐showToolbarFunction条件控制顶部工具栏显隐showPanelFunction条件控制 addon 面板显隐本文主题对应的完整配置示例同时覆盖三个函数见 storybook-config-layout.md。这些回调函数都允许包含一些默认行为并可按需覆盖从而在保留用户偏好如用户手动打开/关闭面板的前提下对特定页面强制显隐。showPanel函数签名与State参数详解showPanel(state, defaultValue)的第一个参数是当前 manager 的完整状态对象官方文档为它列出了可直接使用的字段字段类型含义示例值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对本文场景最关键的是state.index?.[state.storyId]?.tagsindex中保存了每个 Story 的静态分析元数据含tags配合当前storyId即可拿到当前 Story 的标签数组从而实现按标签隐藏面板。核心实现基于showcase/kitchensink标签隐藏面板以下代码来自官方示例片段 storybook-manager-addon-panel-hide-on-showcase.md直接放入你的 manager 配置文件./storybook/manager.jsTypeScript 项目为./storybook/manager.ts即可生效。JavaScript 版本import { addons } from storybook/manager-api; addons.setConfig({ layoutCustomisations: { showPanel(state, defaultValue) { const tags state.index?.[state.storyId]?.tags ?? []; // Hide the panel on stories designed to showcase multiple variants or usage examples. if (tags.includes(showcase) || tags.includes(kitchensink)) { return false; } return defaultValue; }, }, });TypeScript 版本import { addons, type State } from storybook/manager-api; addons.setConfig({ layoutCustomisations: { showPanel(state: State, defaultValue: boolean) { const tags state.index?.[state.storyId]?.tags ?? []; // Hide the panel on stories designed to showcase multiple variants or usage examples. if (tags.includes(showcase) || tags.includes(kitchensink)) { return false; } return defaultValue; }, }, });逐行拆解读取标签state.index?.[state.storyId]?.tags ?? []—— 使用可选链安全取值storyId不存在或tags缺失时回退为空数组避免抛错条件判断若当前 Story 带showcase或kitchensink标签直接返回false强制隐藏面板——这类 Story 通常是集中展示多个变体/使用示例的画廊页不需要 Controls 等调试面板回退默认其余 Story 返回defaultValue即完全尊重用户当前的显隐偏好不影响正常调试流程。要使用这一能力你需要先在对应 Story 的 CSF 文件中声明标签例如tags: [showcase]这与autodocs、test等 Storybook 内建标签机制一致Story 的元数据随后会被静态分析进state.index供 manager 侧读取。底层原理getShowPanelWithCustomisations如何工作从源码看manager-api 的布局模块 layout.ts 中面板显隐的自定义逻辑如下getShowPanelWithCustomisations(showPanel: boolean) { const state store.getState(); if (isFunction(state.layoutCustomisations.showPanel)) { return state.layoutCustomisations.showPanel(state, showPanel) ?? showPanel; } return showPanel; },可以提炼出三个关键机制调用时机Storybook 渲染 manager UI 时会先把当前面板是否显示作为showPanel传入再调用你在layoutCustomisations.showPanel中注册的回调??空值合并回调返回undefined时等价于不表态结果回退为传入的showPanel默认值这正是示例代码中非展示类 Story 返回defaultValue这一分支能在源码层面成立的原因未配置时的默认行为默认布局状态 layout.ts 中showPanel/showSidebar/showToolbar初始均为undefinedisFunction判断不通过时直接透传默认值保证不配置该功能时行为与旧版完全一致。同样的模式也应用于工具栏getShowToolbarWithCustomisations与侧边栏getNavSizeWithCustomisations通过将navSize置 0 来隐藏侧边栏。layoutCustomisations配置本身在setConfig初始化时与默认状态合并见 layout.ts你只需提供Partial的片段即可未提供的项保持默认。实战扩展与其他布局自定义组合使用showPanel常与showSidebar、showToolbar组合针对不同页面做差异化布局。仓库中提供了两个官方示例在 landing 页隐藏侧边栏storybook-manager-sidebar-hide-on-landing.md 展示了当storyId landing viewMode docs时返回false隐藏侧边栏因为该页面自带导航链接在 docs 页隐藏工具栏storybook-manager-toolbar-hide-on-docs.md 展示了当viewMode docs时隐藏工具栏。更完整的组合配置示例见 storybook-config-layout.md其中showSidebar、showToolbar、navSize、bottomPanelHeight、panelPosition、initialActive等参数一应俱全。通过 URL 参数临时控制除了配置代码Storybook 还支持 URL 查询参数对部分布局能力做运行时覆盖见 features-and-behavior.mdx配置项查询参数支持值全屏fulltrue、false显示侧边栏navtrue、false显示面板panelfalse、right、bottomselectedPaneladdonPanel任意面板 IDshowTabstabstrue—instrumentfalse、true—statuses分号分隔的状态值new、modified、related前缀!表示排除例如在浏览器地址栏追加?panelfalse即可临时隐藏面板适合快速验证效果无需改动配置文件。注意事项与最佳实践不要滥用隐藏能力官方文档特别警告showSidebar与showToolbar可以隐藏对 Storybook 功能至关重要的 UI 元素误用可能导致无法导航。隐藏侧边栏时必须确保当前页面提供替代的导航方式如 landing 页自带导航链接。showPanel相对安全但仍建议只针对明确的展示型 Story 生效优先使用defaultValue回退示例中命中标签返回false否则返回defaultValue的模式应当保持——这样不会覆盖用户手动开关面板的偏好属于对用户最友好的实现标签命名自洽showcase、kitchensink是示例中的约定标签实际项目中你可以在 CSF 里自定义任意标签名只要保证Story 中声明的标签与showPanel中检查的标签一致即可仓库自身的 kitchen-sink 类示例项目见 test-storybooks/portable-stories-kitchen-sink也体现了这类展示型 Story 集合的真实使用场景配置位置该配置属于 manager 侧应放在storybook/manager.js/storybook/manager.ts部分项目模板为.storybook/目录而不是preview配置文件因为addons与addons.setConfig均来自storybook/manager-api包。总结layoutCustomisations.showPanel为 Storybook 提供了上下文感知的面板显隐控制借助state.index与 Story 标签机制你可以精确地让展示型 Storyshowcase/kitchensink隐藏 addon 面板、回归纯净画布同时在其他 Story 上完全保留用户的默认偏好。其背后由 manager-api 布局模块的getShowPanelWithCustomisations与??回退语义支撑行为清晰可预期。配合showSidebar、showToolbar与 URL 参数你可以为不同的查看场景定制出真正贴合演示与调试需求的 Storybook 界面。【免费下载链接】storybookStorybook is the industry standard workshop for building, documenting, and testing UI components in isolation项目地址: https://gitcode.com/GitHub_Trending/st/storybook创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考