组件库开发规范
简介
本文档用于介绍组件库开发相关的规范以及组件库开发过程中的注意事项。
Color Governance Documentation
Color System Governance 的唯一入口：docs/color-system/README.md
Cursor Interaction
组件交互光标遵循 Cursor Interaction Contract：普通点击、选择、展开和说明触发区默认使用普通箭头；文本输入、拖拽、调整尺寸及已有禁用光标按具体功能保留。Storybook 的 Foundations / Interaction / Cursor 可集中验证这些场景。
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.
Product UI font-family configuration
Nova 字体族产品配置合同 已于 2026-10-14 批准。Nova 可以通过现有公开 CSS 入口，在其拥有的文档根级配置 --ald-typography-family-ui-sans 为该合同指定的字体栈；已安装 3.1.12 的 CSS 交付面支持此方式，无需新增 Provider。
产品自己的 sans/heading、公开第三方字体配置与默认图表/导出适配应消费同一字体来源。配置必须覆盖同文档 body Portal；独立文档单独交付。仅配置字体能力输出，不逐角色覆盖 family，不修改 code-mono、字号、行高、字距、ALD 角色字重或 Frozen Mapping。其他产品保留现有默认值，具体采用另有产品批准记录。
当前 ConfigProvider.theme、createTheme() 与 themeToCssVars() 没有有效的字体配置链；不要传入未实现的 theme.token.fontFamily。本批准记录不代表新 Runtime API、包发布或 Nova 接入验收已经完成。
环境配置
组件库开发过程中，需要满足以下条件：
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
组件开发指南（必读）
了解组件分类
- 毛坯组件 原始的未做任何修改的 antd 组件
- 简装组件 是指在毛坯组件的基础上，只简单了修改了一些颜色、样式等的组件
- 精装组件 所谓精装组件，是指设计师精心设计过组件应用场景和 UI 的组件，可能基于 antd，也可以完全自定义
单元测试
组件开发过程中需要写单测的，建议先写单测，然后进行开发。了解 TDD
哪些情况需要写单元测试：
- 如果是基于 antd 的组件，但凡组件有 api 接口变动，必须要写单元测试
- 非基于 antd 的组件，必须要写单元测试
- 单元测试需要覆盖组件每一个 api 接口的各个状态
- 单元测试文件以 .test.tsx 结尾
单元测试参考资料：
组件开发注意事项
组件开发支持两种模式，基于 antd 开发和其它自定义开发。
基于 antd 开发: 在业务满足的情况下，建议基于 antd 开发或者 rc 组件开发。方式是把 antd 组件引用过来，然后做升级修改之后，再作为 ald 组件暴露出去
自定义开发： 当 antd 组件不满足业务的时候，可以自定义开发，允许引用其它基础组件进行二次开发或者完全自定义组件进行开发。通常是精装组件。
组件开发有以下几个必须要注意的点
- 组件样式要和组件类进行分离，即在组件开发的过程中，不允许引用 css、less 等样式组件。样式单独写在 style 文件夹下。
- 组件文档内的 api 接口展示，是获取组件属性 props 的接口 interface 定义来实现的（自定义 md 表格除外）。组件库脚手架对于组件接口 interface 有处理，即凡是接口来自于外部库引入的部分，不会被文档 api 识别，即无法展示。interface 接口的每一个想要暴露的属性，都必须要写注释，主要包括类型、描述、默认值等。
- 组件简装及以上，必须要写 demo 样例，用于展示已经支持的样式及功能
- 精装组件必须要写单元测试。每一个组件的属性，都要在测例中进行测试，保证在组件的的维护修改过程中，不会出现 bug。
- 组件由 ts 编写，必须对外暴露所有可能在业务使用过程中需要的 ts 类型。
- 组件库不使用 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 文件中。
- 设计部分用于描述组件的设计理念，内容由设计师提供，可以是链接，也可以是资料等。
- 文档用于描述组件库开发的一些信息等。
- 组件用于展示组件的使用场景用例，组件的一些信息，组件的 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-importstyle 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,
},
];