storybook 编写stories的story基础语法

编写 stories

story 用于展示组件某个状态，每个组件可以包含任意多个 story，用来测试组件的各种场景。根据默认配置，只需要在组件的文件夹中，以 **.component.stories.ts 的格式创建即可。

story 语法

基本编写语法很简单，是 export 任意多个 function，每一个就是一个 story。导出主要分两种：

1. default export：默认导出，提供组件级别的配置信息，例如以下配置会注明组件的归类，并提供 Button 组件的信息，以便渲染这个组件。

   // Button.stories.ts
   
   import Button from './button.component';
   
   export default {
     title: 'Components/Button',
     component: Button,
   }

2. 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 个层级，方便灵活配置。

1. story 层级：

   // Button.stories.ts
   
   const Template = (args: Button) => ({
     props: args,
   });
   
   // 在这个 story 中传入组件属性，只影响当前 story
   export const Primary = Template.bind({});
   Primary.args = {
     primary: true,
     label: 'Primary',
   };

2. 组件层级：

   // 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 插件举例，它用来控制组件容器的背景色，默认自带黑/白两色。

1. 全局定义在根目录 .storybook/preview.js 下，会影响所有的 stories。这样配置后，每个 story 界面下都可以选择红/绿两色背景：

   // .storybook/preview.js
    
   export const parameters = {
     backgrounds: {
       values: [
         { name: 'red', value: '#f00' },
         { name: 'green', value: '#0f0' },
       ],
     },
   };

2. 组件层级下定义，会让这个组件的所有 stories 都可以选择指定的背景色

   // Button.story.ts
   
   export default {
     title: 'Button',
     component: Button,
     parameters: {
       backgrounds: {
         values: [
           { name: 'red', value: '#f00' },
           { name: 'green', value: '#0f0' },
         ],
       },
     },
   };

3. 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学习笔记—组件化之后之组件管理 - 周陆军的个人网站