# @ferlab/ui 中文文档

规范地址：https://npmcn.com/package/%40ferlab/ui/

版本：10\.35\.7
npm 元数据更新时间：2026-07-17T18:07:11.511Z
中文译文更新时间：2026-11-14T14:39:41.823Z
软件包许可：SEE LICENSE IN LICENSE

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

原始 npm 页面：https://www.npmjs.com/package/%40ferlab/ui
原文对照：https://npmcn.com/package/%40ferlab/ui/?lang=original
项目主页：https://github.com/Ferlab-Ste-Justine/ferlab-ui#readme
源码仓库：https://github.com/Ferlab-Ste-Justine/ferlab-ui

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

- 包体积（解压后）：5 MB，2126 个文件
- 模块格式：ES Module
- TypeScript 类型：包内自带
- 运行依赖：28 个
- peer 依赖：antd ^4\.24\.16，react ^18\.3\.1，date-fns ^2\.29\.3，react-dom ^18\.3\.1，@sentry/react ^8\.23\.0，rc-tree-select ^5\.4\.0
- 首次发布：2021-02-16T14:03:33.801Z
- 最新版本发布：2026-06-30T18:51:05.273Z
- 近 30 天下载量：4958（2026-10-15 至 2026-11-13，npm 官方下载统计）
- 已发布版本数：685（近 12 个月 13 个）

## 中文简介

科学研究数据门户的核心组成部分

## 安装

```sh
npm install @ferlab/ui
```

也可以使用：`pnpm add @ferlab/ui`、`yarn add @ferlab/ui`、`bun add @ferlab/ui`

## README

# @ferlab-ui (法语) 反应核心组件

## 安装

```
npm i @ferlab/ui
```

## 开发者

