mirror of
https://github.com/storybookjs/storybook.git
synced 2025-03-21 05:02:39 +08:00
ADD documenation of new viewport API and migration notes
This commit is contained in:
Tom Coleman
parent
3db6b12103
commit
c2d55a466c
22
MIGRATION.md
22
MIGRATION.md
@ -163,6 +163,28 @@ storiesOf('Stories', module)
|
||||
.add('centered', () => 'Hello', { decorators: [centered] });
|
||||
```
|
||||
|
||||
## Addon viewport uses parameters
|
||||
|
||||
Similarly, `@storybook/addon-viewport` uses parameters to pass viewport options. If you previously had:
|
||||
|
||||
```js
|
||||
import { configureViewport } from `@storybook/addon-viewport`;
|
||||
|
||||
configureViewport(options);
|
||||
```
|
||||
|
||||
You can replace it with:
|
||||
|
||||
```js
|
||||
import { addParameters } from '@storybook/react'; // or others
|
||||
|
||||
addParameters({ viewport: options });
|
||||
```
|
||||
|
||||
The `withViewport` decorator is also no longer supported and should be replaced with a parameter based API as above. Also the `onViewportChange` callback is no longer supported.
|
||||
|
||||
See the README for the viewport addon for more information: https://github.com/storybooks/storybook/blob/master/addons/viewport/README.md
|
||||
|
||||
## From version 4.0.x to 4.1.x
|
||||
|
||||
There are are a few migrations you should be aware of in 4.1, including one unintentionally breaking change for advanced addon usage.
|
||||
|
||||
@ -1,6 +1,6 @@
|
||||
# Storybook Viewport Addon
|
||||
|
||||
Storybook Viewport Addon allows your stories to be displayed in different sizes and layouts in [Storybook](https://storybook.js.org). This helps build responsive components inside of Storybook.
|
||||
Storybook Viewport Addon allows your stories to be displayed in different sizes and layouts in [Storybook](https://storybook.js.org). This helps build responsive components inside of Storybook.
|
||||
|
||||
[Framework Support](https://github.com/storybooks/storybook/blob/master/ADDONS_SUPPORT.md)
|
||||
|
||||
@ -28,21 +28,30 @@ import '@storybook/addon-viewport/register';
|
||||
|
||||
## Configuration
|
||||
|
||||
Import and use the `configureViewport` function in your `config.js` file.
|
||||
The viewport addon is configured by story parameters with the `viewport` key. To configure globally, import `addParameters` from your app layer in your `config.js` file.
|
||||
|
||||
```js
|
||||
import { configureViewport } from '@storybook/addon-viewport';
|
||||
import { addParameters } from '@storybook/react';
|
||||
|
||||
addParameters({ viewport: options });
|
||||
```
|
||||
|
||||
Options can take a object with the following keys:
|
||||
|
||||
### defaultViewport : String
|
||||
----
|
||||
|
||||
---
|
||||
|
||||
Setting this property to, let say `iphone6`, will make `iPhone 6` the default device/viewport for all stories. Default is `'responsive'` which fills 100% of the preview area.
|
||||
|
||||
### viewports : Object
|
||||
----
|
||||
|
||||
---
|
||||
|
||||
A key-value pair of viewport's key and properties (see `Viewport` definition below) for all viewports to be displayed. Default is [`INITIAL_VIEWPORTS`](src/shared/index.js)
|
||||
|
||||
#### Viewport Model
|
||||
|
||||
```js
|
||||
{
|
||||
/**
|
||||
@ -70,154 +79,81 @@ A key-value pair of viewport's key and properties (see `Viewport` definition bel
|
||||
}
|
||||
```
|
||||
|
||||
## Decorators
|
||||
## Configuring per component or story
|
||||
|
||||
Sometimes you want to show collection of mobile stories, and you know those stories look horible on desktop (`responsive`), so you think you need to change the default viewport only for those?
|
||||
Parameters can be configured for a whole set of stories or a single story via the standard parameter API:
|
||||
|
||||
Here is the answer, with `withViewport` decorator, you can change the default viewport of single, multiple, or all stories.
|
||||
|
||||
`withViewport` accepts either
|
||||
* A `String`, which represents the default viewport, or
|
||||
* An `Object`, which looks like
|
||||
```js
|
||||
{
|
||||
name: 'iphone6', // default viewport
|
||||
onViewportChange({ viewport }) { // called whenever different viewport is selected from the dropdown
|
||||
import addStories from '@storybook/react';
|
||||
|
||||
}
|
||||
}
|
||||
addStories('Stories', module)
|
||||
// To set a default viewport for all the stories for this component
|
||||
.addParameters({ viewport: { defaultViewport: 'iphone6' }})
|
||||
.add('story', () => </>, { viewport: 'iphonex' });
|
||||
```
|
||||
|
||||
## Examples
|
||||
|
||||
### Basic Usage
|
||||
|
||||
Simply import the Storybook Viewport Addon in the `addons.js` file in your `.storybook` directory.
|
||||
|
||||
```js
|
||||
import '@storybook/addon-viewport/register'
|
||||
```
|
||||
|
||||
This will register the Viewport Addon to Storybook and will show up in the action area.
|
||||
|
||||
|
||||
### Use Custom Set of Devices
|
||||
|
||||
This will replace all previous devices with `Kindle Fire 2` and `Kindle Fire HD` by simply calling `configureViewport` with the two devices as `viewports` in `config.js` file in your `.storybook` directory.
|
||||
This will replace all previous devices with `Kindle Fire 2` and `Kindle Fire HD` by simply calling `addParameters` with the two devices as `viewports` in `config.js` file in your `.storybook` directory.
|
||||
|
||||
```js
|
||||
import { configureViewport } from '@storybook/addon-viewport';
|
||||
import { addParameters } from '@storybook/react';
|
||||
|
||||
const newViewports = {
|
||||
kindleFire2: {
|
||||
name: 'Kindle Fire 2',
|
||||
styles: {
|
||||
width: '600px',
|
||||
height: '963px'
|
||||
}
|
||||
height: '963px',
|
||||
},
|
||||
},
|
||||
kindleFireHD: {
|
||||
name: 'Kindle Fire HD',
|
||||
styles: {
|
||||
width: '533px',
|
||||
height: '801px'
|
||||
}
|
||||
}
|
||||
height: '801px',
|
||||
},
|
||||
},
|
||||
};
|
||||
|
||||
configureViewport({
|
||||
viewports: newViewports
|
||||
addParameters({
|
||||
viewport: { viewports: newViewports },
|
||||
});
|
||||
```
|
||||
|
||||
|
||||
### Add New Device
|
||||
|
||||
This will add both `Kindle Fire 2` and `Kindle Fire HD` to the list of devices. This is acheived by making use of the exported [`INITIAL_VIEWPORTS`](src/shared/index.js) property, by merging it with the new viewports and pass the result as `viewports` to `configureViewport` function
|
||||
|
||||
```js
|
||||
import { configureViewport, INITIAL_VIEWPORTS } from '@storybook/addon-viewport';
|
||||
import { addParameters } from '@storybook/react';
|
||||
import { INITIAL_VIEWPORTS } from '@storybook/addon-viewport';
|
||||
|
||||
const newViewports = {
|
||||
kindleFire2: {
|
||||
name: 'Kindle Fire 2',
|
||||
styles: {
|
||||
width: '600px',
|
||||
height: '963px'
|
||||
}
|
||||
height: '963px',
|
||||
},
|
||||
},
|
||||
kindleFireHD: {
|
||||
name: 'Kindle Fire HD',
|
||||
styles: {
|
||||
width: '533px',
|
||||
height: '801px'
|
||||
}
|
||||
}
|
||||
height: '801px',
|
||||
},
|
||||
},
|
||||
};
|
||||
|
||||
configureViewport({
|
||||
viewports: {
|
||||
...INITIAL_VIEWPORTS,
|
||||
...newViewports
|
||||
}
|
||||
addParameters({
|
||||
viewport: {
|
||||
viewports: {
|
||||
...INITIAL_VIEWPORTS,
|
||||
...newViewports,
|
||||
},
|
||||
},
|
||||
});
|
||||
```
|
||||
|
||||
|
||||
### Change The Default Viewport
|
||||
|
||||
This will make `iPhone 6` the default viewport for all stories.
|
||||
|
||||
```js
|
||||
import { configureViewport } from '@storybook/addon-viewport';
|
||||
|
||||
configureViewport({
|
||||
defaultViewport: 'iphone6'
|
||||
});
|
||||
```
|
||||
|
||||
## withViewport Decorator
|
||||
|
||||
Change the default viewport for single/multiple/global stories, or listen to viewport selection changes
|
||||
|
||||
```js
|
||||
import React from 'react';
|
||||
import { storiesOf, addDecorator } from '@storybook/react';
|
||||
import { withViewport } from '@storybook/addon-viewport';
|
||||
|
||||
// Globablly
|
||||
addDecorator(withViewport('iphone5'));
|
||||
|
||||
// Collection
|
||||
storiesOf('Decorator with string', module)
|
||||
.addDecorator(withViewport('iphone6'))
|
||||
.add('iPhone 6', () => (
|
||||
<h1>
|
||||
Do I look good on <b>iPhone 6</b>?
|
||||
</h1>
|
||||
));
|
||||
|
||||
// Single
|
||||
storiesOf('Parameterized story', module)
|
||||
.addDecorator(withViewport())
|
||||
.add(
|
||||
'iPad',
|
||||
() => (
|
||||
<h1>
|
||||
Do I look good on <b>iPad</b>?
|
||||
</h1>
|
||||
),
|
||||
{ viewport: 'ipad' }
|
||||
);
|
||||
|
||||
storiesOf('Decorator with object', module)
|
||||
.addDecorator(
|
||||
withViewport({
|
||||
onViewportChange({ viewport }) {
|
||||
console.log(`Viewport changed: ${viewport.name} (${viewport.type})`); // e.g. Viewport changed: iphone6 (mobile)
|
||||
},
|
||||
})
|
||||
)
|
||||
.add('onViewportChange', () => <MobileFirstComponent />);
|
||||
|
||||
```
|
||||
|
||||
Loading…
x
Reference in New Issue
Block a user