# @carbon/web-components 中文文档

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

版本：2\.67\.0
npm 元数据更新时间：2026-11-04T14:10:07.293Z
中文译文更新时间：2026-11-09T02:40:40.152Z
软件包许可：Apache-2\.0

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

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

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

- 包体积（解压后）：29.9 MB，6569 个文件
- 模块格式：ES Module
- TypeScript 类型：包内自带
- 运行依赖：11 个
- 首次发布：2022-12-06T16:17:57.867Z
- 最新版本发布：2026-11-04T14:10:06.750Z
- 近 30 天下载量：109393（2026-10-09 至 2026-11-07，npm 官方下载统计）
- 已发布版本数：1219（近 12 个月 58 个）

## 中文简介

碳设计系统的网络组件

## 安装

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

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

## README

# @ 碳/ 网络组件

碳设计系统的Web组件.

## 安装

```bash
npm install @carbon/web-components
```

## 使用量

这个 `@carbon/web-components` 包提供了碳设计组件 系统.

要使用一个组件,可以直接从包中导入:

```javascript
import '@carbon/web-components/es/components/dropdown/dropdown.js';
import '@carbon/web-components/es/components/dropdown/dropdown-item.js';
```

一旦导入组件模块,您就可以使用其中的组件 与本地 HTML 标记相同的方式 :

```html
<cds-dropdown trigger-content="Select an item">
  <cds-dropdown-item value="all">Option 1</cds-dropdown-item>
  <cds-dropdown-item value="cloudFoundry">Option 2</cds-dropdown-item>
  <cds-dropdown-item value="staging">Option 3</cds-dropdown-item>
  <cds-dropdown-item value="dea">Option 4</cds-dropdown-item>
  <cds-dropdown-item value="router">Option 5</cds-dropdown-item>
</cds-dropdown>
```

### 光盘N

CDN 文物也可以直接添加到页面中(开始) 版本时 `v1.16.0`:

```html
<!doctype html>
<html>
  <head>
    <script
      type="module"
      src="https://1.www.s81c.com/common/carbon/web-components/version/v2.65.0/dropdown.min.js"></script>
    <style type="text/css">
      <!-- hide custom element until it has been defined //-->
      cds-dropdown:not(:defined),
      cds-dropdown-item:not(:defined) {
        visibility: hidden;
      }
    </style>
  </head>
  <body>
    <div id="app">
      <cds-dropdown trigger-content="Select an item">
        <cds-dropdown-item value="all">Option 1</cds-dropdown-item>
        <cds-dropdown-item value="cloudFoundry">Option 2</cds-dropdown-item>
        <cds-dropdown-item value="staging">Option 3</cds-dropdown-item>
        <cds-dropdown-item value="dea">Option 4</cds-dropdown-item>
        <cds-dropdown-item value="router">Option 5</cds-dropdown-item>
      </cds-dropdown>
    </div>
  </body>
</html>
```

## 准备为 v3

下一个主要发行(v3)会改变组件的注册方式. 见 [v3 迁移指南](https://npmcn.com/package/docs/guides/cwc-v3-migration.md) 准备.

**现在可以了.** 选择加入的API—— `defineCustomElement` (单位:千美元)`es/globals/register.js`)和 `static is` 标签字段 – 在 v2 中可用 , 今天你可以写出v3准备的代码.

**折旧(将在v3中删除):**

-   **这个 `carbonElement` 装饰** (单位:千美元)`es/globals/decorators/carbon-element.js`, (中文(简体) ), 用于自定义元素的作者 – 迁移到 Lit 的 `customElement` (单位:千美元)`import { customElement } from 'lit/decorators.js'`) (中文(简体) ).
-   **这个 `es-custom` 构建** (单位:千美元)`cds-custom-*` 元素),被自定义标签所取代 名称、前缀构建和范围登记.
-   **这个 `custom-elements.json` WCA 列表**,替换为标准自定义 《要点宣言》.

**闯入 v3 :** 在 v3 中, 导入一个组件的类文件 登记其要素,例如导入 `button/button.js` 改为 `button/index.js`。使用 `v3` 标记 - 从 [`feat/web-components-v3`](https://github.com/carbon-design-system/carbon/tree/feat/web-components-v3) 树枝.

## 文档

组成部分文件和使用指南见:

-   [故事书](https://web-components.carbondesignsystem.com/)
-   [以形式使用组件](https://npmcn.com/package/%40carbon/web-components/docs/form.md)
-   [在组件中使用自定义样式](https://npmcn.com/package/%40carbon/web-components/docs/styling.md)
-   [移动到 v3](https://npmcn.com/package/docs/guides/cwc-v3-migration.md)

## 捐款

见 [贡献指南](https://npmcn.com/package/.github/CONTRIBUTING.md)。 。 。 .

## 许可证

凭 [Apache 2.0 许可证](https://npmcn.com/package/LICENSE)。 。 。 .

## ![IBM Telemetry](https://raw.githubusercontent.com/ibm-telemetry/telemetry-js/main/docs/images/ibm-telemetry-light.svg) IBM 遥测

本套件使用 IBM 遥测来收集去识别和匿名的度量衡 数据。 通过安装此包作为依赖, 您同意远程测量 藏书。 选择退出,看 [选择退出IBM遥测数据收集](https://github.com/ibm-telemetry/telemetry-js/tree/main#opting-out-of-ibm-telemetry-data-collection)。 。 。 . 有关所收集数据的更多信息,请参见: [IBM 遥测文档](https://github.com/ibm-telemetry/telemetry-js/tree/main#ibm-telemetry-collection-basics)。 。 。 .

## 常见问题

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

碳设计系统的网络组件

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

在项目目录运行 npm install @carbon/web-components，或使用 pnpm add / yarn add / bun add。它还提供命令行工具 create-prefixed-build，可以用 npx create-prefixed-build 直接运行。

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

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

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

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

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

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

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

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

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

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