视口
视口功能允许你调整故事渲染所在的 iframe 的尺寸。它使开发响应式 UI 变得容易。
配置
开箱即用,视口功能为你提供了一组标准的视口供你使用。如果你想更改默认的视口集合,可以在 .storybook/preview.js|ts
中使用 viewport
参数 配置自己的视口。
你可以使用 options
属性 定义可用的视口,并使用 initialGlobals
属性 设置初始视口
// Replace your-framework with the framework you are using, e.g. react-vite, nextjs, vue3-vite, etc.
import { Preview } from '@storybook/your-framework';
import { INITIAL_VIEWPORTS } from 'storybook/viewport';
const preview: Preview = {
parameters: {
viewport: {
options: INITIAL_VIEWPORTS,
},
},
initialGlobals: {
viewport: { value: 'ipad', isRotated: false },
},
};
export default preview;
使用详细的设备集合
默认情况下,视口功能会使用一组最小的视口,这使得你可以在常见的响应式场景中测试你的 UI。这些也通过 MINIMAL_VIEWPORTS
导出 提供,并包括以下设备
键 | 描述 | 尺寸 (w×h,px) |
---|---|---|
mobile1 | 小型手机 | 320 × 568 |
mobile2 | 大型手机 | 414 × 896 |
tablet | 平板电脑 | 834 × 1112 |
如果你需要更详细的设备集合,可以使用 INITIAL_VIEWPORTS
导出,它包括以下设备
键 | 描述 | 尺寸 (w×h,px) |
---|---|---|
iphone5 | iPhone 5 | 320 × 568 |
iphone6 | iPhone 6 | 375 × 667 |
iphone6p | iPhone 6 Plus | 414 × 736 |
iphone8p | iPhone 8 Plus | 414 × 736 |
iphonex | iPhone X | 375 × 812 |
iphonexr | iPhone XR | 414 × 896 |
iphonexsmax | iPhone XS Max | 414 × 896 |
iphonese2 | iPhone SE (第二代) | 375 × 667 |
iphone12mini | iPhone 12 mini | 375 × 812 |
iphone12 | iPhone 12 | 390 × 844 |
iphone12promax | iPhone 12 Pro Max | 428 × 926 |
iphoneSE3 | iPhone SE 第三代 | 375 × 667 |
iphone13 | iPhone 13 | 390 × 844 |
iphone13pro | iPhone 13 Pro | 390 × 844 |
iphone13promax | iPhone 13 Pro Max | 428 × 926 |
iphone14 | iPhone 14 | 390 × 844 |
iphone14pro | iPhone 14 Pro | 393 × 852 |
iphone14promax | iPhone 14 Pro Max | 430 × 932 |
galaxys5 | Galaxy S5 | 360 × 640 |
galaxys9 | Galaxy S9 | 360 × 740 |
nexus5x | Nexus 5X | 412 × 668 |
nexus6p | Nexus 6P | 412 × 732 |
pixel | Pixel | 540 × 960 |
pixelxl | Pixel XL | 720 × 1280 |
mobile1 | 小型手机 (也包含在 MINIMAL_VIEWPORTS 中) | 320 × 568 |
mobile2 | 大型手机 (也包含在 MINIMAL_VIEWPORTS 中) | 414 × 896 |
ipad | iPad | 768 × 1024 |
ipad10p | iPad Pro 10.5 英寸 | 834 × 112 |
ipad11p | iPad Pro 11 英寸 | 834 × 1194 |
ipad12p | iPad Pro 12.9 英寸 | 1024 × 1366 |
tablet | 平板电脑 (也包含在 MINIMAL_VIEWPORTS 中) | 834 × 1112 |
要使用详细的设备集合,可以在配置中调整 options
属性,使其包含 INITIAL_VIEWPORTS
导出
// Replace your-framework with the framework you are using, e.g. react-vite, nextjs, vue3-vite, etc.
import { Preview } from '@storybook/your-framework';
import { INITIAL_VIEWPORTS } from 'storybook/viewport';
const preview: Preview = {
parameters: {
viewport: {
options: INITIAL_VIEWPORTS,
},
},
initialGlobals: {
viewport: { value: 'ipad', isRotated: false },
},
};
export default preview;
添加新设备
如果预定义的视口不满足你的需求,你可以将新设备添加到视口列表中。例如,让我们将两个 Kindle 设备添加到默认的最小视口集合中
// Replace your-framework with the framework you are using, e.g. react-vite, nextjs, vue3-vite, etc.
import { Preview } from '@storybook/your-framework';
import { MINIMAL_VIEWPORTS } from 'storybook/viewport';
const kindleViewports = {
kindleFire2: {
name: 'Kindle Fire 2',
styles: {
width: '600px',
height: '963px',
},
},
kindleFireHD: {
name: 'Kindle Fire HD',
styles: {
width: '533px',
height: '801px',
},
},
};
const preview: Preview = {
parameters: {
viewport: {
options: {
...MINIMAL_VIEWPORTS,
...kindleViewports,
},
},
},
};
export default preview;
按组件或故事配置
在某些情况下,全局使用特定的视觉视口可能不切实际,你需要将其调整到单个故事或组件的一组故事中。
参数 可以应用于项目、组件和故事级别,这使得你可以在需要的地方指定配置。例如,你可以像这样为一个组件的所有故事设置可用的视口
// Replace your-framework with the framework you are using, e.g. react-vite, nextjs, nextjs-vite, etc.
import type { Meta, StoryObj } from '@storybook/your-framework';
import { INITIAL_VIEWPORTS } from 'storybook/viewport';
import { MyComponent } from './MyComponent';
const meta = {
component: MyComponent,
parameters: {
viewport: {
//👇 Set available viewports for every story in the file
options: INITIAL_VIEWPORTS,
},
},
} satisfies Meta<typeof MyComponent>;
export default meta;
为故事定义视口
视口模块使你能够通过从工具栏中预定义的视口列表中选择来更改应用于故事的视口。如果需要,你可以使用 globals
选项 将故事设置为默认使用特定视口
// Replace your-framework with the framework you are using, e.g. react-vite, nextjs, vue3-vite, etc.
import type { Meta, StoryObj } from '@storybook/your-framework';
import { Button } from './Button';
const meta = {
component: Button,
globals: {
// 👇 Set viewport for all component stories
viewport: { value: 'tablet', isRotated: false },
},
} satisfies Meta<typeof Button>;
export default meta;
type Story = StoryObj<typeof meta>;
export const OnPhone: Story = {
globals: {
// 👇 Override viewport for this story
viewport: { value: 'mobile1', isRotated: false },
},
};
当你使用 globals
为故事(或组件的故事)指定视口时,该视口会被应用,并且不能通过工具栏更改。这对于确保故事始终在特定视口上渲染非常有用。
API
键盘快捷键
如果需要,可以在快捷键页面编辑这些快捷键。
- 下一个视口: alt + v
- 上一个视口: alt + shift + v
- 重置视口: alt + control + v
全局变量
此模块在 viewport
命名空间下为 Storybook 贡献以下全局变量
value
类型: string
设置后,视口将被应用,并且不能通过工具栏更改。必须与 可用视口 的键匹配。
isRotated
类型: boolean
当为 true 时,应用的视口将旋转 90°,例如,从纵向旋转到横向。
参数
此模块在 viewport
命名空间下为 Storybook 贡献以下 参数
disable
类型: boolean
关闭此模块的行为。此参数最常用于允许在更具体的级别上进行覆盖。例如,如果在项目级别将此参数设置为 true
,则可以在元数据(组件)或故事级别将其设置为 false
来重新启用。
options
类型
{
[key: string]: {
name: string;
styles: { height: string, width: string };
type: 'desktop' | 'mobile' | 'tablet' | 'other';
};
}
指定可用的视口。参见上面的使用示例。width
和 height
值必须包含单位,例如 '320px'
。
导出
此模块为 Storybook 贡献以下导出
import { INITIAL_VIEWPORTS, MINIMAL_VIEWPORTS } from 'storybook/viewport';
INITIAL_VIEWPORTS
类型: object
视口模块提供的完整初始视口集合,如上所示。
MINIMAL_VIEWPORTS
类型: object
视口模块提供的最小视口集合,如上所示。这些是默认使用的。