# @eccenca/gui-elements 中文文档

规范地址：https://npmcn.com/package/%40eccenca/gui-elements/

版本：26\.2\.1
npm 元数据更新时间：2026-11-02T13:20:57.758Z
中文译文更新时间：2026-11-13T04:52:02.772Z
软件包许可：Apache-2\.0

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

原始 npm 页面：https://www.npmjs.com/package/%40eccenca/gui-elements
原文对照：https://npmcn.com/package/%40eccenca/gui-elements/?lang=original
项目主页：https://github.com/eccenca/gui-elements
源码仓库：https://github.com/eccenca/gui-elements

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

- 包体积（解压后）：4.6 MB，2157 个文件
- 模块格式：ESM + CJS
- TypeScript 类型：包内自带
- Node.js 要求：\>=18\.19\.0
- 运行依赖：41 个
- peer 依赖：react \>=18，@blueprintjs/core \>=6
- 首次发布：2018-01-24T13:03:38.923Z
- 最新版本发布：2026-11-02T13:20:57.594Z
- 近 30 天下载量：4769（2026-10-13 至 2026-11-11，npm 官方下载统计）
- 已发布版本数：165（近 12 个月 31 个）

## 中文简介

基于其他库的图形用户界面元素,可用于React应用程序,用Typescript写成.

## 安装

```sh
npm install @eccenca/gui-elements
```

也可以使用：`pnpm add @eccenca/gui-elements`、`yarn add @eccenca/gui-elements`、`bun add @eccenca/gui-elements`

## README

# 精密图形界面元素

