# @gitlab/ui 中文文档

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

版本：140\.1\.1
npm 元数据更新时间：2026-11-14T13:50:33.761Z
中文译文更新时间：2026-11-16T10:54:34.905Z
软件包许可：MIT

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

原始 npm 页面：https://www.npmjs.com/package/%40gitlab/ui
原文对照：https://npmcn.com/package/%40gitlab/ui/?lang=original
项目主页：https://gitlab.com/gitlab-org/gitlab-services/design.gitlab.com#readme
源码仓库：https://gitlab.com/gitlab-org/gitlab-services/design.gitlab.com

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

- 包体积（解压后）：11 MB，1004 个文件
- 模块格式：ESM + CJS
- TypeScript 类型：未声明
- 运行依赖：9 个
- peer 依赖：vue ^2\.7\.16，pikaday ^1\.8\.0，dompurify \>=2\.5\.2 \<3\.0\.0 \|\| \>=3\.1\.2，emoji-regex \>=10\.0\.0，tailwindcss ^3，@gitlab/svgs ^1\.116\.0 \|\| ^2\.0\.0 \|\| ^3\.0\.0
- 首次发布：2018-11-16T14:26:26.908Z
- 最新版本发布：2026-11-14T13:50:33.592Z
- 近 30 天下载量：408250（2026-10-17 至 2026-11-15，npm 官方下载统计）
- 已发布版本数：2029（近 12 个月 151 个）

## 中文简介

GitLab 用户界面组件

## 安装

```sh
npm install @gitlab/ui
```

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

## README

# GitLab 用户界面

