故事

Watch a video tutorial

故事（组件测试）是 Storybook 的基本构建块。

¥Stories (component tests) are Storybook's fundamental building blocks.

在 Storybook Docs 中，你可以在 MDX 文件的上下文中从 CSF 文件渲染任何故事，并使用 Story 块应用所有注释（参数、args、加载器、装饰器、播放函数）。

¥In Storybook Docs, you can render any of your stories from your CSF files in the context of an MDX file with all annotations (parameters, args, loaders, decorators, play function) applied using the Story block.

通常你希望使用 Canvas 块来渲染带有周围边框和源块的故事，但你可以使用 Story 块来渲染故事。

¥Typically you want to use the Canvas block to render a story with a surrounding border and the source block, but you can use the Story block to render just the story.

Screenshot of Story block

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

故事

¥Story

import { Story } from '@storybook/blocks';

Configuring with props and parameters

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

¥ℹ️ Like most blocks, the Story 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.story.

以下 autoplay 配置是等效的：

¥The following autoplay 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: {
      story: { autoplay: true },
    },
  },
};

{/* ButtonDocs.mdx */}
 
<Story of={ButtonStories.Basic} autoplay />

上面的示例在 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.

`autoplay`

类型：boolean

¥Type: boolean

默认：parameters.docs.story.autoplay

¥Default: parameters.docs.story.autoplay

确定故事的播放函数是否运行。

¥Determines whether a story's play function runs.

由于所有故事都在文档条目中同时渲染，因此播放函数可以执行可以相互交互的任意操作（例如窃取焦点或滚动屏幕）。因此，默认情况下，故事不会在文档模式下运行播放函数。

¥Because all stories render simultaneously in docs entries, play functions can perform arbitrary actions that can interact with each other (such as stealing focus or scrolling the screen). For that reason, by default, stories do not run play functions in docs mode.

但是，如果你知道你的播放函数在文档中“安全”运行，则可以使用此属性自动运行它。

¥However, if you know your play function is “safe” to run in docs, you can use this prop to run it automatically.

如果故事使用 mount 在其播放函数中，除非将 autoplay 设置为 true，否则它将不会在文档中渲染。

¥If a story uses mount in its play function, it will not render in docs unless autoplay is set to true.

`height`

类型：string

¥Type: string

默认：parameters.docs.story.height

¥Default: parameters.docs.story.height

在 iframe 或内联中渲染故事时，设置最小高度（请注意，对于 iframe，这是实际高度）。这将覆盖 iframe 的 parameters.docs.story.iframeHeight。

¥Set a minimum height (note for an iframe this is the actual height) when rendering a story in an iframe or inline. This overrides parameters.docs.story.iframeHeight for iframes.

`inline`

类型：boolean

¥Type: boolean

默认：parameters.docs.story.inline 或 true（用于支持的框架）

¥Default: parameters.docs.story.inline or true (for supported frameworks)

确定故事是渲染 inline（与其他文档内容在同一浏览器框架中）还是在 iframe 中渲染。

¥Determines whether the story is rendered inline (in the same browser frame as the other docs content) or in an iframe.

将 inline 选项设置为 false 将阻止关联的 controls 更新文档页面中的故事。这是当前实现的已知限制，将在未来的版本中解决。

¥Setting the inline option to false will prevent the associated controls from updating the story within the documentation page. This is a known limitation of the current implementation and will be addressed in a future release.

`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, Story } 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 */}
<Story of={HeaderStories.LoggedIn} meta={HeaderStories} />

`of`

类型：故事导出

¥Type: Story export

指定 Story 块渲染哪个故事。如果没有定义 of 并且 MDX 文件是 attached，则将渲染主要（第一个）故事。

¥Specifies which story is rendered by the Story block. If no of is defined and the MDX file is attached, the primary (first) story will be rendered.

Watch a video tutorial