# @globalpayments/vega 中文文档

规范地址：https://npmcn.com/package/%40globalpayments/vega/

版本：2\.110\.1
npm 元数据更新时间：2026-11-11T03:38:45.646Z
中文译文更新时间：2026-11-16T16:13:08.923Z
软件包许可：UNLICENSED

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

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

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

- 包体积（解压后）：39.8 MB，4576 个文件
- 模块格式：ESM + CJS
- TypeScript 类型：包内自带
- 运行依赖：2 个
- 首次发布：2026-05-20T17:00:54.932Z
- 最新版本发布：2026-11-11T03:38:45.400Z
- 近 30 天下载量：12246（2026-10-17 至 2026-11-15，npm 官方下载统计）
- 已发布版本数：126（近 12 个月 126 个）

## 中文简介

Vega - 全球支付系统的设计系统

## 安装

```sh
npm install @globalpayments/vega
```

也可以使用：`pnpm add @globalpayments/vega`、`yarn add @globalpayments/vega`、`bun add @globalpayments/vega`

## README

# 维加- stencil

## 目录

-   [概览](https://npmcn.com/package/%40globalpayments/vega/#readme-overview)
-   [先决条件](https://npmcn.com/package/%40globalpayments/vega/#readme-prerequisite)
    -   [代码插件](https://npmcn.com/package/%40globalpayments/vega/#readme-code-linter)
    -   [\[可选 配置新设计符牌](https://npmcn.com/package/%40globalpayments/vega/#readme--optional--consume-new-design-token)
-   [开始](https://npmcn.com/package/%40globalpayments/vega/#readme-getting-started)
-   [除错/ 开发](https://npmcn.com/package/%40globalpayments/vega/#readme-debug-development)
-   [测试](https://npmcn.com/package/%40globalpayments/vega/#readme-testing)
    -   [如果你想运行一个测试套房, 请运行](https://npmcn.com/package/%40globalpayments/vega/#readme-if-you-want-to-run-a-single-test-suite--please-run)
    -   [如果你想在一个测试套间内运行特定测试箱,请运行](https://npmcn.com/package/%40globalpayments/vega/#readme-if-you-want-to-run-the-specific-test-case-within-a-single-test-suite--please-run)
    -   [如果您想要运行的是与其他测试套件中的大小写重复的, 您可以使用以下命令指定特定套件中的测试大小写 :](https://npmcn.com/package/%40globalpayments/vega/#readme-if-you-would-like-to-run-is-duplicate-with-the-cases-in-other-test-suite--you-can-use-the-below-command-to-specify-the-test-case-in-a-specific-suite-)
        -   [如果您需要更新组件图像, pls 在 master.json 中删除相关对象, 然后在命令下运行并执行更改 :](https://npmcn.com/package/%40globalpayments/vega/#readme-if-you-need-to-update-component-images-pls-delete-the-related-object-in-masterjson-then-run-below-command-and-commit-the-changes-)
    -   [如果您想要禁用 Featureflag 来测试旧逻辑的大小写](https://npmcn.com/package/%40globalpayments/vega/#readme-if-you-want-to-disable-Featureflag-to-test-cases-with-old-logic)
-   [提高承诺](https://npmcn.com/package/%40globalpayments/vega/#readme-raising-a-commit)
-   [解决问题](https://npmcn.com/package/%40globalpayments/vega/#readme-troubleshooting)
    -   [1\. E2E 测试因未加载的 css而失败](https://npmcn.com/package/%40globalpayments/vega/#readme-1-e2e-testing-failure-due-to-the-css-not-loaded)

## 概览

此软件包主要用于创建自定义的网络组件 [stencil.js (英语)](https://stenciljs.com/docs/introduction)。 。 。 .

## 先决条件

### 代码插件

vega-stencil 正在使用 eslint( 配置 : `.eslintrc.js`)与更美(配置: `.prettierrc.js`) (中文(简体) ). 请在您的 IDE 中确保两个工具都设置妥当 .

### \[可选 配置新设计符牌

设计令牌最初存放于 [`../vega-design` 软件包](https://github.com/heartlandpayments/Vega/tree/main/vega-design) 它也负责生成其他客户端使用的相应 CSS/JS 文件,包括 `vega-stencil`。 。 。 .

因此,如果想要测试一些设计符号的更改并把它们整合到vega-stencil中,就需要重新运行 CSS/JS 文件的消耗命令 `vega-design` 改为 `vega-stencil`数字 :

```bash
> npm run consume-design-token
```

## 开始

安装节点依赖

```bash
> npm install
```

## 除错/ 开发

生成新的速率组件

```bash
> npm run generate <element_tag>
```

启动本地服务器以预览您的变更

```bash
> npm run start
# or 
> npm run debug # no cache
```

## 测试

目前,viga-stencil有两个测试环境:

1.  单位测试环境 :
    -   在这个洞中,我们将运行 vega 组件/ 非组件逻辑(例如. [`vega-badge.spec.tsx`](https://github.com/heartlandpayments/Vega/blob/main/vega-stencil/src/components/vega-badge/test/vega-badge.spec.tsx)) (中文(简体) ).
    -   在这个洞穴里,运行期间不会有任何实际的 HTML 元素,它们都会以 `MockHTMLElement`
2.  E2E测试管 :
    -   这个env是使用精确的浏览器运行时间(Chrimium)来运行测试,这意味着所有的UI/UX应该和真实的一样.
    -   我们在这个洞里进行的测试是:
        1.  Vega组件类的E2E测试(如. [`vega-badge.e2e.ts`](https://github.com/heartlandpayments/Vega/blob/main/vega-stencil/src/components/vega-badge/test/vega-badge.e2e.ts)(中文(简体) )
        2.  E2E测试,用于视觉回归检查(例如. [`vaga-date-picker.visual.e2e.ts`](https://github.com/heartlandpayments/Vega/blob/main/vega-stencil/src/components/vega-date-picker/test/vega-date-picker.visual.e2e.ts)(中文(简体) )
        3.  E2E 标准无障碍测试 `'wcag2a', 'wcag2aa','wcag21a', 'wcag21aa'` (例如:. [`vega-date-picker.ada.e2e.ts`](https://github.com/heartlandpayments/Vega/blob/main/vega-stencil/src/components/vega-date-picker/test/vega-date-picker.ada.e2e.ts)(中文(简体) )

要运行的命令 **<1> 和 <2>** 实值

```bash
> npm run test:base:coverage
# or
> npm run test:base:watch-all # this command will re-run when src files are changed
```

只运行视觉回归测试的命令是

```bash
> npm run test:visual 
```

### 如果你想运行一个测试套房, 请运行

```bash
> npm run test:single-suite <suite_file_name>
```

示例 `npm run test:single-suite vega-modal.spec`

### 如果你想在一个测试套间内运行特定测试箱,请运行

```bash
> npm run test:single-case <test_case_name_regex>
```

这只能用一个符合正则名称的测试。 示例 `npm run test:single-case "should render proper css of modal when open modal"`

### 如果您想要运行的是与其他测试套件中的大小写重复的, 您可以使用以下命令指定特定套件中的测试大小写 :

```bash
> npm run test:single-suite -- --testNamePattern <test_case_name_regex>
```

#### 如果您需要更新组件图像, pls 在 master.json 中删除相关对象, 然后在命令下运行并执行更改 :

1\. 联合国.**< 3> (中文(简体) )** 2.节点脚本/视频测试-截图-处理.js

#### 如果您想要看到本地和站点之间的相差, pls 将遵循以下步骤 :

1\. 安装活服务器扩展名 2. 用 Live Server 打开屏幕截图/compare.html 3. 右上方的所有截图 4. 点击左下方的空白区域,如果立面不显示,则使用manuel来比较

#### 如果您想要禁用 Featureflag 来测试旧逻辑的大小写 :

对于 e2e 测试以禁用特征旗 :

```
describe('vega-input', () => {
  let page: E2EPage;
  beforeEach(async () => {
      page = await newE2EPage();
      await page.evaluateOnNewDocument(() => {
          window['VegaDisabledFeatureKeys'] = ['VEGA_FORM.FORM_FIELD_CONTROLLER_VALIDATION'];
      });
  });
```

要禁用特性旗的光谱测试 :

```
describe('vega-input', () => {
  beforeAll(() => {
    FeatureFlag.disable('VEGA_FORM.FORM_FIELD_CONTROLLER_VALIDATION');
});
```

**说明**数字 :

1.  单位( spec) 测试与 e2e 测试在 stencil 中的主要差异 [此处可见](https://stenciljs.com/docs/testing-overview#unit-testing-vs-end-to-end-testing)

-   接到通知后,就进行单位测试 `stencil` 实值 **完全一样** 运行它与 `jest` 直接的CLI(特别是针对非组件测试套件),这是因为stencil通过使用自己的测试运行时组件来嘲弄大多数html元素,因此我们建议避免使用 `jest` 在Github输油管运行时可能会看到不同的测试结果.

2.  在Vega中,我们倾向于将测试案例放在spec/unit测试中,而不是e2e测试,除非他们无法在非浏览器env中进行测试(例如模拟用户模糊/聚焦事件,窗口大小调整),主要原因是stencil不支持运行测试覆盖在e2e测试案例之上,因此我们无法轻易地告诉e2e测试恰当覆盖了内部组件.
3.  假设您必须使用 e2e 测试来覆盖代码分支, 请使用 [istanbul/ ignoring- 编码覆盖](https://github.com/gotwarlost/istanbul/blob/master/ignoring-code-for-coverage.md) 财务报告和审定财务报表 **就e2e测试中如何涵盖这一分支的问题提出补充意见** 以跳过密码进行覆盖检查。 例如:
    -   内 `vega-stencil/src/components/vega-carousel/vega-carousel.tsx`
        
        ```ts
        // ...
        
        /**
        * The below method is e2e-test covered in
        * @see{module:vega-carousel-e2e-render}
        */
        /* istanbul ignore next */
        @Watch('perPage')
        onPerPagePropsChange(): void {
          this.resizeWindowHelper();
          this.applySpacingHelper();
        }
        
        // ...
        ```
        
    -   和 jsdoc 模块 `module:vega-carousel-e2e-render` 定义于 `vega-stencil/src/components/vega-carousel/test/vega-carousel.e2e.ts`
        
        ```ts
        describe('vega-carousel', () => {
          /** @module vega-carousel-e2e-render */
          it('renders', async () => {
            const page: E2EPage = await newE2EPage();
            await page.setContent('<vega-carousel></vega-carousel>');
            const element: E2EElement = await page.find('vega-carousel');
            expect(element).toHaveClass('hydrated');
          });
        });
        ```
        

## 提高承诺

运行时确保您通过必要的预承诺检查

```bash
> npm run pre-release
```

一旦以上命令成功,运行此命令来建造用于释放的文物

```bash
> npm run release 
```

## 解决问题

### 1\. E2E 测试因未加载的 css而失败

这是因为你工作空间里现在的平板建筑是分道扬镳的,你需要通过跑来重建文物 `yarn run release`。 。 。 .

## 常见问题

### @globalpayments/vega 是什么？

Vega - 全球支付系统的设计系统

### 如何安装 @globalpayments/vega？

在项目目录运行 npm install @globalpayments/vega，或使用 pnpm add / yarn add / bun add。

### @globalpayments/vega 支持 TypeScript 吗？

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

### @globalpayments/vega 支持 ESM 还是 CommonJS？

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

### @globalpayments/vega 可以商用吗？

@globalpayments/vega 使用 UNLICENSED 许可。作者声明为 UNLICENSED，即不授予公开使用许可（与公共领域的 Unlicense 不同）。使用前需获得作者授权。以上为概括，不构成法律意见，请以许可原文为准。

### @globalpayments/vega 的下载量有多少？

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

### @globalpayments/vega 还在维护吗？

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

