Storybook 自定义 Preview 参数：在 `.storybook/preview.*` 中配置 backgrounds 等全局参数

Storybook 自定义 Preview 参数：在.storybook/preview.*中配置 backgrounds 等全局参数

【免费下载链接】storybookStorybook is the industry standard workshop for building, documenting, and testing UI components in isolation项目地址: https://gitcode.com/GitHub_Trending/st/storybook

导读

parameters是 Storybook 控制组件渲染行为的核心机制，而.storybook/preview.*文件正是定义全局参数的入口。本文以官方案例storybook-preview-custom-params为骨架，完整讲解如何在 Preview 文件中自定义backgrounds参数（自定义背景色列表），并覆盖 CSF 3、CSF Next 两种编写风格在 JS/TS、React/Vue/Angular/Web Components 各框架下的写法，同时结合仓库源码揭示参数在底层如何被读取、合并与生效，帮助你写出类型安全、可维护的全局 Preview 配置。

为什么需要自定义 Preview 参数

Storybook 的parameters是静态的、树状结构的元数据，用于配置每个 story 的渲染行为（例如背景色、视口、工具栏状态等）。parameters支持继承合并：定义在.storybook/preview.*中的参数作用于所有 story，可以被组件级（meta）和 story 级参数逐层覆盖。

backgrounds是 Storybook 官方内置功能，默认自带 light 和 dark 两种背景。通过自定义 Preview 参数，你可以：

• 替换或扩充项目统一的背景色列表，让所有组件在预设背景下预览；
• 为团队建立统一的视觉检查基线（例如品牌色背景）；
• 结合globals/initialGlobals为整个项目设定初始背景。

官方文档 Backgrounds 中也明确推荐用backgrounds参数在.storybook/preview.*中配置自己的颜色集合，并指向了 configure-story-rendering 与 parameters 两份参考文档。

完整配置示例（原文档核心）

原文档storybook-preview-custom-params.md（位于 docs/_snippets/storybook-preview-custom-params.md）给出了在 Preview 文件中自定义背景色列表的完整代码。其核心是backgrounds.values：

export default { parameters: { backgrounds: { values: [ { name: 'red', value: '#f00' }, { name: 'green', value: '#0f0' }, ], }, }, };

对应带类型标注的 TS 版本：

// Replace your-framework with the framework you are using, e.g. react-vite, nextjs, vue3-vite, etc. import type { Preview } from '@storybook/your-framework'; const preview: Preview = { parameters: { backgrounds: { values: [ { name: 'red', value: '#f00' }, { name: 'green', value: '#0f0' }, ], }, }, }; export default preview;

参数结构说明

backgrounds.values是背景色数组，每个元素是一个对象：

在实际项目中，更常见的做法是使用options对象形式（键值映射），来自 addon-backgrounds-options-in-preview.md：

// .storybook/preview.ts const preview: Preview = { parameters: { backgrounds: { options: { // 默认选项 dark: { name: 'Dark', value: '#333' }, light: { name: 'Light', value: '#F7F9F2' }, // 自定义选项 maroon: { name: 'Maroon', value: '#400' }, }, }, }, initialGlobals: { // 设置初始背景色 backgrounds: { value: 'light' }, }, }; export default preview;

无论是values（数组）还是options（映射表），它们都会在运行时被归一到以name为键的BackgroundMap中消费（见下文源码分析）。

CSF Next 风格：使用definePreview

definePreview是 CSF Next 实验性语法中定义 Preview 配置的入口函数，相比直接导出对象，它能提供完整的类型推导。原文档覆盖了 React、Vue3、Angular、Web Components 四个渲染器，导入路径随框架而异：

React（@storybook/your-framework，即 react-vite / nextjs / nextjs-vite 等）：

// Replace your-framework with the framework you are using (e.g., react-vite, nextjs, nextjs-vite) import { definePreview } from '@storybook/your-framework'; export default definePreview({ parameters: { backgrounds: { values: [ { name: 'red', value: '#f00' }, { name: 'green', value: '#0f0' }, ], }, }, });

Vue3（@storybook/vue3-vite）：

import { definePreview } from '@storybook/vue3-vite'; export default definePreview({ parameters: { backgrounds: { values: [ { name: 'red', value: '#f00' }, { name: 'green', value: '#0f0' }, ], }, }, });

Angular（@storybook/angular）：

import { definePreview } from '@storybook/angular'; export default definePreview({ parameters: { backgrounds: { values: [ { name: 'red', value: '#f00' }, { name: 'green', value: '#0f0' }, ], }, }, });

Web Components（@storybook/web-components-vite）：

import { definePreview } from '@storybook/web-components-vite'; export default definePreview({ parameters: { backgrounds: { values: [ { name: 'red', value: '#f00' }, { name: 'green', value: '#0f0' }, ], }, }, });

