特性和行为

要控制 Storybook 用户界面的布局，您可以在您的 .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) => <abbr title="...">{item.name}</abbr>`

以下选项可在 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。如果使用不当，它们可能导致无法导航。隐藏侧边栏时，请确保显示的页面提供了替代的导航方式。

自定义用户界面

Storybook 的用户界面是高度可定制的。通过 showSidebar 和 showToolbar 函数提供的 API 和配置选项，您可以控制侧边栏和工具栏元素的显示方式。这两个函数都允许您包含一些默认行为，并且可以被覆盖以根据您的需要自定义用户界面。

覆盖侧边栏可见性

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

名称	类型	描述	示例值
path	字符串	正在显示的页面路径	`'/story/components-button--default'`
viewMode	字符串	当前页面是故事 (story) 还是文档 (docs)	`'docs'` 或 `'story'`
singleStory	布尔值	当前页面是否是组件的唯一故事 (story)	`true` 或 `false`
storyId	字符串	当前故事 (story) 或文档 (docs) 页面的 ID	`'blocks-blocks-unstyled--docs'`
layout	对象	当前布局状态	参见下文
layout.isFullscreen	布尔值	预览画布是否处于全屏模式	`true` 或 `false`
layout.panelPosition	字符串	面板显示在预览下方还是侧面	`'bottom'` 或 `'right'`
layout.showNav	布尔值	最终用户是否希望看到侧边栏的设置	`true` 或 `false`
layout.showPanel	布尔值	最终用户是否希望看到面板的设置	`true` 或 `false`
layout.showSidebar	布尔值	最终用户是否希望看到侧边栏的设置	`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 顶部显示一个工具栏，允许您访问插件（例如视口、背景）或自定义菜单。但是，如果您想自定义工具栏的行为，可以使用 showToolbar 函数。下文列出了可用的选项以及如何使用它们的概述。

名称	类型	描述	示例值
path	字符串	正在显示的页面路径	`'/story/components-button--default'`
viewMode	字符串	当前页面是故事 (story) 还是文档 (docs)	`'docs'` 或 `'story'`
singleStory	布尔值	当前页面是否是组件的唯一故事 (story)	`true` 或 `false`
storyId	字符串	当前故事 (story) 或文档 (docs) 页面的 ID	`'blocks-blocks-unstyled--docs'`
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	`快捷键`	`false`
--- (全屏)	`full`	`true`, `false`
--- (显示侧边栏)	`nav`	`true`, `false`
--- (显示面板)	`panel`	`false`, `'right'`, `'bottom'`
selectedPanel	`addonPanel`	任何面板 ID
showTabs	`tabs`	`true`
---	`instrument`	`false`, `true`

特性和行为

自定义用户界面

覆盖侧边栏可见性

配置工具栏

通过 URL 参数配置