develop.md

Develop

开发文档，如何从头开始开发一个组件

1. Prepare

下载源代码 https://github.com/jdthfe/eui/tree/master

安装依赖

yarn install

切换一个新分支

2. Lint

为了规范开发，代码使用了严格的 eslint 、prettier 和 stylelint。推荐使用辅助插件，达到保存文件时自动格式化代码的效果。

以 vscode 为例

1. 安装并启用扩展 Eslint 、Prettier - Code formatter 、stylelint（选择工作区启用，防止影响其他项目）

2. 基于 vscode，增加如下配置

   {
       // 增加测试快照可读性
       "files.associations": { "*.ts.snap": "html" },
       // 储存时自动格式化
       "editor.formatOnSave": true,
       // 允许在如下语言中提示错误和自动修复
       "eslint.validate": [
           "javascript",
           "javascriptreact",
           { "language": "typescript", "autoFix": true },
           { "language": "typescriptreact", "autoFix": true }
       ],
       // 关联 prettier & stylelint
       "prettier.stylelintIntegration": true
   }

3. ctrl + p | command + p ，输入 >reload window，重载窗口

4. 完成！可以通过保存来自动格式化文件了

3. New

辅助开发所使用的脚本，详细说明请查看 scripts.md

本地启动项目

yarn dev

新建一个组件

yarn new

假设新组建名字为 Learn，下面将会依次介绍生成的文件

---

src/Learn/index.tsx �

import React from 'react';
// 辅助 className 拼接 https://github.com/JedWatson/classnames#readme
import classnames from 'classnames';
import { LearnProps } from './PropsType';
// 组件通用前缀
import { prefix } from '../_util/';
const prefixCls = `${prefix}-learn`;

//  如果组件中包含其他组件，禁止从 src/index 中引入
//  应该直接从同级引入。eg:
//  import TouchFeedback from '../TouchFeedback';

//  引入通用变量
// import { Variable } from '../../_util/';
// const { transitionFade } = Variable;

// Function Component
const Learn = (props: LearnProps) => {
    //  如果某属性为选填，请赋初始值。必填属性不赋值
    //  api 脚本会读取此处的初始值在 readme 中生成表格
    const { prop = 'default', className, children, ...restProps } = props;
    const cls = classnames(prefixCls, className);
    return (
        <div {...restProps} className={cls}>
            {prop} | {children}
        </div>
    );
};

export default Learn;

有关函数组件的格式和写法，请参考 MessageBox、Toast 组件

---

src/Learn/PropsType.tsx �

//  组件需要继承 return 的最外层元素的属性
//  在 index.tsx 文件中，可以通过鼠标悬停在对应元素上，来查看属性全称
//  默认是 div 的属性
export interface LearnProps extends React.DetailedHTMLProps<React.HTMLAttributes<HTMLDivElement>, HTMLDivElement> {
    // 属性的描述必须用 /** contentn */ 注释，并且使用英文
    /** description */
    prop?: string;
}

有关函数组件属性的格式和写法，请参考 MessageBox、Toast 组件

有关封装用组件属性的格式和写法，请参考 TouchFeedback、Cover 组件

---

src/Learn/style/index.scss �

//  组件样式，组件内禁止使用特定 px 值，必须引用变量。方便修改
@import '../../style/mixin';
$learn-prefix: $preifx + '-learn';

.#{$learn-prefix} {
    text-decoration: underline;
}

---

src/Learn/demo/index.tsx �

demo 文件用于展示、说明和测试组件效果，建议提供覆盖组件中所有 api 的样例

import React from 'react';
//  如果组件中包含其他组件，请按如下方式引入
import { Learn } from '@src/index';
const Demo = () => {
    return (
        <div className="Learn">
            <Learn>children</Learn>
            <Learn prop={'Hello World'}>children</Learn>
        </div>
    );
};

export default Demo;

---

src/Learn/demo/readme.md �

src/Learn/demo/readme.zh-CN.md � 请在对应语言的文档中使用对应语言

如果需要新增语言

1. 所有存在 *.zh-CN.md 的文档都需要新增对应语言文档。
2. 全局搜索 !tag new language，增加新语言代码。

（标题会自动添加于此，请到 site/\_util/componentIndex.tsx 中完善组件的其他语言名称）

description

（demo 源码会自动添加在 ## Demo 之下，请勿删除 ## Demo）

## Demo

other description

## API

| Properties | Descrition  | Type     | Default     | Required |
| ---------- | ----------- | -------- | ----------- | -------- |
| prop       | description | `string` | `'default'` | `false`  |

（运行 yarn api 之后会生成新的 api table 在此，请复制并粘贴到其他语言中修改）

---

src/Learn/__testS__/demo.test.tsx �

通用测试，生成 demo 文件运行之后的快照。一般不需要修改

import webDemoTest from '@tests/shared/demoTest';
webDemoTest('Learn');

---

src/Learn/__testS__/index.test.tsx �

对 demo 测试中未覆盖到处进行补充

describe('Learn', () => {
    // Supplement uncovered test
    it('trigger event correctly', () => {
        expect(true).toBe(true);
    });
});

4. Test

运行 yarn test Learn 可以测试单组件，并且生成覆盖率报告在 src/Learn/__testS__/coverage 中 �

请参照覆盖率报告，补充组件的测试直到覆盖率大于 90%

测试写法可以参照已有组件，在此不再赘述

提交之前务必运行 yarn test 测试全部组件，确保测试通过

页面 build 部署、npm 提交等均由 Travis 脚本自动完成，详细配置在 .travis.yml 中

5. Prod

yarn prod

将生成打包完成的组件，用以本地使用或者单独发布