# @cbpds/web-components 中文文档

规范地址：https://npmcn.com/package/%40cbpds/web-components/

版本：0\.9\.0-beta\.4
npm 元数据更新时间：2026-09-23T20:07:11.179Z
中文译文更新时间：2026-11-09T13:34:05.365Z
软件包许可：CC0-1\.0

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

原始 npm 页面：https://www.npmjs.com/package/%40cbpds/web-components
原文对照：https://npmcn.com/package/%40cbpds/web-components/?lang=original
项目主页：https://github.com/US-CBP/design-system/tree/develop/packages/web-components
源码仓库：https://github.com/US-CBP/design-system

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

- 包体积（解压后）：15.4 MB，1323 个文件
- 模块格式：ESM + CJS
- TypeScript 类型：包内自带
- 运行依赖：4 个
- 首次发布：2023-11-17T20:07:46.473Z
- 最新版本发布：2026-09-23T20:07:10.979Z
- 近 30 天下载量：2519（2026-10-09 至 2026-11-07，npm 官方下载统计）
- 已发布版本数：37（近 12 个月 11 个）

## 中文简介

CBP设计系统的Web组件.

## 安装

```sh
npm install @cbpds/web-components
```

也可以使用：`pnpm add @cbpds/web-components`、`yarn add @cbpds/web-components`、`bun add @cbpds/web-components`

## README

# 使用 CBP 设计系统Web组件

## 在您的应用程序中包含 Web 组件

将CBP设计系统网络组件纳入您的网站或应用程序有几种策略,详情如下:.

### 节点模块

CBP设计系统 [网络组件](https://www.npmjs.com/package/@cbpds/web-components) (和 [反应包装](https://www.npmjs.com/package/@cbpds/react-components))发布为npm.

在现代JavaScript框架中,你可以使用原生的网络组件,这些组件是框架-不可知的. 要将 CBP 设计系统网络组件添加到您的项目中,请做以下操作:

-   以依赖方式安装网络组件包 : `npm install @cbpds/web-components`
-   导入您框架中的 Web 组件加载器, 例如 `App.js|jsx|tsx` 或者说 `main.js|jsx|tsx`。 。 。 .
-   打电话 `defineCustomElements()` 初始化加载器并注册网络组件(在使用时会懒惰地加载).

```javascript
import { defineCustomElements } from '@cbpds/web-components/dist/loader';
defineCustomElements();
```

如果您正在使用代码库中的 Typescript, 您可能需要在成功编译您的代码之前让您的项目意识到网络组件 。 在很多情况下,只需在您之前添加网络组件定义就可以做到这一点 `tsconfig.json`包括(在 `npm install` 已运行)。 例如,

```json
"include": [
  "src",
  "node_modules/@cbpds/web-components/dist/types/components.d.ts"
]
```

如果使用带有React的TypeScript,这本身是不够的. 你还需要延长JSX。 内向元素来识别你的组件. 可以通过创建 `src/types/` 文件夹和其中的文件,例如, `custom-element-types.d.ts`数字 :

```TypeScript
import type { CustomElements, CustomCssProperties } from "@cbpds/web-components/dist/types/custom-element-jsx" 

declare module "react" {
  namespace JSX {
    interface IntrinsicElements extends CustomElements {}
  }
  export interface CSSProperties extends CustomCssProperties {}
}

```

### 脚本标签

对于不在一个节点.js环境中运行或需要构建步骤的网站,可以通过脚本标记包含网页组件:

-   在您索引.html或模板文件头加载器模块的脚本标记 .
    -   这个文件是一个加载器,它根据需要登记所有的设计系统组件和懒惰的单个组件.
    -   注:无害环境管理模块必须在SSL/https上提供.
    -   然后可以在模板,JSX,html等任何地方使用网络组件(海关元素).

您可以使用 UNPKG (一个反映 npm 的开源全球内容提供网络) 进行测试, 但是它不应该用于生产应用 .

参考最新版本:

```html
<script type="module" src="https://unpkg.com/@cbpds/web-components/dist/cbp-web-components/cbp-web-components.esm.js"></script>
```

参考特定版本:

```html
<script type="module" src="https://unpkg.com/@cbpds/web-components@0.0.1-develop.20/dist/cbp-web-components/cbp-web-components.esm.js"></script>
```

理想的情况是,您的申请应参考文件的中央、组织托管副本或提取软件包 `dist/cbp-web-components` 在您的应用程序的“ 资产” 目录中引用 :

```html
<script type="module" src="./assets/cbp-web-components/cbp-web-components.esm.js"></script>
```

## 使用 Web 组件

一旦CBP设计系统的网站组件被包含在您的网站或应用程序中,它们可能被用于HTML,JSX等. 这些web组件是像其他HTML元素一样被使用的自定义元素,其属性,方法和事件在其API文档中被定义.

建议: [`cbp-app` 网络组件](https://us-cbp.github.io/design-system/?path=/docs/components-app-specifications--docs) 用于包装您应用程序或站点模板的全部内容,以包括整个设计系统中用于设计组件的全局CSS变量(设计符号).

为了尽快开始,你可以抄取我们一个 ["当代"的故事](https://us-cbp.github.io/design-system/?path=/story/patterns-page-templates--internal) 来包装您的应用程序或网站内容.

## 字体和资产

无论您如何包含网络组件( 以上两种方法都不同), 您仍然需要一些属于 CBP 设计系统软件包但并未封装在 `cbp-app` 网络组件或任何其他组件 :

复制文件到 `node_modules/@cbpds/web-components/dist/assets/` 您的应用程序 `/assets` 目录。 (这可自动与 `vite-plugin-static-copy`(例如,第1行) 这个目录包括了Roboto字体文件,他们的CSS字体面部定义,以及CBP封印,这些字被多处使用,可以作为favicon来引用.

Roboto字体家族是CBP设计系统标准的一部分,但必须在应用程序中手动链接 `<head>` 还有.

复制并粘贴到您的索引.html或模板文件中 :

```html
<link rel="icon" type="image/svg+xml" href="assets/images/cbp-seal.svg">
<link rel="stylesheet" type="text/css" href="./assets/css/roboto.css">
<link rel="stylesheet" type="text/css" href="./assets/css/roboto_mono.css">
```

这些 CSS 文件假设一个目录结构:

-   网络根
    -   资产
        -   密码
        -   字体
            -   机器人
            -   机器人摩诺
        -   图像

任何偏离此结构的情况都可能需要编辑链接到的CSS文件和通向字体的路径.

如果您的应用程序资产文件夹的路径不同于 `./assets`,您可能需要提供路径作为属性 `cbp-universal-header` 作为您网站/应用程序模板的一部分.

## 常见问题

### @cbpds/web-components 是什么？

CBP设计系统的Web组件\.

### 如何安装 @cbpds/web-components？

在项目目录运行 npm install @cbpds/web-components，或使用 pnpm add / yarn add / bun add。

### @cbpds/web-components 支持 TypeScript 吗？

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

### @cbpds/web-components 支持 ESM 还是 CommonJS？

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

### @cbpds/web-components 可以商用吗？

@cbpds/web-components 使用 CC0-1\.0 许可。作者放弃著作权，可不受限制地使用。以上为概括，不构成法律意见，请以许可原文为准。

### @cbpds/web-components 的下载量有多少？

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

### @cbpds/web-components 还在维护吗？

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