-   所有工作都要靠主人来完成
-   所有样式自动引用到 @ ferlab/ 样式包
-   应增加部件和试验 [故事书](https://npmcn.com/package/storybook)

### 发展

在真实项目中开发或调试库的步骤

1.  让 @ ferlab/ ui 进入链接
    1.  `npm link` @ ferlab/ ui 文件夹内
2.  链接您的项目中的库
    1.  `npm link @ferlab/ui`

#### 复制重现

##### Tsconfig 解决方案

链接库将两次在捆绑中添加软件包,这将产生一些问题 `react` 财务报告和审定财务报表 `react-dom`,使用主机模块需要添加一个别名.

例如,在tsconfig中,请参考 [clin-portal-ui (英语)](https://github.com/Ferlab-Ste-Justine/clin-portal-ui) 以实例为例.

```json
{
    "compilerOptions": {
        "baseUrl": ".",
        "paths": {
            "react": ["node_modules/react"],
            "react-dom": ["node_modules/react-dom"]
        }
    }
}
```

其他解决方案:

npm 将工程节点/反应链接到 ferlab/ ui

##### Npm 链接解决方案

当您使用 npm 链接或等效链接时, 这个问题也可能出现 。 在这种情况下,您的捆绑者可能会“看到”两个反应——一个在应用程序文件夹中,一个在您的图书馆文件夹中。 假设我的应用程序和我的lib是兄弟文件夹, 一个可能的修补是运行 `npm link ../myapp/node_modules/react` 从我的lib。 这将让库使用应用程序的反相副本.

### 故事书

为了查看和测试所有可用的组件

首先,你需要构建组件

> npm 运行构建

或以开发模式运行

> npm 开始

```bash
cd ferlab-ui/storybook
npm start
```

### 发布新版本

### **更新** 蚂蚁d

蚂蚁有时在非破损的活塞中会有断裂变化. 降低多个项目阻碍发展的风险. 我们应该遵循步骤,更新任何与蚂蚁设计相关的内容.

1.  创建只包含 antd 更新的 pr
2.  创建 npm 发布候选人 例如:7.9.10-弧1
3.  在生产(clin, kids first)中将RC发布于出入口上.
    
    > Clin拥有特征分支QA环境,不需要在QA发布.
    

#### 合并新的变化

1.  更新套件中的版本. json ([https://semver.org (英语)](https://semver.org/)(中文(简体) )
2.  更新 `Release.md` 带有更改的文件
3.  添加或修改匹配您修改的故事本
4.  创建 PR

#### 发布到 npm

**说明 :** 本节概述了出版一包到npm的过程. 当分支合并到 `master` 树枝。 如果软件包版本已经存在,则会跳过发布进程来避免冲突.

**步骤 :**

1.  更新 `package.json` 版本为想要的版本,用于发布.
2.  为修改创建一个拉动请求(PR).
3.  将 PR 合并到 `master` 树枝.
4.  确保GitHub行动在进行之前圆满完成.

#### 出版发行候选人(RC)

**说明 :** 发布候选人(RC)的目的是在将更改合并为主要分支之前彻底测试. 它允许在成为正式发布的一部分之前在特征分支中测试具体的更改.

**步骤 :**

1.  当拉动请求启动时会自动创建一个特性分支.
2.  在特性分支中,添加一个 `package.json` 带有后缀的版本 `-rc[number]`,例如 `8.5.6-rc2`,以表示它是释放候选人.
3.  将公关标为“ 尚未准备好进行MERGE ” , 以表示不应合并为 `master` 树枝.
4.  驻地协调员PR应经过测试和验证,但不应并入 `master` 树枝。 其目的是确保在正式释放前进行彻底测试.

#### 手动发布到 npm (如果自动发布出错)

1.  尝试安装软件包,以确保一切工作都精细
    
    > cd \[测试 dir\] && npm i \[full path\]/ferlab-ui/packages/ui\] (中文(简体) )
    
2.  删除要删除的核心文件夹文件
    
    > rm - rf 核心/ 常规
    
3.  准备包裹
    
    > npm 运行构建
    
4.  按下新版本
    
5.  创建新版本的标签 `git tag ui@[semantic version]` 譬如说.
    
    > git 标签 [ui@4.4.1](mailto:ui@4.4.1) git 推动 -- -- tags
    
6.  登录到 npm
    
    > npm 登录
    
7.  按下新版本
    
    > npm 发布
    

## 发展

运行 `npx tscp -w` 用于现场观察 sass文件.

## 样式和主题

### 战略

1.  . 少用自定义颜色和蚂蚁设计组件
2.  导出为主题和自定义组件的 scs
3.  每个组件使用一个 css 模块和 scs
4.  使用 scs 导出变量进行道具和内置样式( 尽可能避免)

颜色变量命名公约应当遵循蚂蚁设计主题的实施

#### 动机

-   访问 JS 的主题变量
-   访问 Css 模块中的主题变量 + scs
-   与其他项目和组成部分的兼容性
-   不要强迫CRA弹出

#### 结构

```
[project]
  |-- theme/                :> Legacy styles
  |-- style/                :> Main style/theme source
    |-- dist/               :> dynamicaly generated files
      |-- themes
        |-- default/        :> default theme, to load in code
          |-- antd.css      :> load in main app, rewrite ant design default
          '-- _colors.scss   :> dynamically generated colors from ant design theme in colors.less
    |-- themes/
      |-- default           :> default theme (default could for example point to v1 or v2 etc.)
        |-- antd/           :> not use directly in the code
        | |-- antd.less
        | '-- colors.less
        |-- _colors.scss        :> Ant design colors to import from other scss files or JavaScript
        |-- colors.modules.scss :> Colors classes and variables to be uses inside jsx (className)
        '-- main.scss      :> General style for the site outside ant design component
```

所有遗留下来的东西 `src/theme/` 应该进去 `src/style/theme/default/main.scss` 或者说 `src/style/theme/default/colors.scss`

### 配置

#### 参考资料

[设计可用的主题变量](https://github.com/ant-design/ant-design/blob/master/components/style/themes/default.less)

#### 使用

主应用程序文件中的第一个导入蚂蚁设计覆盖

```JavaScript
import 'themes/dist/themes/default/antd.css';
import 'themes/default/main.scss';
```

#### 构成部分

1.  创建一个 `[Component].module.scss` 在同一目录中的文件
2.  在组件中导入您的样式

```JavaScript
import style from '[Component].module.css'
// ...
return () => <div clasName={style.isBeautiful}></div>;
```

3.  要使用全局定义的主题变量,请从 `src/themes/default/colors.scss` 或者说 `src/themes/default/main.scss`

#### 如何将 scs 变量导出到 JavaScript

在 scs 文件内,请使用 `export key` 将它们提供给 JavaScript 。 使用与组件相同的技术 `.module.scss` 在《联合提交的材料》中.

譬如说.

```scss
:export {
    btnPrimaryBg: $btn-primary-bg;
    btnPrimaryColor: $btn-primary-color;
}
```

链接问题:

```
In packages/ui:
rm -rf core
npm i
npm run build
npm remove --global @ferlab/ui
npm link
npm link ~/[project path]/nodes-module/react

Then in local projet:
npm unlink @ferlab/ui
npm link @ferlab/ui
npm start
```

## 常见问题

### @ferlab/ui 是什么？

科学研究数据门户的核心组成部分

### 如何安装 @ferlab/ui？

在项目目录运行 npm install @ferlab/ui，或使用 pnpm add / yarn add / bun add。它还需要宿主项目提供 peer 依赖：antd（^4\.24\.16）、react（^18\.3\.1）、date-fns（^2\.29\.3）、react-dom（^18\.3\.1）、@sentry/react（^8\.23\.0）、rc-tree-select（^5\.4\.0）。npm 7 及以上与 pnpm 8 及以上默认会自动安装必需的 peer 依赖，Yarn 需要手动安装。它还提供命令行工具 ferlabui-script、ferlabui-less2css，可以用 npx ferlabui-script 直接运行。

### @ferlab/ui 支持 TypeScript 吗？

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

### @ferlab/ui 支持 ESM 还是 CommonJS？

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

### @ferlab/ui 可以商用吗？

@ferlab/ui 使用 SEE LICENSE IN LICENSE 许可。许可条款写在包内的独立文件中，请阅读该文件确认可否商用。以上为概括，不构成法律意见，请以许可原文为准。

### @ferlab/ui 的下载量有多少？

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

### @ferlab/ui 还在维护吗？

最新版本 10\.35\.7 发布于 2026/07/01（4 个月前）；至今共发布 685 个版本，其中过去 12 个月发布了 13 个；首次发布于 2021/02/16。发布频率只是参考信号：功能稳定的工具可能很少需要更新，建议结合源码仓库的 issue 和提交记录判断。