Args

观看视频教程

Story 是一个组件，它带有一组参数，用于定义组件应如何渲染。“Args” 是 Storybook 用于在单个 JavaScript 对象中定义这些参数的机制。Args 可用于动态更改 props、slots、styles、inputs 等。它允许 Storybook 及其插件实时编辑组件。您*无需*修改底层组件代码即可使用 args。

当 arg 的值更改时，组件会重新渲染，从而允许您通过影响 args 的插件在 Storybook 的 UI 中与组件进行交互。

在简介中了解如何以及为何编写 stories。有关 args 工作原理的详细信息，请继续阅读。

Args 对象

`args` 对象可以在 story、组件和全局级别定义。它是一个 JSON 可序列化对象，由字符串键和匹配的有效值类型组成，可以传递到框架的组件中。

Story args

要定义单个 story 的 args，请使用 args CSF story 键

Button.stories.ts|tsx

import type { Meta, StoryObj } from '@storybook/react';
 
import { Button } from './Button';
 
const meta: Meta<typeof Button> = {
  component: Button,
};
 
export default meta;
type Story = StoryObj<typeof Button>;
 
export const Primary: Story = {
  args: {
    primary: true,
    label: 'Button',
  },
};

这些 args 仅适用于它们所附加的 story，尽管您可以通过 JavaScript 对象重用它们来重复使用它们

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 Primary: Story = {
  args: {
    primary: true,
    label: 'Button',
  },
};
 
export const PrimaryLongName: Story = {
  args: {
    ...Primary.args,
    label: 'Primary with a really long name',
  },
};

在上面的示例中，我们使用了 ES 2015 的对象展开特性。

组件 args

您还可以在组件级别定义 args；它们将应用于组件的所有 stories，除非您覆盖它们。为此，请在 default CSF 导出上使用 args 键

Button.stories.ts|tsx

import type { Meta } from '@storybook/react';
 
import { Button } from './Button';
 
const meta: Meta<typeof Button> = {
  component: Button,
  //👇 Creates specific argTypes
  argTypes: {
    backgroundColor: { control: 'color' },
  },
  args: {
    //👇 Now all Button stories will be primary.
    primary: true,
  },
};
 
export default meta;
type Story = StoryObj<typeof Button>;

全局 args

您还可以在全局级别定义 args；它们将应用于每个组件的 stories，除非您覆盖它们。为此，请在 preview.js|ts 的默认导出中定义 args 属性

.storybook/preview.ts

// Replace your-renderer with the renderer you are using (e.g., react, vue3, angular, etc.)
import { Preview } from '@storybook/your-renderer';
 
const preview: Preview = {
  // The default value of the theme arg for all stories
  args: { theme: 'light' },
};
 
export default preview;

对于全局 args 的大多数用途，全局变量是定义全局应用设置（例如主题）的更好工具。使用全局变量户能够使用工具栏菜单更改值。

Args 组合

您可以分离 story 的参数以在其他 stories 中进行组合。以下是如何为同一组件的多个 stories 组合 args 的方法。

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 Primary: Story = {
  args: {
    primary: true,
    label: 'Button',
  },
};
 
export const Secondary: Story = {
  args: {
    ...Primary.args,
    primary: false,
  },
};

如果您发现自己为组件的大多数 stories 重复使用相同的 args，则应考虑使用组件级别的 args。

在为从其他组件组装而成的复合组件编写 stories 时，Args 非常有用。复合组件通常将其参数不变地传递给其子组件，类似地，它们的 stories 可以是其子组件 stories 的组合。使用 args，您可以直接组合参数

Page.stories.ts|tsx

import type { Meta, StoryObj } from '@storybook/react';
 
import { Page } from './Page';
 
//👇 Imports all Header stories
import * as HeaderStories from './Header.stories';
 
const meta: Meta<typeof Page> = {
  component: Page,
};
 
export default meta;
type Story = StoryObj<typeof Page>;
 
export const LoggedIn: Story = {
  args: {
    ...HeaderStories.LoggedIn.args,
  },
};

Args 可以修改组件的任何方面

您可以在 stories 中使用 args 来配置组件的外观，类似于在应用程序中所做的操作。例如，以下是如何使用 footer arg 来填充子组件

Page.stories.ts|tsx

import type { Meta, StoryObj } from '@storybook/react';
 
import { Page } from './Page';
 
type PagePropsAndCustomArgs = React.ComponentProps<typeof Page> & { footer?: string };
 
