描述

Description 块显示从各自的 JSDoc 注释中获得的组件、故事或元数据的描述。

¥The Description block displays the description for a component, story, or meta, obtained from their respective JSDoc comments.

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

描述

¥Description

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

Description 配置了以下属性：

¥Description is configured with the following props:

of

类型：故事导出或 CSF 文件导出

¥Type: Story export or CSF file exports

指定从哪里提取描述。它可以指向故事或元，具体取决于你想要显示的描述。

¥Specifies where to pull the description from. It can either point to a story or a meta, depending on which description you want to show.

描述从 JSDoc 注释或参数中提取，并以 markdown 形式渲染。有关更多详细信息，请参阅 编写描述。

¥Descriptions are pulled from the JSDoc comments or parameters, and they are rendered as markdown. See Writing descriptions for more details.

编写描述

¥Writing descriptions

有多个地方可以编写组件/故事的描述，具体取决于你想要实现的目标。描述可以在故事级别编写，以描述组件的每个故事，也可以在元或组件级别编写，以一般性描述组件。

¥There are multiple places to write the description of a component/story, depending on what you want to achieve. Descriptions can be written at the story level to describe each story of a component, or they can be written at the meta or component level to describe the component in general.

描述可以写成故事、元或组件上方的 JSDoc 注释。或者，它们也可以在 parameters 中指定。要通过参数而不是注释来描述故事，请将其添加到 parameters.docs.description.story；要描述元/组件，请将其添加到 parameters.docs.description.component。

¥Descriptions can be written as JSDoc comments above stories, meta, or components. Alternatively they can also be specified in parameters. To describe a story via parameters instead of comments, add it to parameters.docs.description.story; to describe meta/component, add it to parameters.docs.description.component.

我们建议使用 JSDoc 注释进行描述，并且仅在由于某种原因无法编写注释或你希望 Storybook 中显示的描述与注释不同的情况下使用 parameters.docs.description.X 属性。注释提供了更好的写作体验，因为你不必担心缩进，而且对于正在探索故事/组件源的其他开发者来说，它们更容易被发现。

¥We recommend using JSDoc comments for descriptions, and only use the parameters.docs.description.X properties in situations where comments are not possible to write for some reason, or where you want the description shown in Storybook to be different from the comments. Comments provide a better writing experience as you don’t have to worry about indentation, and they are more discoverable for other developers that are exploring the story/component sources.

记录故事时，在 of 属性中引用故事导出（见下文），描述块将按以下顺序查找描述：

¥When documenting a story, reference a story export in the of prop (see below) and the Description block will look for descriptions in the following order:

1. parameters.docs.description.story 在故事中

   ¥parameters.docs.description.story in the story

2. 故事上方的 JSDoc 注释

   ¥JSDoc comments above the story

记录组件时，在 of 属性中引用元导出（见下文），描述块将按以下顺序查找描述：

¥When documenting a component, reference a meta export in the of prop (see below) and the Description block will look for descriptions in the following order:

1. parameters.docs.description.component 在元数据中

   ¥parameters.docs.description.component in the meta

2. 元上方的 JSDoc 注释

   ¥JSDoc comments above the meta

3. 组件上方的 JSDoc 注释

   ¥JSDoc comments above the component

此流程为你提供了覆盖每个场景描述的强大方法。请看以下示例：

¥This flow gives you powerful ways to override the description for each scenario. Take the following example:

// Button.jsx
 
/**
 
 * # The Button component
 
 * Shows a button
 */
export const Button = () => <button>Click me</button>;

// Replace your-framework with the name of your framework
import type { Meta, StoryObj } from '@storybook/your-framework';
 
import { Button } from './Button';
 
/**
 * # Button stories
 * These stories showcase the button
 */
const meta: Meta<typeof Button> = {
  component: Button
  parameters: {
    docs: {
      description: {
        component: 'Another description, overriding the comments'
      },
    },
  },
};
 
export default meta;
type Story = StoryObj<typeof Button>;
 
/**
 * # Primary Button
 * This is the primary button
 */
export const Primary: Story = {
  parameters: {
    docs: {
      description: {
        story: 'Another description on the story, overriding the comments'
      },
    },
  },
};

{/* ButtonDocs.mdx */}
 
import { Meta, Description } from '@storybook/blocks';
import * as ButtonStories from './Button.stories';
 
<Meta of={ButtonStories} />
 
{/* Shows the description for the default export (the meta).
    If that didn't have any comments, it would show the 
    comments from the component instead */}
<Description of={ButtonStories} />
 
{/* Shows the description for the Primary export */}
<Description of={ButtonStories.Primary} />