基于 [帕兰蒂尔蓝图JS](https://blueprintjs.com/) 财务报告和审定财务报表 [IBM 碳](https://www.carbondesignsystem.com/),用于 [公司记忆](https://eccenca.com/products/enterprise-knowledge-graph-platform-corporate-memory) 应用.

## 使用量

### 安装

我们提供 [通过 npmjs 注册的软件包](https://www.npmjs.com/package/@eccenca/gui-elements),通过:

```
yarn add @eccenca/gui-elements
```

也可以作为Git子模块包含在您的项目中,并通过纱线链接或纱线工作空间使用.

只要IBM Carbon不支持类型Script,就有必要安装 `@types/carbon-components-react` 发展依赖:

```
yarn add --dev @types/carbon-components-react
```

### 包含

-   添加所有基本组件的SCSS样式 `@import "~@eccenca/gui-elements/index";` 输入您的 SCSS 主文件 .
-   要使用扩展和特殊公司内存组件,包括 `@eccenca/gui-elements/extensions` 财务报告和审定财务报表 `@eccenca/gui-elements/cmem` 有必要
-   只包含默认配置 `@import "~@eccenca/gui-elements/src/configuration/variables;` 输入您的 SCSS 文件 .

### 配置

全体 [配置变量](https://github.com/eccenca/gui-elements/blob/develop/src/configuration/_variables.scss) 可以在导入完整库或默认配置之前设置, 但对于主要属性, 您只需要修改几个参数

#### 颜色

自从v25以来,我们使用一个彩色调色板作为颜色配置的基本基础. 调色板被定义为4个部分,包含各种颜色的锡,每个锡包括从100(浅色)到900(暗色)的5个不同的重量.

默认调色板如果在配置或完整库导入到您的 Sass 样式之前被定义,则可被覆盖 。 调色板需要完全定义,我们目前不支持部分覆盖.

```
$eccgui-color-palette-light: (
    "identity": (
        "brand": #fae1cc #f8cd99 #f6b966 #f4a533 #f29100,
        "accent": #e5f4fb #aecfe3 #77abca #4186b2 #0a6199,
        "text": #f8f8f8 #bcbcbc #818181 #434343 #090909,
        "background": #fff #e8e8e8 #d6d6d6 #d4d4d4 #d3d3d3,
    ),
    "semantic": (
        "info": #e5f4fb #aecfe3 #77aaca #4086b2 #096199,
        "success": #e8f5e9 #b2c6b4 #7c967e #466749 #103713,
        "warning": #fff3e0 #fad2b3 #f5b287 #f0915a #eb702d,
        "danger": #fff5f6 #edbfc0 #db8989 #c95253 #b71c1c,
    ),
    "layout": (
        "yellow": #fff6d5 #f1ecb5 #e3db79 #d4c93c #c1a500,
        "purple": #f4ddf3 #c8a2d1 #9d6eb8 #71378f #480e75,
        "magenta": #ffd8e8 #f5a6c3 #e276a4 #be4c80 #59122d,
        "pink": #fde4f1 #e6b4ce #d08aae #bb5f8e #711c4d,
        "violet": #f4e3f4 #d8b0d8 #b377b3 #904490 #570057,
        "indigo": #efe4fb #b89ee0 #8f72c5 #6547aa #3b1e8f,
        "cyan": #dff9fc #86d6e5 #5abfd4 #2da9c4 #0092b3,
        "teal": #d4f2ec #a3ddd3 #6dc0b2 #479d8d #104c42,
        "lime": #cde0d6 #bce3c2 #9dcd99 #7ba66c #87b347,
        "amber": #ffe7b8 #ffe9c4 #f9cd8d #eeb757 #ef8f00,
        "vermilion": #ffd8cc #e4c4ba #b27a6b #8c4b3a #651c09,
        "grey": #f5f6f7 #b7b7b7 #808080 #484848 #1c2329,
    ),
    "extra": (
        "gold": #fff7d5 #ebd893 #dfc670 #d3b44e #c7a22b,
        "silver": #f0f0f0 #dedede #ccc #bababa #a8a8a8,
        "bronze": #fbe9db #f2d6bc #eac29d #e1af7e #d89b5f,
    ),
);
```

所有调色板颜色将自动被转换为 CSS 自定义属性,并可以通过名称方案来引用 `--eccgui-color-palette-{groupname}-{colortint}-{colorweight}`,比如说. `--eccgui-color-palette-identity-brand-100`。 。 。 .

其他所有颜色都以调色板为主,但在默认值被导入配置或完整库之前仍有可能设置出几个特殊的颜色配置.

-   `$eccgui-color-applicationheader-text`
-   `$eccgui-color-applicationheader-background`
-   `$eccgui-color-workspace-text`
-   `$eccgui-color-workspace-background`

#### 大小

-   `$eccgui-size-typo-base`: 大小,包括绝对单位,目前只有 `px` 获得支持
-   `$eccgui-size-typo-base-lineheight`: 仅与字体大小之比,无单位!
-   `$eccgui-size-type-levelratio`: 没有单位的比例 ! 用于根据 `$eccgui-size-typo-base`
-   `$eccgui-size-block-whitespace`: 块级元素之间的空白, 目前仅此 `px` 获得支持

## 发展

### 部门管理

我们有四类主要分支代表现状:

-   `main`: 包含最新官方发布,仅限 `release/*` 分会合并到这个分会
-   `develop`:包含最新发展情况, `feature/*`, (中文(简体) ), `bugfix/*` 财务报告和审定财务报表 `next` 将合并为 `develop`
-   `next`: 即将到来的新主要版本的开发树,将合并为 `develop` 在某个时候, `feature/*`, (中文(简体) ), `bugfix/*` 财务报告和审定财务报表 `release/*` 分行将合并到其中
-   `legacy`: 当前主要版本的前身开发树,仅限 `bugfix/*` 财务报告和审定财务报表 `hotfix/*` 分行将合并到其中

我们允许为有效的分支名称添加几个前缀 :

-   `feature/*`: 扩展功能
-   `fix/*`, (中文(简体) ), `bugfix/*`, (中文(简体) ), `hotfix/*`: 固定功能
-   `release/*`: 分会最终确定发布,也用于发布发布候选软件包
-   `change/*`, (中文(简体) ), `temp/*`, (中文(简体) ), `test/*`:不具体的改变,也许只是为了测试一些不一定会在 PR 中结束的东西
-   `maintain/*`: 保持依赖关系,在出版过程中产生的变化

`next` 财务报告和审定财务报表 `legacy` 只有在必要时才存在,否则我们不维持这些分支。 合并为 `main`, (中文(简体) ), `develop`, (中文(简体) ), `next` 财务报告和审定财务报表 `legacy` 总是通过拉取请求来管理.

### 正在测试

运行 Jest 测试 `yarn test`,用于测试覆盖信息运行 `yarn test:coverage`。 。 。 . 您可以通过 : `yarn compile` (JS/Typescript)和 (中文(简体) ) `yarn compile-scss` (特别事务厅).

如果您使用我们的库在应用程序中运行 Jest 测试, 您需要安装 `@babel/plugin-transform-runtime` 作为开发依赖,并添加到您的 Babel 插件配置中.

### 运行故事本

所有的故事源文件都保存在相应的组件、扩展和 cm 文件夹中,使用 `*.stories.tsx` 文件名图案. 运行故事本

```
yarn install
yarn storybook
```

如果您想要将 Jest 测试结果纳入故事本, 请运行 `yarn test:generate-output` 在此之前 `yarn storybook`。 。 。 . 如果故事和测试在文件名中准确分享了相配名称,例如. `Button.stories.tsx` 财务报告和审定财务报表 `Button.`,然后在测试输出可用时自动包括测试. 如果文件名称无法以图案相匹配, 那么测试文件名称需要在故事中配置 :

```javascript
Default.parameters = {
    jest: "MyTestFile.test.tsx",
};
```

### 命名公约

-   使用一个 `*Props` 组件接口的后缀.
-   使用一个 `*Utils` 后缀用于为相通性提供辅助函数的对象. 名称应该从小写字母开始.

别忘了出口. 它们需要通过简单的导入从 `@eccenca/gui-elements`。 。 。 .

示例:如果您拥有 `SimpleComponent` 然后至少提供 `SimpleComponentProps`也许 `simpleComponentUtils`。 。 。 .

### 通过雅尔克语使用

必要时可以使用 [雅尔克语](https://github.com/wclr/yalc) 用于同时开发 gui 元素和您的应用程序.

1.  通过 npm 或 纱线在全球安装 yalc
2.  离职 [@ cecenca/ gui- 要素](https://github.com/eccenca/gui-elements)
3.  居伊元素文件夹内 : `yarn build:all && yalc publish --push`
4.  在您的应用程序文件夹中 : `yalc add @eccenca/gui-elements`
5.  更新到 Gui 元素后, 重建并更新应用程序 yalc 文件夹 : `yarn build:all && yalc publish --push` (通常不要求你开枪) `yalc add` 在应用程序文件夹中)

在本地测试了 GUI 元素包后, 您可以清理您的应用程序文件夹 `yalc remove --all && git checkout -- pakage.json yarn.lock`。 。 。 .

### 调取请求和发布新闻稿的程序

1.  `feature/*` 财务报告和审定财务报表 `bugfix/*` 分支合并为 `develop` (或 `next` 财务报告和审定财务报表 `legacy`(通过拉动请求)
    -   要通过 npm 软件包测试特定特性或错误修正,可以通过使用 ["publish:功能/固定前放出"动作](https://github.com/eccenca/gui-elements/actions/workflows/publish-featurefix-prerelease.yml)
2.  `release/*`分支创建于 `develop` (或 `next` 财务报告和审定财务报表 `legacy`)通过 ["创造:释放分支"](https://github.com/eccenca/gui-elements/actions/workflows/create-release-branch.yml),将自动创建拉动请求
    -   通过触发 : ["波兰语:释放候选人"](https://github.com/eccenca/gui-elements/actions/workflows/publish-release-candidate.yml)
3.  将释放分支的请求拉入 `main` 需要核准
    -   接下来 ["出书:最后发行"](https://github.com/eccenca/gui-elements/actions/workflows/publish-final-release.yml) 可用于 `main` (或 `next` 财务报告和审定财务报表 `legacy`) 发布最终发布包
    -   为在出版过程中所做的修改自动创建另一个 PR

## 许可证

Apache许可证,2.0版,2004年1月

## 常见问题

### @eccenca/gui-elements 是什么？

基于其他库的图形用户界面元素,可用于React应用程序,用Typescript写成\.

### 如何安装 @eccenca/gui-elements？

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

### @eccenca/gui-elements 支持 TypeScript 吗？

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

### @eccenca/gui-elements 支持 ESM 还是 CommonJS？

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

### @eccenca/gui-elements 需要什么版本的 Node\.js？

package\.json 的 engines 字段要求 Node\.js \>=18\.19\.0。版本不符时 npm 默认只给出警告，开启 engine-strict 后会拒绝安装。

### @eccenca/gui-elements 可以商用吗？

@eccenca/gui-elements 使用 Apache-2\.0 许可。宽松许可：允许商业使用、修改和再分发，并附带明确的专利授权；分发时需保留许可与 NOTICE 文件，修改过的文件要注明改动。以上为概括，不构成法律意见，请以许可原文为准。

### @eccenca/gui-elements 的下载量有多少？

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

### @eccenca/gui-elements 还在维护吗？

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