若项目未启用 CSF Next（该语法标注为实验性），继续使用 CSF 3 的export default { parameters: {...} }或const preview: Preview = {...}写法即可，两种方式在功能上等价。

各框架导入路径速查

JS 版本写法与 TS 相同，只是去掉类型标注：

import { definePreview } from '@storybook/vue3-vite'; export default definePreview({ parameters: { backgrounds: { values: [ { name: 'red', value: '#f00' }, { name: 'green', value: '#0f0' }, ], }, }, });

底层实现：backgrounds参数如何被读取与生效

参数类型定义（types.ts）

背景功能的所有参数结构定义在 code/core/src/backgrounds/types.ts，其中BackgroundsParameters明确了可配置项：

• default：默认背景色名称；
• disable：布尔值，关闭该功能（false表示启用）；
• grid：网格配置{ cellAmount, cellSize, opacity, offsetX?, offsetY? }；
• options：BackgroundMap，即Record<string, Background>，Background为{ name: string; value: string }。

本文配置的values数组在渲染阶段会被归一到该options映射中供查询。

默认参数与全局状态（preview.ts）

code/core/src/backgrounds/preview.ts 通过definePreviewAddon注册背景功能，并给出了默认参数：

const parameters = { [PARAM_KEY]: { grid: { cellSize: 20, opacity: 0.5, cellAmount: 5, }, disable: false, }, }; const initialGlobals: Record<string, GlobalState> = { [PARAM_KEY]: { value: undefined, grid: false }, };

由此可见：即使你不写任何配置，Storybook 也会提供默认网格参数（cellSize: 20、opacity: 0.5、cellAmount: 5）和初始全局状态（无选中背景、不显示网格）。你在 Preview 中传入的backgrounds.values会与这些默认参数合并。

装饰器如何应用颜色（decorator.ts）

真正把背景色渲染到页面上的是装饰器withBackgroundAndGrid（code/core/src/backgrounds/decorator.ts）：

const { options = DEFAULT_BACKGROUNDS, disable, grid = defaultGrid, } = (parameters[PARAM_KEY] || {}) as NonNullable<BackgroundsParameters['backgrounds']>; const data = globals[PARAM_KEY] || {}; const backgroundName: string | undefined = typeof data === 'string' ? data : data?.value; const item = backgroundName ? options[backgroundName] : undefined; const value = typeof item === 'string' ? item : item?.value || 'transparent';

关键逻辑：

1. 从context.parameters[PARAM_KEY]中取出你配置的backgrounds参数（未配置时使用DEFAULT_BACKGROUNDS）；
2. 从context.globals[PARAM_KEY]中读取当前选中的背景名（支持字符串或{ value, grid }对象两种形态）；
3. 用背景名在options（由values归一而来）中查找对应项，最终取item.value作为 CSS 背景色；
4. 若找不到匹配项，回退为'transparent'。

也就是说，你在 Preview 中配置的values数组，最终会成为工具栏背景下拉列表的选项来源，并决定globals.backgrounds.value对应的实际颜色。

常量与事件（constants.ts）

code/core/src/backgrounds/constants.ts 定义了该功能的参数键：

export const ADDON_ID = 'storybook/background'; export const PARAM_KEY = 'backgrounds'; export const GRID_PARAM_KEY = 'grid';

这就是为什么配置必须写在backgrounds命名空间下——所有相关参数和 globals 都挂载在此键名下。

进阶：继承、禁用与网格

除了在 Preview 中做全局配置，backgrounds参数还支持更细粒度的控制（详见 backgrounds.mdx）：

• 按组件/按 story 覆盖：通过参数继承机制，在 meta 或 story 中重新定义backgrounds.options，即可只调整某个组件或单个故事的背景集合；
• 禁用背景：设置backgrounds: { disable: true }可关闭背景功能，disable支持在项目、组件、story 不同层级覆盖（例如项目级禁用后，在个别 story 中重新启用）；
• 网格：backgrounds.grid支持cellAmount（次网格线尺寸，默认5）、cellSize（主网格线尺寸，默认20）、opacity、offsetX、offsetY等属性，用于检查组件对齐；
• 固定背景：在 story 的globals.backgrounds中指定value后，该背景会被固定，工具栏无法再切换——适合需要保证某些 story 始终在特定背景下渲染的场景。

小结

storybook-preview-custom-params展示的是 Storybook 中最常用的全局参数配置模式：在.storybook/preview.*中通过parameters.backgrounds.values定义项目统一的背景色列表。无论是 CSF 3 的对象导出，还是 CSF Next 的definePreview，配置内容一致；结合 types.ts 中的类型定义、preview.ts 中的默认参数与 decorator.ts 中的消费逻辑，你可以完全掌控背景色在 Storybook 中的行为，并以此为模板举一反三地配置其他全局参数。

【免费下载链接】storybookStorybook is the industry standard workshop for building, documenting, and testing UI components in isolation项目地址: https://gitcode.com/GitHub_Trending/st/storybook