# @aloudata/aloudata-design 中文文档

规范地址：https://npmcn.com/package/%40aloudata/aloudata-design/

版本：3\.1\.18
npm 元数据更新时间：2026-11-05T10:17:58.179Z
中文译文更新时间：2026-11-08T01:05:39.406Z
软件包许可：MIT

本文由上游 README 翻译，可能存在偏差，请结合原文核对 API、命令与配置。版权与许可归原作者所有。

原始 npm 页面：https://www.npmjs.com/package/%40aloudata/aloudata-design
原文对照：https://npmcn.com/package/%40aloudata/aloudata-design/?lang=original

## 关键信息（来自 npm 元数据）

- 包体积（解压后）：5.8 MB，1058 个文件
- 模块格式：ES Module
- TypeScript 类型：包内自带
- 运行依赖：36 个
- peer 依赖：dayjs \>=1\.11\.0，react \>=18\.0\.0，react-dom \>=18\.0\.0
- 首次发布：2022-03-02T14:20:04.552Z
- 最新版本发布：2026-11-05T10:17:57.711Z
- 近 30 天下载量：1952（2026-10-06 至 2026-11-04，npm 官方下载统计）
- 已发布版本数：366（近 12 个月 84 个）

## 中文简介

## 简介

## 安装

```sh
npm install @aloudata/aloudata-design
```

也可以使用：`pnpm add @aloudata/aloudata-design`、`yarn add @aloudata/aloudata-design`、`bun add @aloudata/aloudata-design`

## README

# 组件库开发规范

## 简介

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

## Color Governance Documentation

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

## Cursor Interaction

组件交互光标遵循 [Cursor Interaction Contract](https://npmcn.com/package/%40aloudata/aloudata-design/docs/component-governance/cursor-interaction-contract.md)：普通点击、选择、展开和说明触发区默认使用普通箭头；文本输入、拖拽、调整尺寸及已有禁用光标按具体功能保留。Storybook 的 **Foundations / Interaction / Cursor** 可集中验证这些场景。

## Business Project CSS Consumption

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

```css
@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 字体族产品配置合同](https://npmcn.com/package/%40aloudata/aloudata-design/docs/foundation-system/nova-font-family-product-configuration-proposal.md) 已于 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 快速开始

#### 安装和启动

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

#### 创建组件模板

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

#### 组件校验

```bash
  yarn run lint //stylelint、eslint 校验
```

#### 组件测试

```bash
  yarn run test //单元测试
```

#### 组件打包

```bash
  yarn run build //打包
```

#### 组件本地 link

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

### 2 目录结构

```text
.
├── 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 做一定的配置**，具体[配置参考](https://docs.dingtalk.com/i/nodes/mM3zoYAw1Rr8D5Nong2XWnZ07y9NpXxD?dontjump=true&iframeQuery=utm_source%3Dportal%26utm_medium%3Dportal_space_file_tree&navQuery=spaceId%3Da0gX104nML97WzeJ&nav=spaces)

ts 文件使用 _eslint_ 校验， 配置文件 .eslintrc.js [查看规则](https://cn.eslint.org/docs/rules/) less 文件使用 _stylelint_ 校验， 配置文件 .stylelintrc.json [查看规则](https://stylelint.bootcss.com/user-guide/rules/list) 使用 _prettier_ 格式化代码，配置文件 .prettierrc.js

## 组件开发指南（必读）

### 了解组件分类

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

### 单元测试

组件开发过程中需要写单测的，建议先写单测，然后进行开发。[了解 TDD](https://baike.baidu.com/item/TDD/9064369)

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

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

单元测试参考资料：

-   [jestjs](https://jestjs.io/zh-Hans/docs/getting-started)
-   [jest-dom](https://testing-library.com/docs/ecosystem-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 预发进行编写，用于描述组件的文档的信息，如：

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

具体参考：[FrontMatter](https://d.umijs.org/zh-CN/config/frontmatter)

#### 组件场景用例 demo 展示

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

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

关于 demo 的配置，即 code 的用法，请参考[demo 配置](https://d.umijs.org/zh-CN/config/frontmatter#demo-%E9%85%8D%E7%BD%AE%E9%A1%B9)

#### 组件 api 展示

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

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

参考文档：[API](https://d.umijs.org/zh-CN/guide/advanced#%E5%9C%A8%E6%96%87%E6%A1%A3%E4%B8%AD%E5%B1%95%E7%A4%BA-api)

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

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

### 关于组件模板创建

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

## 关于组件库打包

### 一、组件打包

```bash
  npm run build
```

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

### 二、官方网站打包

```bash
  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：

```css
@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 应使用：

```css
@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。

## 按需引用

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

## 常见问题

### @aloudata/aloudata-design 是什么？

简介

### 如何安装 @aloudata/aloudata-design？

在项目目录运行 npm install @aloudata/aloudata-design，或使用 pnpm add / yarn add / bun add。它还需要宿主项目提供 peer 依赖：dayjs（\>=1\.11\.0）、react（\>=18\.0\.0）、react-dom（\>=18\.0\.0）。npm 7 及以上与 pnpm 8 及以上默认会自动安装必需的 peer 依赖，Yarn 需要手动安装。

### @aloudata/aloudata-design 支持 TypeScript 吗？

支持。包内自带 TypeScript 类型声明（package\.json 声明了 types 入口），安装后即可获得类型提示，无需再安装 @types 包。

### @aloudata/aloudata-design 支持 ESM 还是 CommonJS？

以 ES Module 形式发布，推荐使用 import 引入。在 CommonJS 项目中，Node\.js 20\.19\+ / 22\.12\+ 可以直接 require\(\) 不含顶层 await 的 ES Module，更早的版本需要改用动态 import\(\)。

### @aloudata/aloudata-design 可以商用吗？

@aloudata/aloudata-design 使用 MIT 许可。宽松许可：允许商业使用、修改和再分发，通常只需在分发时保留原版权与许可声明。以上为概括，不构成法律意见，请以许可原文为准。

### @aloudata/aloudata-design 的下载量有多少？

根据 npm 官方下载统计，@aloudata/aloudata-design 在 2026/10/06 – 2026/11/04 这 30 天内被下载 1,952 次，日均约 65 次。下载量会把 CI 构建、镜像同步和作为其他包依赖的安装一并计入，适合横向比较热度，不能直接等同于使用人数。

### @aloudata/aloudata-design 还在维护吗？

最新版本 3\.1\.18 发布于 2026/11/05（3 天前）；至今共发布 366 个版本，其中过去 12 个月发布了 84 个；首次发布于 2022/03/02。发布频率只是参考信号：功能稳定的工具可能很少需要更新，建议结合源码仓库的 issue 和提交记录判断。