编写 stories
story 用于展示组件某个状态,每个组件可以包含任意多个 story,用来测试组件的各种场景。根据默认配置,只需要在组件的文件夹中,以 **.component.stories.ts 的格式创建即可。
story 语法
基本编写语法很简单,是 export
任意多个 function,每一个就是一个 story。导出主要分两种:
-
default export:默认导出,提供组件级别的配置信息,例如以下配置会注明组件的归类,并提供 Button 组件的信息,以便渲染这个组件。
// Button.stories.ts import Button from './button.component'; export default { title: 'Components/Button', component: Button, }
-
named export:命名导出,用以描述 story,如上所说,一个组件可以有若干个 story。
// Button.stories.ts // 创建一个模板,方便在后续的 story 中复用 const Template = (args: Button) => ({ props: args, }); export const Primary = Template.bind({}); // 复制 Template Primary.args = { background: '#ff0', label: 'Button' }; Primary.storyName = "主要状态" // 自定义 story 名 export const Secondary = Template.bind({}); Secondary.args = { ...Primary.args, label: '222' }; // 复用上一个 story 的配置 export const Tertiary = Template.bind({}); Tertiary.args = { ...Primary.args, label: '222 } // 再来一个
通过复制模板 function,可以创建若干个 story,传入不同的参数,就可以分别渲染出组件的不同状态。每个 story 的名字默认是 function 名,也可以自定义。
Args(属性)
上一节看到了怎么去写一个 Story 文件,不过里面反复用到的 args 是什么呢?
它代表组件的输入属性(Angular 中的 @input(),Vue/React 中的 props),它有 2 个层级,方便灵活配置。
-
story 层级:
// Button.stories.ts const Template = (args: Button) => ({ props: args, }); // 在这个 story 中传入组件属性,只影响当前 story export const Primary = Template.bind({}); Primary.args = { primary: true, label: 'Primary', };
-
组件层级:
// Button.stories.ts import Button from './button.component'; // 组件层级(默认导出)中传入组件属性, // 这个 Button 组件的所有 stories 的 primary 属性都会是 true export default { title: "Button", component: Button, args: { primary: true, }, }
就像上一节所看到的,不同的 story 的 args 是可以复用的,这里用到了 ES6 的解构语法:
const Primary = ButtonStory.bind({}); Primary.args = { primary: true, label: 'Button', } // 复用 Primary story 的 args,并覆盖 primary 属性 const Secondary = ButtonStory.bind({}); Secondary.args = { ...Primary.args, // 合并上一个 args 对象 primary: false, }
简单的导出几个 function,这个按钮组件的测试用例就写好了
可以看到,这个按钮组件可以独立于项目运行了,并且右边工具栏可以自由更改它的属性,实时查看属性改变后的效果,还可以自动生成组件文档。
有 story 做示例,有实时的控制台,有文档,再也不怕写好的组件别人不知道怎么用了。
额外的配置项
除了写给组件写 story,很多时候也会需要配置插件,或者给组件提供额外的功能,这里看看是如何配置的吧。
Parameters(参数)
Parameters 用以配置 Storybook 和 插件,具有全局、组件、story 三个层级。
Story 拥有大量的插件,以下以简单的 backgrounds 插件举例,它用来控制组件容器的背景色,默认自带黑/白两色。
-
全局定义在根目录 .storybook/preview.js 下,会影响所有的 stories。这样配置后,每个 story 界面下都可以选择红/绿两色背景:
// .storybook/preview.js export const parameters = { backgrounds: { values: [ { name: 'red', value: '#f00' }, { name: 'green', value: '#0f0' }, ], }, };
-
组件层级下定义,会让这个组件的所有 stories 都可以选择指定的背景色
// Button.story.ts export default { title: 'Button', component: Button, parameters: { backgrounds: { values: [ { name: 'red', value: '#f00' }, { name: 'green', value: '#0f0' }, ], }, }, };
-
story 层级下的定义只会影响当前 story,其他 story 就只能选择默认的黑/白两色了。
// Button.story.ts export const Primary = Template.bind({}); Primary.args = { primary: true, label: 'Button', }; // 红绿背景只在这个 story 下可以选择 Primary.parameters = { backgrounds: { values: [ { name: 'red', value: '#f00' }, { name: 'green', value: '#0f0' }, ], }, };
Parameters 的配置是可以继承,同名的子级会覆盖父级的定义。
Decorators(装饰器)
每个 Decorator 也是 function,用来包裹 story,保持原有的 story 不变的情况下,额外给它添加额外的 DOM 元素、引入上下文环境、添加假数据等等。
和 Parameters 一样,它也可以定义在全局/组件/story 三个层级,每个 Decorator 按定义顺序依次执行,从全局到 story。
例如,用一个额外的 <div>
包裹每个 story 的组件渲染:
// button.stories.ts import { Meta, Story } from '@storybook/angular'; import { ListComponent } from './list.component'; export default { title: 'Example/List', component: ListComponent, decorators: [ (storyFunc) => { const story = storyFunc(); return { ...story, template: `<div style="height: 60px">${story.template}</div>`, }; } ] } as Meta;
这样一来,这个列表组件的所有 story,都会展示出它在一个 60 像素高的容器内的呈现效果。
除了给组件包裹额外的元素,再例如为复合组件添加组件依赖:
// List.stories.ts import { moduleMetadata } from '@storybook/angular'; import { CommonModule } from '@angular/common'; import List from './list.component'; import ListItem from './list-item.component' // 给 list 组件添加它需要的组件和模块依赖 export default { title: 'List', component: List, decorators: [ moduleMetadata({ declarations: [ListItem], imports: [CommonModule], }), ], }; const Template = (args: List) => ({ component: List, props: args, });
就像平常需要在 ngModule 中声明似的,moduleMetadata
装饰器可以轻松测试各种组件,让你能在 Storybook 中从小到大搭建组件库。
文章内容来源:
Storybook 组件驱动开发(一)-- 基本使用 前端 - Storybook 组件驱动开发(一)-- 基本使用 - 个人文章 - SegmentFault 思否
转载本站文章《storybook 编写stories的story基础语法》,
请注明出处:storybook 编写stories的story基础语法 - Storybook Driven Development学习笔记—组件化之后之组件管理 - 周陆军的个人网站