Docs
Storybook Docs

画布

Watch a video tutorial

Canvas 块是 Story 的封装器，具有一个工具栏，可让你与其内容进行交互，同时自动提供所需的 Source 片段。

¥The Canvas block is a wrapper around a Story, featuring a toolbar that allows you to interact with its content while automatically providing the required Source snippets.

Screenshot of Canvas block

在 MDX 中使用 Canvas 块时，它使用 of prop 引用故事：

¥When using the Canvas block in MDX, it references a story with the of prop:

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

在以前版本的 Storybook 中，可以将任意组件作为子组件传递给 Canvas。这已被弃用，Canvas 块现在仅支持单个故事。

¥In previous versions of Storybook it was possible to pass in arbitrary components as children to Canvas. That is deprecated and the Canvas block now only supports a single story.

画布

¥Canvas

import { Canvas } from '@storybook/blocks';
Configuring with props and parameters

ℹ️ 与大多数块一样，Canvas 块在 MDX 中使用 props 配置。其中许多属性的默认值来自块命名空间 parameters.docs.canvas 中相应的 参数。

¥ℹ️ Like most blocks, the Canvas block is configured with props in MDX. Many of those props derive their default value from a corresponding parameter in the block's namespace, parameters.docs.canvas.

以下 sourceState 配置是等效的：

¥The following sourceState configurations are equivalent:

Button.stories.ts|tsx
// Replace your-framework with the name of your framework
import type { Meta, StoryObj } from '@storybook/your-framework';
 
import { Button } from './Button';
 
const meta: Meta<typeof Button> = {
  component: Button,
};
 
export default meta;
type Story = StoryObj<typeof Button>;
 
export const Basic: Story = {
  parameters: {
    docs: {
      canvas: { sourceState: 'shown' },
    },
  },
};
{/* ButtonDocs.mdx */}
 
<Canvas of={ButtonStories.Basic} sourceState="shown" />

上面的示例在 story 级别应用了参数，但它也可以在 component（或元）级别或 project 级别应用。

¥The example above applied the parameter at the story level, but it could also be applied at the component (or meta) level or project level.

additionalActions

类型：

¥Type:

Array<{
  title: string | JSX.Element;
  className?: string;
  onClick: () => void;
  disabled?: boolean;
}>;

默认：parameters.docs.canvas.additionalActions

¥Default: parameters.docs.canvas.additionalActions

提供任何其他自定义操作以显示在右下角。这些是简单的按钮，可以执行你在 onClick 函数中指定的任何操作。

¥Provides any additional custom actions to show in the bottom right corner. These are simple buttons that do anything you specify in the onClick function.

{/* ButtonDocs.mdx */}
 
import { Meta, Story, Canvas, SourceState } from '@storybook/blocks';
import * as ButtonStories from './Button.stories';
 
<Meta of={ButtonStories} />
 
{/* with an additional action */}
<Canvas
  additionalActions={[
    {
      title: 'Open in GitHub',
      onClick: () => {
        window.open(
          'https://github.com/storybookjs/storybook/blob/next/code/ui/blocks/src/examples/Button.stories.tsx',
          '_blank'
        );
      },
    }
  ]}
  of={ButtonStories.Primary}
/>

className

类型：string

¥Type: string

默认：parameters.docs.canvas.className

¥Default: parameters.docs.canvas.className

为预览元素提供 HTML 类，用于自定义样式。

¥Provides HTML class(es) to the preview element, for custom styling.

layout

类型：'centered' | 'fullscreen' | 'padded'

¥Type: 'centered' | 'fullscreen' | 'padded'

默认：parameters.layout 或 parameters.docs.canvas.layout 或 'padded'

¥Default: parameters.layout or parameters.docs.canvas.layout or 'padded'

指定画布应如何布局故事。

¥Specifies how the canvas should layout the story.

  • centered：将故事置于画布的中心

    ¥centered: Center the story within the canvas

  • padded:(默认)为故事添加填充

    ¥padded: (default) Add padding to the story

  • 全屏：按原样显示故事，无填充

    ¥fullscreen: Show the story as-is, without padding

除了 parameters.docs.canvas.layout 属性或 layout 属性之外，Canvas 块还将尊重在常规故事视图中定义 故事如何布局 的 parameters.layout 值。

¥In addition to the parameters.docs.canvas.layout property or the layout prop, the Canvas block will respect the parameters.layout value that defines how a story is laid out in the regular story view.

meta

类型：CSF 文件导出

¥Type: CSF file exports

指定与故事关联的 CSF 文件。

¥Specifies the CSF file to which the story is associated.

你可以使用 meta 属性从尚未附加到 MDX 文件（通过 Meta）的 CSF 文件渲染故事。传递 CSF 文件中的完整导出集（不是默认导出！）。

¥You can render a story from a CSF file that you haven’t attached to the MDX file (via Meta) by using the meta prop. Pass the full set of exports from the CSF file (not the default export!).

{/* ButtonDocs.mdx */}
 
import { Meta, Canvas } from '@storybook/blocks';
import * as ButtonStories from './Button.stories';
import * as HeaderStories from './Header.stories';
 
<Meta of={ButtonStories} />
 
{/* Although this MDX file is largely concerned with Button,
    it can render Header stories too */}
<Canvas of={HeaderStories.LoggedIn} meta={HeaderStories} />

of

类型：故事导出

¥Type: Story export

指定显示哪个故事的来源。

¥Specifies which story's source is displayed.

source

类型：SourceProps['code'] | SourceProps['format'] | SourceProps['language'] | SourceProps['type']

¥Type: SourceProps['code'] | SourceProps['format'] | SourceProps['language'] | SourceProps['type']

指定传递给内部 Source 块的属性。有关更多信息，请参阅 Source Doc Block documentation。

¥Specifies the props passed to the inner Source block. For more information, see the Source Doc Block documentation.

dark 属性被忽略，因为当 Source 块作为 Canvas 块的一部分显示时，它始终以夜间模式渲染。

¥The dark prop is ignored, as the Source block is always rendered in dark mode when shown as part of a Canvas block.

sourceState

类型：'hidden' | 'shown' | 'none'

¥Type: 'hidden' | 'shown' | 'none'

默认：parameters.docs.canvas.sourceState 或 'hidden'

¥Default: parameters.docs.canvas.sourceState or 'hidden'

指定源面板的初始状态。

¥Specifies the initial state of the source panel.

  • 隐藏：默认情况下，源面板是隐藏的

    ¥hidden: the source panel is hidden by default

  • shown:默认情况下显示源面板

    ¥shown: the source panel is shown by default

  • none:源面板不可用，并且不会渲染显示它的按钮

    ¥none: the source panel is not available and the button to show it is not rendered

story

类型：StoryProps['inline'] | StoryProps['height'] | StoryProps['autoplay']

¥Type: StoryProps['inline'] | StoryProps['height'] | StoryProps['autoplay']

指定传递给内部 Story 块的属性。有关更多信息，请参阅 Story Doc Block documentation。

¥Specifies the props passed to the inner Story block. For more information, see the Story Doc Block documentation.

withToolbar

类型：boolean

¥Type: boolean

默认：parameters.docs.canvas.withToolbar

¥Default: parameters.docs.canvas.withToolbar

确定是否渲染包含与故事交互的工具的工具栏。

¥Determines whether to render a toolbar containing tools to interact with the story.