GitHub/storybook
1
0
Fork 0
mirror of https://github.com/storybookjs/storybook.git synced 2025-04-05 16:11:33 +08:00
Code Issues Packages Projects Releases Wiki Activity

Refactor actions README

Browse Source
This commit is contained in:
Tom Coleman 2020-08-10 16:03:56 +10:00
parent 8e99cd2c34
commit f7df04c4cf
4 changed files with 94 additions and 134 deletions
Show Stats Download Patch File Download Diff File Expand all files Collapse all files

83
addons/actions/ADVANCED.md Normal file
View File

@ -0,0 +1,83 @@
## Advanced/Legacy Actions usage
For basic usage, see the [documentation](https://storybook.js.org/docs/react/essentials/actions).
This document describes the pre-6.0 usage of the addon, and as such is no longer recommended (although it will be supported until at least 7.0).
## Manually-specified actions
Import the `action` function and use it to create actions handlers. When creating action handlers, provide a **name** to make it easier to identify.
> _Note: Make sure NOT to use reserved words as function names. [issues#29](https://github.com/storybookjs/storybook-addon-actions/issues/29#issuecomment-288274794)_
```js
import { action } from '@storybook/addon-actions';
import Button from './button';
export default {
title: 'Button',
component: Button,
};
export const defaultView = () => <Button onClick={action('button-click')}>Hello World!</Button>;
```
## Multiple actions
If your story requires multiple actions, it may be convenient to use `actions` to create many at once:
```js
import { actions } from '@storybook/addon-actions';
import Button from './button';
export default {
title: 'Button',
component: Button,
};
// This will lead to { onClick: action('onClick'), ... }
const eventsFromNames = actions('onClick', 'onMouseOver');
// This will lead to { onClick: action('clicked'), ... }
const eventsFromObject = actions({ onClick: 'clicked', onMouseOver: 'hovered' });
export const first = () => <Button {...eventsFromNames}>Hello World!</Button>;
export const second = () => <Button {...eventsFromObject}>Hello World!</Button>;
```
## Configuration
Arguments which are passed to the action call will have to be serialized while be "transferred" over the channel.
This is not very optimal and can cause lag when large objects are being logged, for this reason it is possible to configure a maximum depth.
The action logger, by default, will log all actions fired during the lifetime of the story. After a while this can make the storybook laggy. As a workaround, you can configure an upper limit to how many actions should be logged.
To apply the configuration globally use the `configureActions` function in your `preview.js` file.
```js
import { configureActions } from '@storybook/addon-actions';
configureActions({
depth: 100,
// Limit the number of items logged into the actions panel
limit: 20,
});
```
To apply the configuration per action use:
```js
action('my-action', {
depth: 5,
});
```
### Available Options
| Name | Type | Description | Default |
| -------------------- | ------- | ----------------------------------------------------------------------------------- | ------- |
| `depth` | Number | Configures the transferred depth of any logged objects. | `10` |
| `clearOnStoryChange` | Boolean | Flag whether to clear the action logger when switching away from the current story. | `true` |
| `limit` | Number | Limits the number of items logged in the action logger | `50` |

136
addons/actions/README.md
View File

@ -2,19 +2,21 @@
Storybook Addon Actions can be used to display data received by event handlers in [Storybook](https://storybook.js.org).
[Framework Support](https://github.com/storybookjs/storybook/blob/master/ADDONS_SUPPORT.md)
[Framework Support](https://storybook.js.org/docs/react/api/frameworks-feature-support)
![Screenshot](https://raw.githubusercontent.com/storybookjs/storybook/HEAD/addons/actions/docs/screenshot.png)
## Getting Started
Actions is part of [essentials](https://storybook.js.org/docs/react/essentials/introduction) and so is installed in all new Storybooks by default. If you need to add it to your storybook, you can run:
Install:
```sh
npm i -D @storybook/addon-actions
```
Then, add following content to `.storybook/main.js`
Then, add following content to [`.storybook/main.js`](https://storybook.js.org/docs/react/configure/overview#Configure-your-Storybook-project)
```js
module.exports = {
@ -22,132 +24,6 @@ module.exports = {
};
```
## Actions args
## Usage
Starting in SB6.0, we recommend using story parameters to specify actions which get passed into your story as [Args](https://docs.google.com/document/d/1Mhp1UFRCKCsN8pjlfPdz8ZdisgjNXeMXpXvGoALjxYM/edit?usp=sharing) (passed as the first argument when `passArgsFirst` is set to `true`).
The first option is to specify `argTypes` for your story with an `action` field. Take the following example:
```js
import Button from './button';
export default {
title: 'Button',
argTypes: { onClick: { action: 'clicked' } },
};
export const Basic = ({ onClick }) => <Button onClick={onClick}>Hello World!</Button>;
```
Alternatively, suppose you have a naming convention, like `onX` for event handlers. The following configuration automatically creates actions for each `onX` `argType` (which you can either specify manually or generate automatically using [Storybook Docs](https://www.npmjs.com/package/@storybook/addon-docs).
```js
import Button from './button';
export default {
title: 'Button',
component: Button,
parameters: { actions: { argTypesRegex: '^on.*' } },
};
export const Basic = ({ onClick }) => <Button onClick={onClick}>Hello World!</Button>;
```
> **NOTE:** If you're generating `argTypes` in using another addon (like Docs, which is the common behavior) you'll need to make sure that the actions addon loads **AFTER** the other addon. You can do this by listing it later in the `addons` registration code in `.storybook/main.js`.
## Manually-specified actions
Import the `action` function and use it to create actions handlers. When creating action handlers, provide a **name** to make it easier to identify.
> _Note: Make sure NOT to use reserved words as function names. [issues#29](https://github.com/storybookjs/storybook-addon-actions/issues/29#issuecomment-288274794)_
```js
import { action } from '@storybook/addon-actions';
import Button from './button';
export default {
title: 'Button',
component: Button,
};
export const defaultView = () => <Button onClick={action('button-click')}>Hello World!</Button>;
```
## Multiple actions
If your story requires multiple actions, it may be convenient to use `actions` to create many at once:
```js
import { actions } from '@storybook/addon-actions';
import Button from './button';
export default {
title: 'Button',
component: Button,
};
// This will lead to { onClick: action('onClick'), ... }
const eventsFromNames = actions('onClick', 'onMouseOver');
// This will lead to { onClick: action('clicked'), ... }
const eventsFromObject = actions({ onClick: 'clicked', onMouseOver: 'hovered' });
export const first = () => <Button {...eventsFromNames}>Hello World!</Button>;
export const second = () => <Button {...eventsFromObject}>Hello World!</Button>;
```
## Configuration
Arguments which are passed to the action call will have to be serialized while be "transferred" over the channel.
This is not very optimal and can cause lag when large objects are being logged, for this reason it is possible to configure a maximum depth.
The action logger, by default, will log all actions fired during the lifetime of the story. After a while this can make the storybook laggy. As a workaround, you can configure an upper limit to how many actions should be logged.
To apply the configuration globally use the `configureActions` function in your `preview.js` file.
```js
import { configureActions } from '@storybook/addon-actions';
configureActions({
depth: 100,
// Limit the number of items logged into the actions panel
limit: 20,
});
```
To apply the configuration per action use:
```js
action('my-action', {
depth: 5,
});
```
### Available Options
| Name | Type | Description | Default |
| -------------------- | ------- | ----------------------------------------------------------------------------------- | ------- |
| `depth` | Number | Configures the transferred depth of any logged objects. | `10` |
| `clearOnStoryChange` | Boolean | Flag whether to clear the action logger when switching away from the current story. | `true` |
| `limit` | Number | Limits the number of items logged in the action logger | `50` |
## Declarative Configuration via Parameters
You can define action handles in a declarative way using parameters. They accepts the same arguments as [`actions`](#multiple-actions)
Keys have `'<eventName> <selector>'` format, e.g. `'click .btn'`. Selector is optional. This can be used with any framework but is especially useful for `@storybook/html`.
```js
import Button from './button';
export default {
title: 'Button',
parameters: {
actions: {
handles: ['mouseover', 'click .btn']
}
};
export const first = () => <Button className="btn">Hello World!</Button>;
```
The basic usage is documented in the [documentation](https://storybook.js.org/docs/react/essentials/actions). For legacy usage, see the [advanced README](./ADVANCED.md).

5
docs/essentials/actions.md
View File

@ -53,10 +53,9 @@ NOTE: If you're generating argTypes in using another addon (like [docs](../writi
</div>
### Action event handlers
It is also possible to detect if your component is emitting the correct HTML events using the `parameters.actions.handles` [parameter](../writing-stories/parameters.md).
It is also possible to detect if your component is emitting the correct HTML events using the `parameters.actions.handles` [parameter](../writing-stories/parameters.md).
<!-- prettier-ignore-start -->
@ -72,4 +71,4 @@ This will bind a standard HTML event handler to the outermost HTML element rende
### Advanced / legacy usage
There are also some older ways to use actions as documented in the [advanced README](../addons/actions/ADVANCED-README.md).
There are also some older ways to use actions as documented in the [advanced README](../../addons/actions/ADVANCED.md).

4
docs/essentials/introduction.md
View File

@ -34,4 +34,6 @@ As an example, if the background addon wasn't necessary to your work, you would
<!-- prettier-ignore-end -->
You can use the following keys for each individual addon: `actions`, `backgrounds`, `controls`, `docs`, `viewport`
<div class="aside">
You can use the following keys for each individual addon: `actions`, `backgrounds`, `controls`, `docs`, `viewport`.
</div>