功能和行为

要控制 Storybook UI 的布局，您可以在 .storybook/manager.js 中使用 addons.setConfig。

.storybook/manager.ts

import { addons, type State } from 'storybook/manager-api';
 
addons.setConfig({
  navSize: 300,
  bottomPanelHeight: 300,
  rightPanelWidth: 300,
  panelPosition: 'bottom',
  enableShortcuts: true,
  showToolbar: true,
  theme: undefined,
  selectedPanel: undefined,
  initialActive: 'sidebar',
  layoutCustomisations: {
    showSidebar(state: State, defaultValue: boolean) {
      return state.storyId === 'landing' ? false : defaultValue;
    },
    showToolbar(state: State, defaultValue: boolean) {
      return state.viewMode === 'docs' ? false : defaultValue;
    },
  },
  sidebar: {
    showRoots: false,
    collapsedRoots: ['other'],
  },
  toolbar: {
    title: { hidden: false },
    zoom: { hidden: false },
    eject: { hidden: false },
    copy: { hidden: false },
    fullscreen: { hidden: false },
  },
});

下表详细说明了如何使用 API 值

名称	类型	描述	示例值
navSize	数字（像素）	显示故事列表的侧边栏的大小	`300`
bottomPanelHeight	数字（像素）	面板在底部位置时的尺寸	`200`
rightPanelWidth	数字（像素）	面板在右侧位置时的尺寸	`200`
panelPosition	字符串	显示附加面板的位置	`'bottom'` 或 `'right'`
enableShortcuts	布尔值	启用/禁用快捷键	`true`
showToolbar	布尔值	显示/隐藏工具栏	`true`
theme	对象	Storybook 主题，请参阅下一节	`undefined`
selectedPanel	字符串	选择附加面板的 ID	`'storybook/actions/panel'`
initialActive	字符串	在移动设备上选择默认激活的选项卡	`'sidebar'` 或 `'canvas'` 或 `'addons'`
layoutCustomisations	对象	布局自定义选项，见下文	`{ showSidebar: ({ viewMode }, defaultValue) => viewMode === 'docs' ? false : defaultValue` }`
sidebar	对象	侧边栏选项，见下文	`{ showRoots: false }`
toolbar	对象	使用插件 ID 修改工具栏中的工具	`{ fullscreen: { hidden: false } }`

以下选项可在 sidebar 命名空间下配置

名称	类型	描述	示例值
showRoots	布尔值	将顶级节点显示为侧边栏中的“根”	`false`
collapsedRoots	数组	默认视觉上折叠的根节点 ID 集合	`['misc', 'other']`
renderLabel	函数	为树节点创建自定义标签；必须返回一个 ReactNode	`(item, api) => {item.name}`

以下选项可在 toolbar 命名空间下配置

名称	类型	描述	示例值
[id]	字符串	切换特定工具栏项的可见性（例如 `title`、`zoom`）	`{ hidden: false }`

以下选项可在 layoutCustomisations 命名空间下配置

名称	类型	描述	示例值
showSidebar	函数	切换侧边栏的可见性	`({ storyId }, defaultValue) => storyId === 'landing' ? false : defaultValue`
showToolbar	函数	切换工具栏的可见性	`({ viewMode }, defaultValue) => viewMode === 'docs' ? false : defaultValue`

showSidebar 和 showToolbar 函数可用于隐藏 Storybook 功能所必需的 UI 部分。如果使用不当，可能会导致导航困难。隐藏侧边栏时，请确保显示的页面提供替代导航方式。

自定义 UI

Storybook 的 UI 高度可定制。其 API 和配置选项可通过 showSidebar、showPanel 和 showToolbar 函数进行访问，允许您控制侧边栏、附加面板和工具栏元素的显示方式。每个函数都允许您包含一些默认行为，并可以覆盖以根据您的需求自定义 UI。

覆盖侧边栏可见性

侧边栏位于屏幕左侧，包含搜索功能和导航菜单。用户可以通过键盘快捷键显示或隐藏它。如果您想在特定位置强制显示或隐藏侧边栏，可以在 layoutCustomisations 中定义一个 showSidebar 函数。以下是传递给此函数的可用参数以及如何使用它们的概述。

名称	类型	描述	示例值
path	字符串	正在显示的页面路径	`'/story/components-button--default'`
viewMode	字符串	当前页面是故事还是文档	`'docs'` 或 `'story'`
singleStory	布尔值	当前页面是否是组件的唯一故事	`true` 或 `false`
storyId	字符串	当前故事或文档页面的 ID	`'blocks-unstyled--docs'`
index	对象	包含每个故事静态分析元数据的索引	`{ 'blocks-unstyled--docs': { tags: ['autodocs'] } }`
layout	对象	当前布局状态	见下文
layout.isFullscreen	布尔值	预览画布是否处于全屏模式	`true` 或 `false`
layout.panelPosition	字符串	面板显示在预览的下方还是侧面	`'bottom'` 或 `'right'`
layout.showNav	布尔值	最终用户想要查看侧边栏的设置	`true` 或 `false`
layout.showPanel	布尔值	最终用户想要查看面板的设置	`true` 或 `false`
layout.showToolbar	布尔值	最终用户想要查看工具栏的设置	`true` 或 `false`

./storybook/manager.ts

import { addons, type State } from 'storybook/manager-api';
 
addons.setConfig({
  layoutCustomisations: {
    // Hide the sidebar on the landing page, which has its own nav links to other pages.
    showSidebar(state: State, defaultValue: boolean) {
      if (state.storyId === 'landing' && state.viewMode === 'docs') {
        return false;
      }
 
      return defaultValue;
    },
  },
});

如果您通过 showSidebar 隐藏侧边栏，请确保显示的页面提供替代导航方式。

配置附加面板

查看故事时，Storybook 会在 UI 的底部或右侧显示附加面板。该面板显示可用附加组件的 UI（例如，交互面板、可访问性测试面板或控件面板）。如果您想自定义附加面板何时出现，可以使用 showPanel 函数。下面列出了可用选项以及如何使用它们的概述。

名称	类型	描述	示例值
path	字符串	正在显示的页面路径	`'/story/components-button--default'`
viewMode	字符串	当前页面是故事还是文档	`'docs'` 或 `'story'`
singleStory	布尔值	当前页面是否是组件的唯一故事	`true` 或 `false`
storyId	字符串	当前故事或文档页面的 ID	`'blocks-unstyled--docs'`
index	对象	包含每个故事静态分析元数据的索引	`{ 'blocks-unstyled--docs': { tags: ['autodocs'] } }`
layout	对象	当前布局状态	见下文
layout.isFullscreen	布尔值	预览画布是否处于全屏模式	`true` 或 `false`
layout.panelPosition	字符串	面板显示在预览的下方还是侧面	`'bottom'` 或 `'right'`
layout.showNav	布尔值	最终用户想要查看侧边栏的设置	`true` 或 `false`
layout.showPanel	布尔值	最终用户想要查看面板的设置	`true` 或 `false`
layout.showToolbar	布尔值	最终用户想要查看工具栏的设置	`true` 或 `false`

./storybook/manager.ts

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;
    },
  },
});

默认情况下，Storybook 在 UI 顶部显示一个工具栏，允许您访问附加组件的菜单（例如，视口、背景）或自定义定义的菜单。但是，如果您想自定义工具栏的行为，可以使用 showToolbar 函数。下面列出了可用选项以及如何使用它们的概述。

名称	类型	描述	示例值
path	字符串	正在显示的页面路径	`'/story/components-button--default'`
viewMode	字符串	当前页面是故事还是文档	`'docs'` 或 `'story'`
singleStory	布尔值	当前页面是否是组件的唯一故事	`true` 或 `false`
storyId	字符串	当前故事或文档页面的 ID	`'blocks-unstyled--docs'`
index	对象	包含每个故事静态分析元数据的索引	`{ 'blocks-unstyled--docs': { tags: ['autodocs'] } }`
layout	对象	当前布局状态	见下文
layout.isFullscreen	布尔值	预览画布是否处于全屏模式	`true` 或 `false`
layout.panelPosition	字符串	面板显示在预览的下方还是侧面	`'bottom'` 或 `'right'`
layout.showNav	布尔值	最终用户想要查看侧边栏的设置	`true` 或 `false`
layout.showPanel	布尔值	最终用户想要查看面板的设置	`true` 或 `false`
layout.showToolbar	布尔值	最终用户想要查看工具栏的设置	`true` 或 `false`

./storybook/manager.ts

import { 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;
    },
  },
});

通过 URL 参数配置

您可以使用 URL 参数来配置一些可用功能

配置选项	查询参数	支持的值
enableShortcuts	`shortcuts`	`false`
--- (全屏)	`full`	`true`, `false`
--- (显示侧边栏)	`nav`	`true`, `false`
--- (显示面板)	`panel`	`false`, `'right'`, `'bottom'`
selectedPanel	`addonPanel`	任何面板 ID
showTabs	`tabs`	`true`
---	`instrument`	`false`, `true`

功能和行为

自定义 UI

覆盖侧边栏可见性

配置附加面板

配置工具栏

通过 URL 参数配置