const meta: Meta<PagePropsAndCustomArgs> = {
  component: Page,
  render: ({ footer, ...args }) => (
    <Page {...args}>
      <footer>{footer}</footer>
    </Page>
  ),
};
export default meta;
 
type Story = StoryObj<PagePropsAndCustomArgs>;
 
export const CustomFooter: Story = {
  args: {
    footer: 'Built with Storybook',
  },
};

通过 URL 设置 args

您还可以通过向 URL 添加 args 查询参数来覆盖活动 story 的初始 args 集。通常，您会使用 Controls 插件来处理此问题。例如，以下是如何在 Storybook 的 URL 中设置 size 和 style arg

?path=/story/avatar--default&args=style:rounded;size:100

作为防范 XSS 攻击的安全措施，URL 中提供的 arg 的键和值仅限于字母数字字符、空格、下划线和破折号。任何其他类型都将被忽略并从 URL 中删除，但您仍然可以将它们与 Controls 插件和在您的 story 中一起使用。

args 参数始终是一组用分号 ; 分隔的 key: value 对。值将被强制转换为它们各自的 argTypes（可能已自动推断出来）。支持对象和数组。特殊值 null 和 undefined 可以通过在前面加上感叹号 ! 来设置。例如，args=obj.key:val;arr[0]:one;arr[1]:two;nil:!null 将被解释为

{
  obj: { key: 'val' },
  arr: ['one', 'two'],
  nil: null
}

同样，特殊格式可用于日期和颜色。Date 对象将被编码为 !date(value)，其中 value 表示为 ISO 日期字符串。颜色被编码为 !hex(value)、!rgba(value) 或 !hsla(value)。请注意，rgb(a) 和 hsl(a) 在 URL 中不应包含空格或百分号。

通过 URL 指定的 Args 将扩展并覆盖在 story 上设置的 args 的任何默认值。

从 story 内部设置 args

交互式组件通常需要由其包含组件或页面控制，以响应事件、修改其状态并在 UI 中反映这些更改。例如，当用户切换开关组件时，应选中该开关，并且 Storybook 中显示的 arg 应反映该更改。为了实现这一点，您可以使用 @storybook/preview-api 导出的 useArgs API

my-component/component.stories.ts|tsx

import { StoryObj, Meta } from '@storybook/react';
import { useArgs } from '@storybook/preview-api';
import { Checkbox } from './checkbox';
 
const meta: Meta<typeof Checkbox> = {
  title: 'Inputs/Checkbox',
  component: Checkbox,
};
export default meta;
 
type Story = StoryObj<typeof Checkbox>;
 
export const Example: Story = {
  args: {
    isChecked: false,
    label: 'Try Me!',
  },
  /**
   * 👇 To avoid linting issues, it is recommended to use a function with a capitalized name.
   * If you are not concerned with linting, you may use an arrow function.
   */
  render: function Render(args) {
    const [{ isChecked }, updateArgs] = useArgs();
 
    function onChange() {
      updateArgs({ isChecked: !isChecked });
    }
 
    return <Checkbox {...args} onChange={onChange} isChecked={isChecked} />;
  },
};

映射到复杂的 arg 值

诸如 JSX 元素之类的复杂值无法序列化到管理器（例如，Controls 插件）或与 URL 同步。可以使用 argTypes 中的 mapping 属性将 Arg 值从简单字符串“映射”到复杂类型，以解决此限制。它适用于任何 arg，但在与 select 控件类型一起使用时最有意义。

Example.stories.ts|tsx

// Replace your-renderer with the renderer you are using (e.g., react, vue3, angular, etc.)
import type { Meta } from '@storybook/your-renderer';
 
import { Example } from './Example';
 
const meta: Meta<typeof Example> = {
  component: Example,
  argTypes: {
    label: {
      options: ['Normal', 'Bold', 'Italic'],
      mapping: {
        Bold: <b>Bold</b>,
        Italic: <i>Italic</i>,
      },
    },
  },
};
 
export default meta;

请注意，mapping 不必是详尽的。如果 arg 值不是 mapping 的属性，则将直接使用该值。mapping 中的键始终对应于 arg 值，而不是它们在 options 数组中的索引。

在插件中使用 args

如果您正在编写想要读取或更新 args 的插件，请使用 @storybook/manager-api 导出的 useArgs 钩子

my-addon/src/manager.js|ts

import { useArgs } from '@storybook/manager-api';
 
const [args, updateArgs, resetArgs] = useArgs();
 
// To update one or more args:
updateArgs({ key: 'value' });
 
// To reset one (or more) args:
resetArgs((argNames: ['key']));
 
// To reset all args
resetArgs();