组件库开发规范

简介

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

Color Governance Documentation

Color System Governance 的唯一入口：docs/color-system/README.md

Business Project CSS Consumption

Business Project 应通过正式 CSS Consumer Entry 消费 ALD 的 CSS Variables Public Web Surface：

@import '@aloudata/aloudata-design/css';

该入口只提供已交付的 CSS Variables Public Web Surface；不提供 Dynamic Brand API、Runtime API、createTheme() 或 initAldTheme()。不要依赖 dist 内部路径或其他未声明 package subpath。

Component consumption and CSS Variables consumption are independent public delivery surfaces. Using one does not grant access to the other.

环境配置

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

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 接口等

CSS Variables 与组件消费边界

CSS Variables Public Web Surface 与组件按需引用属于不同 Consumer Entry。

Component Consumption

组件消费用于：

• React Component API。
• Component style assets。
• Component-level usage。

组件消费继续遵循组件按需引用规范。

CSS Variables Consumption

CSS Variables Consumption 用于：

• Design System Color Foundation Public Web Surface。

Business Project 应通过正式 CSS Consumer Entry 消费已交付 CSS Variables：

@import '@aloudata/aloudata-design/css';

该入口不提供：

• Component API。
• Dynamic Brand API。
• Runtime API。
• createTheme()。
• initAldTheme()。

Boundary

Business Project 不应：

• 通过组件 Less / style 文件消费 CSS Variables Public Web Surface。
• 依赖 dist 内部路径。
• 使用未声明 package subpath。
• 直接访问 Runtime、Generator 或 Token Output Contract。

CSS Entry 解决如何消费已交付 CSS output；它不解决如何生成 Dynamic Brand output。它不会开放 createTheme()、initAldTheme() 或任何 Brand runtime capability。

Component On-demand Import

以下配置仅用于 React Component 按需引用。该消费方式属于 Component Consumption，不属于 CSS Variables Public Web Surface Consumption。

组件按需引用用于：

• React Component API。
• Component style assets。
• Component-level usage。

CSS Variables Public Web Surface 应使用：

@import '@aloudata/aloudata-design/css';

不要通过以下方式消费 CSS Variables Public Web Surface：

• Component style import。
• Less 文件。
• babel-plugin-import style path。
• dist 内部文件路径。

Component API 与 CSS Variables Public Surface 是两个独立的 Public Delivery Surface。

按需引用

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