GitLab UI 是一个执行 UI 组件库 [帕贾马斯](https://design.gitlab.com/)我们 设计系统。 GitLab 用户界面以 [Vue.js (英语)](https://vuejs.org/) 其目标是:

-   创建可重复使用的UI组件来加速前端开发.
-   为 GitLab 内的所有组件创建 UI 一致性 .

见 [https://dedesign.gitlab.com/史地书](https://design.gitlab.com/storybook) 用于文档.

## 使用量

1.  要在您的工程中使用 GitLab UI, 请添加为依赖 :
    
    ```sh
    yarn add @gitlab/ui
    ```
    
    > **说明:** 确保同时安装 GitLab UI 的对等依赖性 。 参见 [`package.json`](https://npmcn.com/package/%40gitlab/ui/package.json) 用于对等关系依赖及其预期版本的列表.
    
2.  在主入口处 **在此之前** 导入或使用任何组件:
    
    ```javascript
    import setConfigs from '@gitlab/ui/dist/config';
    
    setConfigs();
    ```
    
    这将设置 GitLab UI 所使用的全局配置 .
    
3.  在应用程序中包含所需的样式表 。 参见 [CSS 文档](https://npmcn.com/doc/css.md) 页:1 安装选项.
    
4.  按要求导入组件 :
    
    ```javascript
    import { GlButton } from '@gitlab/ui';
    ```
    
    > **说明:** GitLab UI 兼容树摇动, 您可以在您的工程中启用此功能 减少捆绑大小.
    

## 快速启动 - 开发

**说明:** GitLab UI不是设计在Windows本土上建造的. 无论是 [WSL 维基月球](https://learn.microsoft.com/en-us/windows/wsl/) 或者说 [GitPod 图像](https://www.gitpod.io/docs/configure/authentication/gitlab) 可用于设置 类似UNIX的环境来建造它.

填写 [项目设置](https://npmcn.com/package/README.md#project-setup) 在寄存器根 README 中,然后 建立和发布故事书:

```sh
cd packages/gitlab-ui
yarn storybook
```

转到 [http://localhost:9001/ (英语)](http://localhost:9001/)

## 测试

### 单位测试

组件单位测试在 `tests/components`测试按以下顺序进行: 用于组织组件的目录结构.

-   `yarn test:unit` 运行所有单位测试.
    
-   `yarn test:unit:watch` 在监视模式下运行所有单元测试.
    
-   `yarn test:unit:debug` 运行所有单元测试,并允许在测试跑道过程中附加调试器.
    
-   `yarn jest [name_pattern]` 运行符合指定名称模式的 spec 文件.
    

#### 实例

-   `yarn jest datepicker` 将所有 spec 文件匹配到包含单词的名称 _选取日期_。 。 。 .
    
-   `yarn jest datepicker -t "when draw event is emitted"` 更远一步,只进行测试 带有一个符合向 `t` 旗帜.
    

### SCSS测试

尽管我们尽量避免写复杂的SASS代码来维持CSS的复杂程度 执行了一些从自动化测试中受益的功能。 SASS测试现场直播 `tests/scss` 目录。 GitLab 用户界面 [真实的](https://www.oddbird.net/true/) 实施这些测试 开玩笑的.

`yarn jest run_scss_tests` 运行所有SCSS测试.

### 视觉回归测试

GitLab UI 使用视觉快照测试来防止带 CSS 和 组件的布局变化。 更多关于这一点,请在 [视觉测试文件](https://npmcn.com/package/%40gitlab/ui/doc/contributing/visual_testing.md)。 。 。 .

#### GitLab 视觉回归测试

GitLab UI 组件是参考执行 [睡衣设计系统组件](https://design.gitlab.com/components/status)。这些组成部分 设计系统规格应当与设计系统规格相一致,在睡衣网站和 gitLab产品。 请看 [用 GitLab 产品 CSS 调试 GitLab UI 发行](https://npmcn.com/package/%40gitlab/ui/doc/debugging-gitlab-ui-with-gitlab-css.md) 用于 GitLab 产品 CSS 的调试问题.

### 结束测试

结束测试的组件在 `cypress/e2e` 文件夹。 看我们的 [结束测试文档](https://npmcn.com/package/%40gitlab/ui/doc/contributing/end_to_end_test.md) 更多细节.

`yarn run cypress open` 运行 Cypress 本地端以运行结束测试 .

### 设计符号

GitLab UI使用设计符号来维持一个单一的真理源,通过自动化, 可用于不同的用途。 更多关于这一点,请在 [设计符号文档](https://npmcn.com/package/%40gitlab/ui/doc/contributing/design_tokens.md)。 。 。 .

## 释放

见 [更新 GitLab 用户界面软件包](https://npmcn.com/package/%40gitlab/ui/doc/updating-gitlab-ui-packages.md) 如何使用 `@gitlab/ui` 在各种项目中不断更新软件包.

要出版GitLab UI的新版本,请参看 [出版软件包](https://npmcn.com/package/doc/publishing-packages.md)。 。 。 .

## 贡献指南

请审查 [设计系统贡献过程](https://design.gitlab.com/contribute/contributing) 如何为帕贾马斯做出贡献.

关于GitLab UI的具体细节,参见 [向GitLab UI捐款](https://npmcn.com/package/%40gitlab/ui/CONTRIBUTING.md) 页:1 增加资源和指南.

### 问题

有问题吗? 看看我们 [财务问题](https://npmcn.com/package/%40gitlab/ui/FAQ.md)你也许能找到答案.

## 常见问题

### @gitlab/ui 是什么？

GitLab 用户界面组件

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

在项目目录运行 npm install @gitlab/ui，或使用 pnpm add / yarn add / bun add。它还需要宿主项目提供 peer 依赖：vue（^2\.7\.16）、pikaday（^1\.8\.0）、dompurify（\>=2\.5\.2 \<3\.0\.0 \|\| \>=3\.1\.2）、emoji-regex（\>=10\.0\.0）、tailwindcss（^3）、@gitlab/svgs（^1\.116\.0 \|\| ^2\.0\.0 \|\| ^3\.0\.0）。npm 7 及以上与 pnpm 8 及以上默认会自动安装必需的 peer 依赖，Yarn 需要手动安装。

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

该包的 package\.json 没有声明类型入口。需要类型提示时，可以在 npm 上查找社区维护的 @types/gitlab\_\_ui 是否存在。

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

同时提供 ES Module 与 CommonJS 入口，import 和 require\(\) 都可以使用，打包工具会自动选择合适的版本。

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

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

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

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

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

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

