加入直播:周四,美国东部时间上午 11 点,Storybook 9 发布及 AMA 问答
文档
Storybook Docs

源码

The Source block is used to render a snippet of source code directly.

Screenshot of Source block

ButtonDocs.mdx
import { Meta, Source } from '@storybook/addon-docs/blocks';
import * as ButtonStories from './Button.stories';
 
<Meta of={ButtonStories} />
 
<Source of={ButtonStories.Primary} />

源码

import { Source } from '@storybook/addon-docs/blocks';
使用 props parameters 进行配置

ℹ️ 与大多数块一样,Source 块在 MDX 中使用 props 进行配置。其中许多 props 的默认值来自于块命名空间 parameters.docs.source 中的对应 参数

以下 language 配置是等效的

Button.stories.ts|tsx
// Replace your-framework with the framework you are using, e.g. react-vite, nextjs, vue3-vite, etc.
import type { Meta, StoryObj } from '@storybook/your-framework';
 
import { Button } from './Button';
 
const meta = {
  component: Button,
} satisfies Meta<typeof Button>;
 
export default meta;
type Story = StoryObj<typeof meta>;
 
export const Basic: Story = {
  parameters: {
    docs: {
      source: { language: 'tsx' },
    },
  },
};
ButtonDocs.mdx
<Source of={ButtonStories.Basic} language="tsx" />

上面的示例在 story 级别应用了参数,但它也可以在 组件(或 meta)级别或 项目 级别应用。

code

类型: string

默认值: parameters.docs.source.code

提供要渲染的源代码。

ButtonDocs.mdx
import { Meta, Source } from '@storybook/addon-docs/blocks';
import * as ButtonStories from './Button.stories';
 
<Meta of={ButtonStories} />
 
<Source code={`const thisIsCustomSource = true;
if (isSyntaxHighlighted) {
  console.log('syntax highlighting is working');
}`} />

dark

类型: boolean

默认值: parameters.docs.source.dark

确定片段是否以深色模式渲染。

仅当 Source 块独立渲染时,才支持浅色模式。当作为 Canvas的一部分渲染时(就像在 autodocs 中一样),它将始终使用深色模式。

excludeDecorators

类型: boolean

默认值: parameters.docs.source.excludeDecorators

确定源代码片段中是否渲染 decorators

language

类型

'jsextra' | 'jsx' | 'json' | 'yml' | 'md' | 'bash' | 'css' | 'html' | 'tsx' | 'typescript' | 'graphql'

默认值: parameters.docs.source.language'jsx'

指定用于语法高亮的语言。

of

类型: Story 导出

指定渲染哪个 story 的源代码。

transform

类型: (code: string, storyContext: StoryContext) => string | Promise<string>

默认值: parameters.docs.source.transform

一个异步函数,用于根据原始源代码和任何必要的 story 上下文,在渲染之前动态转换源代码。返回的字符串按原样显示。如果同时指定了 codetransform,则 transform 将被忽略。

.storybook/preview.js|ts|jsx|tsx
export default {
  parameters: {
    docs: {
      source: {
        transform: async (source) => {
          const prettier = await import('prettier/standalone');
          const prettierPluginBabel = await import('prettier/plugins/babel');
          const prettierPluginEstree = await import('prettier/plugins/estree');
 
          return prettier.format(source, {
            parser: 'babel',
            plugins: [prettierPluginBabel, prettierPluginEstree],
          });
        },
      },
    },
  },
};

此示例展示了如何使用 Prettier 格式化文档中的所有源代码片段。transform 函数通过预览配置全局应用,确保所有 stories 的代码格式一致。

type

类型: 'auto' | 'code' | 'dynamic'

默认值: parameters.docs.source.type'auto'

指定如何渲染源代码。

  • **auto**: 如果 story 的 render 函数接受 args 输入并且当前使用的框架支持 **dynamic**,则与 **dynamic** 相同;否则与 **code** 相同
  • **code**: 渲染 code prop 的值,否则渲染静态 story 源代码
  • **dynamic**: 渲染带有动态更新的 arg 值的 story 源代码

请注意,动态片段仅在 story 使用 args 并且该 story 的 StorySource 块一起渲染时才有效。