组件库开发规范

简介

本文档用于介绍组件库开发相关的规范以及组件库开发过程中的注意事项。

环境配置

组件库开发过程中，需要满足以下条件：

Node version >= 16.0.0

组件库介绍

1 快速开始

安装和启动

  git clone https://codeup.aliyun.com/60dd34bf4690c27532d3d021/fe/aloudata-design.git
  cd aloudata-design
  yarn install
  yarn start

创建组件模板

  yarn run cmt //根据指令输入组件名称，创建组件开发模板

组件校验

  yarn run lint //stylelint、eslint 校验

组件测试

  yarn run test //单元测试

组件打包

  yarn run build //打包

组件本地link

  npm link //将组件库link到本地npm
  // 切换到业务项目目录，·引入组件库
  npm link @aloudata/aloudata-design // 业务项目中引入组件库

2 目录结构

.
├── README.md --> readme
├── docs --> 文档目录
│   └── index.md
├── scripts --> 自定义脚本目录
│   └── createComponentTemplate.mjs
├── dist --> 组件打包生成的组件目录
├── src --> 组件目录
├── tsconfig.json --> tsconfig ts配置文件
├── .editorconfig 
├── .eslintrc.js  --> eslint ts等校验规则配置
├── .fatherrc.ts  ---> father组件打包配置
├── .prettierrc.js ---> prettier 代码格式化配置
├── .stylelintrc.json ---> less 校验规则配置
├── .umirc.js          ---> 脚手架配置
├── commitlint.config.js --> commit 配置规则
├── typings.d.ts
├── package-lock.json
├── package.json
├── yarn-error.log
└── yarn.lock

3 代码风格

我们使用eslint+stylelint+prettier 来统一代码风格，同时需要对vscode做一定的配置，具体配置参考

ts文件使用 eslint 校验， 配置文件 .eslintrc.js 查看规则 less文件使用 stylelint 校验， 配置文件 .stylelintrc.json 查看规则 使用 prettier 格式化代码，配置文件 .prettierrc.js

组件开发指南（必读）

了解组件分类

1. 毛坯组件 原始的未做任何修改的antd组件
2. 简装组件 是指在毛坯组件的基础上，只简单了修改了一些颜色、样式等的组件
3. 精装组件 所谓精装组件，是指设计师精心设计过组件应用场景和UI的组件，可能基于antd，也可以完全自定义

单元测试

组件开发过程中需要写单测的，建议先写单测，然后进行开发。了解TDD

哪些情况需要写单元测试：

1. 如果是基于antd的组件，但凡组件有api接口变动，必须要写单元测试
2. 非基于antd的组件，必须要写单元测试
3. 单元测试需要覆盖组件每一个api接口的各个状态
4. 单元测试文件以 .test.tsx 结尾

单元测试参考资料：

• jestjs
• jest-dom

组件开发注意事项

组件开发支持两种模式，基于antd开发和其它自定义开发。

基于antd开发: 在业务满足的情况下，建议基于antd开发或者rc组件开发。方式是把antd组件引用过来，然后做升级修改之后，再作为ald组件暴露出去

自定义开发： 当antd组件不满足业务的时候，可以自定义开发，允许引用其它基础组件进行二次开发或者完全自定义组件进行开发。通常是精装组件。

组件开发有以下几个必须要注意的点

1. 组件样式要和组件类进行分离，即在组件开发的过程中，不允许引用css、less等样式组件。样式单独写在style文件夹下。
2. 组件文档内的api接口展示，是获取组件属性props的接口interface定义来实现的（自定义md表格除外）。组件库脚手架对于组件接口interface有处理，即凡是接口来自于外部库引入的部分，不会被文档api识别，即无法展示。interface接口的每一个想要暴露的属性，都必须要写注释，主要包括类型、描述、默认值等。
3. 组件简装及以上，必须要写demo样例，用于展示已经支持的样式及功能
4. 精装组件必须要写单元测试。每一个组件的属性，都要在测例中进行测试，保证在组件的的维护修改过程中，不会出现bug。
5. 组件由ts编写，必须对外暴露所有可能在业务使用过程中需要的ts类型。
6. 组件库不使用css-module，请考虑权重问题，禁止出现 !important 这样的样式

组件库文档编写注意事项

文档前文frontMatter编写

在组件库官网展示的时候，会根据文档头部的信息，对文档进行分类，我们当前的计划是分成三类：设计、文档、组件；

在文档头部，使用YAML预发进行编写，用于描述组件的文档的信息，如：

---
nav:
  title: 组件
  path: /components
title: Select 选择器
group:
  title: 组件
---

具体参考：FrontMatter

组件场景用例demo展示

每个简装以上组件都需要展示场景用例，写在src/**/demos/文件夹下 demo项目中，像在业务中使用aloudata-design一样，脚手架会自动关联项目到node-modules下。(建议先build一下，然后再进行demo展示) 在组件的md文档中使用code引入用例，在文档中展示用例，如：

<code src="./demos/single/index.tsx" title="单项选择"/>

关于demo的配置，即code的用法，请参考demo配置

组件api展示

api展示为表格形势，可以使用API标签，如：

  <API src="/path/to/your/component.tsx" hideTitle></API>

参考文档：API

也可以自己使用md语法写表格

| 属性 | 描述 | 类型 | 默认值 |
| ---- | ---- | ---- | ---- |
| value | 某个值 | string | 当前选中的值 |

关于组件模板创建

使用 npm run cmt 创建的组件模板只是做一个参考，需要自己根据实际需求进行修改

关于组件库打包

一、组件打包

  npm run build

组件打包的入口在src/index.tsx，必须在文件总暴露出来，组件才会被打包。 组件打包使用umi框架的 falter 打包工具, 具体配置在 .fatherrc.ts中。打包后会生成lib目录，es目录。

二、官方网站打包

  npm run docs:build

官网打包我们默认使用dumi站点模式，会分为设计、文档、组件三个版块，其中设计和文档版块的内容在docs目录下，组件版块的内容在src/**/*.test.md文件中。

1. 设计部分用于描述组件的设计理念，内容由设计师提供，可以是链接，也可以是资料等。
2. 文档用于描述组件库开发的一些信息等。
3. 组件用于展示组件的使用场景用例，组件的一些信息，组件的api接口等

按需引用

[
    'import',
    {
      libraryName: '@aloudata/aloudata-design',
      libraryDirectory: 'dist',
      style:(name)=>{
        return `${name}/style/index.less`
      },
      camel2DashComponentName: false,
    },
]