mirror of
https://github.com/storybookjs/storybook.git
synced 2025-03-20 05:02:37 +08:00
docs polish and tweaks
This commit is contained in:
domyen
parent
b5a806a5c2
commit
bbf9a89ea0
@ -8,13 +8,11 @@ Storybook ships with toolbar items to control the [viewport](./viewport.md) and
|
||||
|
||||
Globals in Storybook represent “global” (as in not story-specific) inputs to the rendering of the story. As they aren’t specific to the story, they aren’t passed in the `args` argument to the story function (although they are accessible as `context.globals`), but typically you use them in decorators which apply to all stories.
|
||||
|
||||
When the globals change, the story re-renders and the decorators rerun with the new values. The easiest way to change globals is to create a toolbar item for them.
|
||||
|
||||
Let’s see how.
|
||||
When the globals change, the story re-renders and the decorators rerun with the new values. The easiest way to change globals is to create a toolbar item for them.
|
||||
|
||||
### Global types and the toolbar annotation
|
||||
|
||||
Storybook has a simple, declarative syntax for configuring toolbar menus. In your [`.storybook/preview.js`](../configure/overview.md#configure-story-rendering), you can add your own toolbars by creating `globalTypes` with a `toolbar` annotation:
|
||||
Storybook has a simple, declarative syntax for configuring toolbar menus. In your [`.storybook/preview.js`](../configure/overview.md#configure-story-rendering), you can add your own toolbars by creating `globalTypes` with a `toolbar` annotation:
|
||||
|
||||
```js
|
||||
// .storybook/preview.js
|
||||
@ -35,7 +33,7 @@ export const globalTypes = {
|
||||
|
||||
<div class="aside">
|
||||
|
||||
As globals are *global* you can *only* set `globalTypes` in [`.storybook/preview.js`](../configure/overview.md#configure-story-rendering).
|
||||
As globals are _global_ you can _only_ set `globalTypes` in [`.storybook/preview.js`](../configure/overview.md#configure-story-rendering).
|
||||
|
||||
</div>
|
||||
|
||||
@ -53,22 +51,22 @@ For example, suppose you are using `styled-components`. You can add a theme prov
|
||||
import { ThemeProvider } from 'styled-components';
|
||||
import { StoryContext, StoryGetter, StoryWrapper } from '@storybook/addons';
|
||||
|
||||
const withThemeProvider=(Story,context)=>{
|
||||
const withThemeProvider = (Story, context) => {
|
||||
const theme = getTheme(context.globals.theme);
|
||||
return (
|
||||
<ThemeProvider theme={theme}>
|
||||
<Story {...context} />
|
||||
</ThemeProvider>
|
||||
)
|
||||
}
|
||||
);
|
||||
};
|
||||
export const decorators = [withThemeProvider];
|
||||
```
|
||||
|
||||
### Advanced usage
|
||||
|
||||
So far we've managed to create and consume a global inside Storybook.
|
||||
So far we've managed to create and consume a global inside Storybook.
|
||||
|
||||
Now let's take a look at a more complex example. Let's suppose we wanted to implement a new global called __locale__ for internationalization, which shows a flag on the right side of the toolbar.
|
||||
Now let's take a look at a more complex example. Let's suppose we wanted to implement a new global called **locale** for internationalization, which shows a flag on the right side of the toolbar.
|
||||
|
||||
In your [`.storybook/preview.js`](../configure/overview.md#configure-story-rendering), add the following:
|
||||
|
||||
@ -97,21 +95,21 @@ By adding the the configuration element `right`, the text will displayed on the
|
||||
|
||||
Here's a list of the configuration options available.
|
||||
|
||||
| MenuItem | Type | Description | Required |
|
||||
| ------------- |:-------------:|:------------------------------------------------------------:|:--------:|
|
||||
| **value** | String |The string value of the menu that gets set in the globals |Yes |
|
||||
| **title** | String |The main text of the title |Yes |
|
||||
| **left** | String |A string that gets shown in left side of the menu |No |
|
||||
| **right** | String |A string that gets shown in right side of the menu |No |
|
||||
| **icon** | String |An icon that gets shown in the toolbar if this item is selected|No |
|
||||
| MenuItem | Type | Description | Required |
|
||||
| --------- | :----: | :-------------------------------------------------------------: | :------: |
|
||||
| **value** | String | The string value of the menu that gets set in the globals | Yes |
|
||||
| **title** | String | The main text of the title | Yes |
|
||||
| **left** | String | A string that gets shown in left side of the menu | No |
|
||||
| **right** | String | A string that gets shown in right side of the menu | No |
|
||||
| **icon** | String | An icon that gets shown in the toolbar if this item is selected | No |
|
||||
|
||||
### Consuming globals from within a story
|
||||
|
||||
We recommend consuming globals from within a decorator and define a global setting for all stories.
|
||||
We recommend consuming globals from within a decorator and define a global setting for all stories.
|
||||
|
||||
But we're aware that sometimes it's more useful to use toolbar options in a per-story basis.
|
||||
|
||||
Using the example above, you can modify any story to retrieve the __Locale__ `global` from the story context:
|
||||
Using the example above, you can modify any story to retrieve the **Locale** `global` from the story context:
|
||||
|
||||
```js
|
||||
// your-story.js
|
||||
@ -148,11 +146,9 @@ export const StoryWithLocale = ({ globals: { locale } }) => {
|
||||
|
||||
</div>
|
||||
|
||||
|
||||
|
||||
### Consuming globals from within an addon
|
||||
|
||||
If you're working on a Storybook addon and you need to retrieve globals. You can do so, The `@storybook/api` package provides a hook for this scenario, you can use the `useGlobals()` hook to retrieve any globals you want.
|
||||
If you're working on a Storybook addon and you need to retrieve globals. You can do so, The `@storybook/api` package provides a hook for this scenario, you can use the `useGlobals()` hook to retrieve any globals you want.
|
||||
|
||||
Using the ThemeProvider example above, you could expand it to display which current theme is being shown inside a panel like so:
|
||||
|
||||
|
||||
19
docs/toc.js
19
docs/toc.js
@ -117,24 +117,25 @@ module.exports = {
|
||||
title: 'Introduction',
|
||||
type: 'link',
|
||||
},
|
||||
{
|
||||
pathSegment: 'controls',
|
||||
title: 'Controls',
|
||||
type: 'link',
|
||||
},
|
||||
|
||||
{
|
||||
pathSegment: 'actions',
|
||||
title: 'Actions',
|
||||
type: 'link',
|
||||
},
|
||||
{
|
||||
pathSegment: 'viewports',
|
||||
title: 'Viewports',
|
||||
pathSegment: 'backgrounds',
|
||||
title: 'Backgrounds',
|
||||
type: 'link',
|
||||
},
|
||||
{
|
||||
pathSegment: 'backgrounds',
|
||||
title: 'Backgrounds',
|
||||
pathSegment: 'controls',
|
||||
title: 'Controls',
|
||||
type: 'link',
|
||||
},
|
||||
{
|
||||
pathSegment: 'viewports',
|
||||
title: 'Viewports',
|
||||
type: 'link',
|
||||
},
|
||||
{
|
||||
|
||||
@ -1,5 +1,5 @@
|
||||
---
|
||||
title: 'Preview and build Storybook documentation'
|
||||
title: 'Preview and build docs'
|
||||
---
|
||||
|
||||
Storybook allows you to create rich and extensive [documentation](./introduction.md) that will help you and any other stakeholder involved in the development process. Out of the box you have the tooling required to not only write it but also to preview it and build it.
|
||||
|
||||
@ -2,7 +2,7 @@
|
||||
title: 'Parameters'
|
||||
---
|
||||
|
||||
**Parameters** are a set of static, named metadata about a story, typically used to control the behavior of Storybook features and addons.
|
||||
Parameters are a set of static, named metadata about a story, typically used to control the behavior of Storybook features and addons.
|
||||
|
||||
For example, let’s customize the backgrounds addon via a parameter. We’ll use `parameters.backgrounds` to define which backgrounds appear in the backgrounds toolbar when a story is selected.
|
||||
|
||||
|
||||
Loading…
x
Reference in New Issue
Block a user