Storybook Addons API 实战：用 api.toggleFullscreen 精确控制界面全屏模式

Storybook Addons API 实战用 api.toggleFullscreen 精确控制界面全屏模式【免费下载链接】storybookStorybook is the industry standard workshop for building, documenting, and testing UI components in isolation项目地址: https://gitcode.com/GitHub_Trending/st/storybookStorybook 的 UI 由侧边栏nav、画布canvas与附加面板panel组成toggleFullscreen是 Storybook Addons API 中用于切换全屏预览模式的布局接口。它让 addon 作者可以在不依赖用户手动点击 UI 的情况下以编程方式隐藏侧边栏与底部/右侧面板让组件画布独占整个窗口——这是构建专注预览演示模式截图增强测试辅助等功能的常用入口。读完本文你将掌握api.toggleFullscreen(toggled?)的三种调用形态、其底层布局状态机的工作原理以及如何在自定义 addon 的注册回调中安全地控制全屏状态。一、API 概览官方文档中的最小示例Storybook 官方 addons-api 文档docs/addons/addons-api.mdx对它的定义只有一句话切换 Storybook UI 的全屏模式——传入true开启、false关闭、省略参数则切换当前状态。配套代码片段存放在 docs/_snippets/storybook-addons-api-togglefullscreen.md原文如下addons.register(my-organisation/my-addon, (api) { // Toggle fullscreen mode api.toggleFullscreen(); // Enable fullscreen api.toggleFullscreen(true); // Disable fullscreen api.toggleFullscreen(false); });这个片段同时展示了该 API 的三种核心调用方式调用形式行为api.toggleFullscreen()无参数取当前状态的相反值执行切换api.toggleFullscreen(true)显式进入全屏模式api.toggleFullscreen(false)显式退出全屏模式恢复常规布局所有调用都发生在addons.register(id, (api) { ... })的第二个参数回调中这正是 addon 接收 manager API 的约定入口参见 docs/addons/addons-api.mdx 中关于api与register的完整约定。二、在 addon 中应用从注册回调到触发时机api参数是 addon 与 Storybook manager 端 UI 通信的桥梁。实际使用中全屏切换很少像示例那样在注册瞬间直接触发而是绑定在 UI 事件上。常见的模式有在自定义 toolbar tool 的点击回调中切换、在 addon 面板按钮中切换、或在响应式/responsive 逻辑中监听某些全局条件后自动切换。典型注册写法如下延续官方注册约定addons.register(my-organisation/my-addon, ...)import { addons, types } from storybook/manager-api; addons.register(my-organisation/presentation-mode, (api) { // 进入 addon 面板时自动切到全屏退出时恢复 // 实际项目中通常通过 useAddonState / 事件回调驱动下面这类调用 // api.toggleFullscreen(true); });需要强调toggleFullscreen是幂等可重复调用的。当你显式传入布尔值时若目标状态与当前状态一致底层实现会直接返回当前布局、不做多余变更见下文源码分析因此可以在不确定当前状态时放心调用api.toggleFullscreen(true)。三、源码级原理layout 模块如何维护全屏状态要理解toggleFullscreen需要定位 Storybook manager 端的布局状态模块。接口声明位于 code/core/src/manager-api/modules/layout.ts 的SubAPI中/** * Toggles the fullscreen mode of the Storybook UI. * * param toggled - Optional boolean value to set the fullscreen mode to. If not provided, it will * toggle the current state. */ toggleFullscreen: (toggled?: boolean) void;同名实现位于同一文件的init中layout.ts。其逻辑可以概括为三步读取当前状态通过内部函数getIsFullscreen(state)判断当前是否处于全屏。该函数定义在 layout.ts判定标准非常直观const getIsFullscreen (state: State) { return !getIsNavShown(state) !getIsPanelShown(state); };即侧边栏navSize 0与面板底部面板高度或右侧面板宽度大于 0都被隐藏时才算全屏。这里隐含一个值得注意的设计全屏不是独立的布尔字段而是由布局尺寸推导出的派生状态。决定目标状态shouldFullscreen typeof nextState boolean ? nextState : !isFullscreen——这就是显式布尔优先、省略则取反的语义来源。写入布局尺寸进入全屏时把navSize、bottomPanelHeight、rightPanelWidth全部置为0退出全屏时恢复。关键细节recentVisibleSizes 记忆上次可见尺寸全屏的隐藏逻辑与退出恢复都依赖recentVisibleSizes。进入全屏前getRecentVisibleSizes定义于 layout.ts会把当前可见的navSize、bottomPanelHeight、rightPanelWidth快照保存下来退出全屏时则用这份快照把侧边栏与面板还原到全屏前的大小而不是重置为默认值。这正是用户全屏后再退出布局与之前一致体验的来源。代码中还有一个细节退出全屏恢复 nav 时使用state.singleStory ? 0 : state.layout.recentVisibleSizes.navSize。也就是说在 single-story单故事模式下侧边栏本身不可见因此退出全屏时 nav 仍保持为 0不会错误地弹出导航。此外store.setState(..., { persistence: session })表明布局变更会以会话级持久化记录session storage刷新后当前会话内布局状态保持一致。四、配套读取接口与相关布局 API官方在SubAPI中还暴露了只读配套方法getIsFullscreen()见 layout.ts它在模块初始化时被绑定为getIsFullscreen(store.getState())layout.ts。如果你的 addon 需要在切换前做条件判断可以这样组合addons.register(my-organisation/my-addon, (api) { // 仅在非全屏状态下自动进入全屏 if (!api.getIsFullscreen()) { api.toggleFullscreen(true); } });toggleFullscreen只是布局控制家族的一员同一SubAPI中还定义了这些互补接口均位于 layout.ts 的 JSDoc 与实现中API作用参数语义toggleFullscreen(toggled?)切换全屏省略切换、true开启、false关闭togglePanel(toggled?)显示/隐藏附加面板同上toggleNav(toggled?)显示/隐藏侧边栏同上移动端布局走抽屉状态toggleToolbar(toggled?)显示/隐藏工具栏同上togglePanelPosition(position?)切换面板位置bottom/right省略则互切从实现上看togglePanel、toggleNav与toggleFullscreen共享同一套尺寸归零 recentVisibleSizes快照/恢复的模式只是作用字段不同toggleFullscreen同时隐藏 nav 与 panel。因此理解toggleFullscreen的实现基本就等于理解了整套布局切换机制。五、与内置 UI 及快捷键模块的协同全屏并非 addon 独享能力Storybook 管理端 UI 本身也通过同一SubAPI触发它。在 code/core/src/manager/components/preview/Toolbar.tsx 中内置工具栏的 fullscreen tool 直接绑定toggle: api.toggleFullscreen其 tool id 为fullscreen。这意味着 addon API 与内置按钮走的是完全一致的状态通道——通过 API 切到全屏UI 上会呈现同等的布局结果。此外快捷键模块 code/core/src/manager-api/modules/shortcuts.ts 在响应相关按键时也会调用fullAPI.toggleFullscreen(...)部分场景显式传false以强制关闭全屏例如切换故事或进入其他视图模式时主动复位布局。从这些调用点可以推断toggleFullscreen(false)的显式关闭形态在框架内部被大量用作状态复位手段addon 作者在页面/路由切换等场景同样可以借助它做兜底复位。六、测试依据toggleFullscreen 的行为契约该 API 的行为由单元测试固化见 code/core/src/manager-api/tests/layout.test.ts。测试覆盖了以下契约可直接作为 addon 开发时的行为参考无参调用在进入/退出全屏之间往返切换双向对称toggleFullscreen(true)与toggleFullscreen(false)显式控制目标状态已处于全屏时再次请求全屏、或已退出时再次请求退出状态不发生多余变化幂等全屏期间隐藏的 nav/panel 在退出后通过recentVisibleSizes正确恢复getIsFullscreen返回的判定结果与布局尺寸一致。七、实战小结编写自定义 Storybook addon 需要控制 UI 布局时记住以下要点即可正确使用api.toggleFullscreen三种形态无参切换、true开启、false关闭调用位置在addons.register的(api) {...}回调中判定可查询配合api.getIsFullscreen()做条件化控制避免无谓的状态写入恢复有记忆全屏隐藏的是侧边栏与面板退出时依据recentVisibleSizes快照还原到进入前的尺寸与内置机制同源它驱动的是与工具栏 fullscreen 按钮、快捷键完全相同的布局状态因此结果表现一致、可预期。上述结论均可从官方 addons-api 文档、manager-api 布局模块源码 及对应 单元测试 中逐一验证读者可循此路径深入源码继续扩展自己的 addon 能力。【免费下载链接】storybookStorybook is the industry standard workshop for building, documenting, and testing UI components in isolation项目地址: https://gitcode.com/GitHub_Trending/st/storybook创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考