操作

actions 插件用于显示故事中事件处理程序（回调）参数接收的数据。

¥The actions addon is used to display data received by event handler (callback) arguments in your stories.

操作参数

¥Action args

操作通过为你的故事提供特殊的 Storybook 生成的“操作”参数（简称为 "args"）来工作。获取操作参数有两种方法：

¥Actions work via supplying special Storybook-generated “action” arguments (referred to as "args" for short) to your stories. There are two ways to get an action arg:

通过 @storybook/test fn spy 函数

¥Via @storybook/test fn spy function

编写操作的推荐方法是使用 @storybook/test 中的 fn 实用程序来模拟和监视参数。这对于编写 组件测试 非常有用。你可以通过将组件的方法分配给 fn() 函数来模拟它们：

¥The recommended way to write actions is to use the fn utility from @storybook/test to mock and spy args. This is very useful for writing component tests. You can mock your component's methods by assigning them to the fn() function:

// Replace your-framework with the name of your framework
import type { Meta } from '@storybook/your-framework';
import { fn } from '@storybook/test';
 
import { Button } from './Button';
 
const meta: Meta<typeof Button> = {
  component: Button,
  // 👇 Use `fn` to spy on the onClick arg, which will appear in the actions panel once invoked
  args: { onClick: fn() },
};
 
export default meta;

如果你的组件调用一个参数（由于用户的交互或 play 函数）并且该参数被监视，则事件将显示在操作面板中：

¥If your component calls an arg (because of either the user's interaction or the play function) and that arg is spied on , the event will show up in the action panel:

自动匹配参数

¥Automatically matching args

另一种选择是使用全局参数来匹配所有符合特定模式的 argTypes。以下配置会自动为每个 on argType 创建操作（你可以手动指定，也可以是 自动推断）。

¥Another option is to use a global parameter to match all argTypes that match a certain pattern. The following configuration automatically creates actions for each on argType (which you can either specify manually or can be inferred automatically).

当你的组件有几十个（或几百个）方法并且你不想手动为每种方法应用 fn 实用程序时，这非常有用。但是，这不是推荐的编写操作的方式。这是因为自动推断的参数在你的播放函数中不可用作间谍。如果你使用 argTypesRegex 并且你的故事具有播放函数，你还需要使用 fn 实用程序定义参数以在你的播放函数中测试它们。

¥This is quite useful when your component has dozens (or hundreds) of methods and you do not want to manually apply the fn utility for each of those methods. However, this is not the recommended way of writing actions. That's because automatically inferred args are not available as spies in your play function. If you use argTypesRegex and your stories have play functions, you will need to also define args with the fn utility to test them in your play function.

// Replace your-framework with the framework you are using (e.g., react, vue3)
import { Preview } from '@storybook/your-framework';
 
const preview: Preview = {
  parameters: {
    actions: { argTypesRegex: '^on.*' },
  },
};
 
export default preview;

如果你需要更精细地控制匹配哪些 argTypes，则可以调整故事并包含 argTypesRegex 参数。例如：

¥If you need more granular control over which argTypes are matched, you can adjust your stories and include the argTypesRegex parameter. For example:

// Replace your-framework with the name of your framework
import type { Meta } from '@storybook/your-framework';
 
import { Button } from './Button';
 
const meta: Meta<typeof Button> = {
  component: Button,
  parameters: { actions: { argTypesRegex: '^on.*' } },
};
 
export default meta;

操作事件处理程序

¥Action event handlers

还可以使用 parameters.actions.handles 参数 检测你的组件是否发出了正确的 HTML 事件。

¥It is also possible to detect if your component is emitting the correct HTML events using the parameters.actions.handles parameter.

// Replace your-framework with the name of your framework
import type { Meta } from '@storybook/your-framework';
 
import { withActions } from '@storybook/addon-actions/decorator';
 
import { Button } from './Button';
 
const meta: Meta<typeof Button> = {
  component: Button,
  parameters: {
    actions: {
      handles: ['mouseover', 'click .btn'],
    },
  },
  decorators: [withActions],
};
 
export default meta;

这会将标准 HTML 事件处理程序绑定到你的组件渲染的最外层 HTML 元素，并在为给定选择器调用事件时触发操作。格式为 <eventname> <selector>。选择器是可选的；它默认为所有元素。

¥This will bind a standard HTML event handler to the outermost HTML element rendered by your component and trigger an action when the event is called for a given selector. The format is <eventname> <selector>. The selector is optional; it defaults to all elements.

API

参数

¥Parameters

此插件将以下 参数 贡献给 Storybook，位于 actions 命名空间下：

¥This addon contributes the following parameters to Storybook, under the actions namespace:

argTypesRegex

类型：string

¥Type: string

为与正则表达式匹配的每个参数创建操作。请注意如上所述的重要 此方法的局限性。

¥Create actions for each arg that matches the regex. Please note the significant limitations of this approach, as described above.

disable

类型：boolean

¥Type: boolean

禁用此插件的行为。如果你希望为整个 Storybook 禁用此插件，你应该在注册 addon-essentials 时这样做。有关更多信息，请参阅 必备插件文档。

¥Disable this addon's behavior. If you wish to disable this addon for the entire Storybook, you should do so when registering addon-essentials. See the essential addon's docs for more information.

此参数最有用，允许在更具体的级别进行覆盖。例如，如果此参数在项目级别设置为 true，则可以通过在元（组件）或故事级别将其设置为 false 来重新启用它。

¥This parameter is most useful to allow overriding at more specific levels. For example, if this parameter is set to true at the project level, it could then be re-enabled by setting it to false at the meta (component) or story level.

handles

类型：string[]

¥Type: string[]

将标准 HTML 事件处理程序绑定到组件渲染的最外层 HTML 元素，并在为给定选择器调用事件时触发操作。格式为 <eventname> <selector>。选择器是可选的；它默认为所有元素。

¥Binds a standard HTML event handler to the outermost HTML element rendered by your component and triggers an action when the event is called for a given selector. The format is <eventname> <selector>. The selector is optional; it defaults to all elements.

请参阅上面的 动作事件处理程序 部分以获取更多信息。

¥See the action event handlers section, above, for more information.

导出

¥Exports

此插件为 Storybook 贡献了以下导出：

¥This addon contributes the following exports to Storybook:

import { action } from '@storybook/addon-actions';

action

类型：(name?: string) => void

¥Type: (name?: string) => void

允许你创建一个操作，单击后该操作将显示在 Storybook UI 的操作面板中。action 函数采用可选的 name 参数，用于在 UI 中标识操作。

¥Allows you to create an action that appears in the actions panel of the Storybook UI when clicked. The action function takes an optional name parameter, which is used to identify the action in the UI.

// Replace your-framework with the name of your framework
import type { Meta } from '@storybook/your-framework';
import { action } from '@storybook/addon-actions';
 
import Button from './Button';
 
const meta: Meta<typeof Button> {
  component: Button,
  args: {
    // 👇 Create an action that appears when the onClick event is fired
    onClick: action('on-click'),
  },
};
 
export default meta;

高级/旧版用法

¥Advanced / legacy usage

还有一些较旧的方法可以使用 高级自述文件 中记录的操作。

¥There are also some older ways to use actions as documented in the advanced README.