<Meta title="使用说明/物料基本用法" />



import propsImg from '../assets/props.png'
import actions from '../assets/actions.png'

## 在线编辑物料文档

  请来 CodeSandbox  <a href="https://codesandbox.io/s/0qedx" target="_blank">查看在线编辑文档示例</a>

## .arkdoc arkcli 物料文档目录结构

    |-- .arkdoc
    |   |-- config
    |   |   |-- main.js // 可配置stories.js和mdx的解析路径(请用绝对路径)，默认读取.arkdoc/examples路径下所有文档文件
        |   |-- preview.js // 可配置右侧文档区域的展示
    |   |   |-- preview-head.html // 文档canvas和docs区域里iframe的head标签内容
    |   |   |-- preview-body.html // 文档canvas和docs区域里iframe的body标签内容
    |   |-- example // 存放文档示例

## 使用说明
### 前提：
 ```
       1、在 .arkdoc/config/preview-head.html 或者是 preview-body.html 添加你的第三方依赖

      2、在.arkdoc/config/preview.js 配置文档顺序
```

然后在 .arkdoc/examples 目录下的 Button 组件为例，介绍一下如何写`arkcli`的文档

#### 第1步、先完成一个.vue 组件

这一步与我们平时写 vue 文件没有太大区别。只有几点需要注意。

##### a.在写props属性时，建议加上`/** */`这种多行注释。这样写的好处是，`arkcli`在提取props说明时会加上中文注释。效果如下图：

```js
{
  props: {
    /**
     * 标签名
     */
    label: {
      type: String,
      required: true,
    },
    /**
     * 按钮类型
     */
    primary: {
      type: Boolean,
      default: false,
    },
    /**
     * 按钮大小
     */
    size: {
      type: String,
      default: "medium",
      validator: function (value) {
        return ["small", "medium", "large"].indexOf(value) !== -1;
      },
    },
    /**
     * 按钮背景色
     */
    backgroundColor: {
      type: String,
    },
  },
}
```

<img src={propsImg} alt="" />

> 当然你也可以像Button示例里写的那样，在`*.stories.js`文件里，通过`argTypes`属性手动生成props的说明文档。`argTypes`用法见[文档](https://storybook.js.org/docs/vue/api/argtypes)

```js
{
  argTypes: {
    backgroundColor: {
      control: "color", // props里的backgroundColor属性用color控件展示
      description: '手动添加的背景色描述', // 定义props的描述
    },
    size: {
      control: { type: "select" }, // props里的size属性用下拉单选控件展示
      options: ["small", "medium", "large"], // select下拉框选项
    },
  }
}
```

#### b.默认情况下，组件事件是框架自动提取出来的
```js
const Template = (args, { argTypes }) => ({
  props: Object.keys(argTypes), // 定义组件的props
  components: { Button },
  template: '<Button @onClick="onClick" v-bind="$props" />',
})
```
上面story模板里写的`onClick`回调，可以在`argTypes`里进行声明，如下
```js
{
  argTypes: {
    onClick: { action: 'clicked' }
  },
}
```
上面代码的含义是,
触发这个事件后，事件参数被放在`clicked`这个对象里并在`Actions`控件面板里打印出来，如下图:

<img src={actions} alt="" />

另外，通过配置`preview.js`里的`actions: { argTypesRegex: '^on[A-Z].*' }`这行代码，可以进行
全局匹配，告诉框架符合正则的是事件回调函数


更多有关`actions`的用法见[文档](https://storybook.js.org/docs/vue/essentials/actions)

#### 第2步、在\*.stories.\*文件里写我们要展示的文档内容
先用`export default`导出button组件的相关信息，例如组件在文档中展示的标题、属性、事件等等。
然后`export`导出你的story示例。
下面用官网上的一段代码举例(注释部分是为了展示export default里可以配置的内容)，
因为它足够简单，仅用几行代码即可运行：

```js
import { Button } from './Button';

export default {
  title: '组件示例/Button',
  component: Button,
  // 与preview.js导出的parameters作用一样
  // parameters: {
  //   backgrounds: { // Canvas区域工具栏的背景色控件的值
  //     values: [
  //       { name: 'red', value: '#f00' },
  //       { name: 'green', value: '#0f0' },
  //       { name: 'blue', value: '#00f' },
  //     ],
  //   },
  // },
  // 手动设置组件的属性和方法文档展示
  // argTypes: {
  //   size: {
  //     control: { type: 'select' },
  //     options: ['small', 'medium', 'large'],
  //   },
  //   onClick: { action: 'clicked' }
  // },
  // 装饰器，用来在组件ui根元素外部再包一层dom。Story参数代表你的组件
  // decorators: [
  //   (Story) => (
  //     <div style={{ margin: '3em' }}>
  //       <Story />
  //     </div>
  //   ),
  // ],
};

export const Primary = () => <Button primary>Button</Button>;
```

#### 第3步、给story示例取别名
在第二步中，我们已经实现了一个简单的组件文档。左侧导航会有一个`Primary`标题，
这个标题是由`export`导出的变量名决定的。但是在实际开发中我们更多的是用中文描述标题。
此时我们可以在上一步代码后面追加以下代码实现文档标题的重命名
```js
Primary.storyName = '中文标题'
```

#### 第4步、添加更多的story示例
第三步我们完成了`Primary`示例，但是如果我们想给组件加更多示例怎么办？
比如添加大的按钮示例和小的按钮示例，如果像下面这么写：
```js
export const Large = (args, { argTypes }) => ({
  props: Object.keys(argTypes),
  components: { Button },
  template: '<Button @onClick="onClick" size="large" />',
})

export const Small = (args, { argTypes }) => ({
  props: Object.keys(argTypes),
  components: { Button },
  template: '<Button @onClick="onClick" size="small" />',
})
```
这么写虽然可行，但是会有很多重复代码(个别场景会用到上面的写法，例如展示slot插槽)。

首先我们先了解一件事情，我们写组件文档时所展示的组件的不同用法，本质上就是往同一个组件传不同的参数。
比如展示一个大的按钮按钮，我们只需把组件`size`参数改成`large`即可。
`arkcli`提供`Template.bind({})`帮助我们实现这一想法。

具体实现方式是先定义一个可被复用的模板：
```js
const Template = (args, { argTypes }) => ({
  props: Object.keys(argTypes),
  components: { Button },
  template: '<Button @onClick="onClick" v-bind="$props" />',
})
```

然后为每个story示例绑定模板，并修改属性
```js
const Template = (args, { argTypes }) => ({
  props: Object.keys(argTypes),
  components: { Button },
  template: '<Button @onClick="onClick" v-bind="$props" />',
})

export const Large = Template.bind({})
Large.args = {
  size: 'large',
}

export const Small = Template.bind({})
Small.args = {
  size: 'small',
}
```

这样即可实现代码的复用
