# @carbon/ibmdotcom-web-components 中文文档 规范地址：https://npmcn.com/package/%40carbon/ibmdotcom-web-components/ 版本：2\.63\.1 npm 元数据更新时间：2026-11-05T20:07:37.326Z 中文译文更新时间：2026-11-09T05:19:56.787Z 软件包许可：Apache-2\.0 本文由上游 README 翻译，可能存在偏差，请结合原文核对 API、命令与配置。版权与许可归原作者所有。 原始 npm 页面：https://www.npmjs.com/package/%40carbon/ibmdotcom-web-components 原文对照：https://npmcn.com/package/%40carbon/ibmdotcom-web-components/?lang=original 项目主页：https://github.com/carbon-design-system/carbon-for-ibm-dotcom/tree/main#readme 源码仓库：https://github.com/carbon-design-system/carbon-for-ibm-dotcom#main ## 关键信息（来自 npm 元数据） - 包体积（解压后）：39.8 MB，1982 个文件 - 模块格式：CommonJS - TypeScript 类型：未声明 - 运行依赖：20 个 - 首次发布：2020-06-27T00:25:44.055Z - 最新版本发布：2026-11-05T20:07:37.127Z - 近 30 天下载量：7901（2026-10-09 至 2026-11-07，npm 官方下载统计） - 已发布版本数：4225（近 12 个月 44 个） ## 中文简介 IBM.com 的碳组件 ## 安装 ```sh npm install @carbon/ibmdotcom-web-components ``` 也可以使用：`pnpm add @carbon/ibmdotcom-web-components`、`yarn add @carbon/ibmdotcom-web-components`、`bun add @carbon/ibmdotcom-web-components` ## README A 类 `Carbon for IBM.com` 和本地 HTML 元素一样容易使用的变体, 没有框架税,没有框架仓. # `@carbon/ibmdotcom-web-components` `@carbon/ibmdotcom-web-components` 已存在 `Carbon for IBM.com` 与 自定义元素 v1和Shadow DOM v1 specs. ## 目录 - [开始](https://npmcn.com/package/%40carbon/ibmdotcom-web-components/#readme-getting-started) - [用法实例](https://npmcn.com/package/%40carbon/ibmdotcom-web-components/#readme-usage-examples) - [Webpack 应用程序设置](https://npmcn.com/package/%40carbon/ibmdotcom-web-components/#readme-webpack-application-setup) - [基本设置](https://npmcn.com/package/%40carbon/ibmdotcom-web-components/#readme-basic-setup) - [使用萨斯](https://npmcn.com/package/%40carbon/ibmdotcom-web-components/#readme-using-sass) - [Process.env 错误](https://npmcn.com/package/%40carbon/ibmdotcom-web-components/#readme-processenv-error) - [CDN 组件](https://npmcn.com/package/%40carbon/ibmdotcom-web-components/#readme-cdn-bundles) - [已版本套装](https://npmcn.com/package/%40carbon/ibmdotcom-web-components/#readme-versioned-bundles) - [使用其他设计系统(例如Northstar v18)](https://npmcn.com/package/%40carbon/ibmdotcom-web-components/#readme-using-with-other-design-systems-eg-northstar-v18) - [浏览器支持](https://npmcn.com/package/%40carbon/ibmdotcom-web-components/#readme-browser-support) - [可用组件清单](https://npmcn.com/package/%40carbon/ibmdotcom-web-components/#readme-list-of-available-components) - [网络组件中的稳定选择器(用于分析和集成/E2E测试)](https://npmcn.com/package/%40carbon/ibmdotcom-web-components/#readme-stable-selectors-for-analytics-and-integratione2e-testing-in-web-components) - [高级](https://npmcn.com/package/%40carbon/ibmdotcom-web-components/#readme-advanced) - [在组件中使用自定义样式](https://npmcn.com/package/%40carbon/ibmdotcom-web-components/#readme-using-custom-styles-in-components) - [创建不同样式的衍生组件](https://npmcn.com/package/%40carbon/ibmdotcom-web-components/#readme-creating-derived-components-with-different-style) - [使用 CSS 自定义属性](https://npmcn.com/package/%40carbon/ibmdotcom-web-components/#readme-using-css-custom-properties) - [CSS 阴影部件](https://npmcn.com/package/%40carbon/ibmdotcom-web-components/#readme-css-shadow-parts) - [IBM.com 站点所有者的先进用途](https://npmcn.com/package/%40carbon/ibmdotcom-web-components/#readme-advanced-usage-for-ibmcom-site-owners) - [为IBM.com网络组件贡献碳](https://npmcn.com/package/%40carbon/ibmdotcom-web-components/#readme-contributing-to-carbon-for-ibmcom-web-components) ## 开始 要安装 `@carbon/ibmdotcom-web-components` 在你的项目中,你需要 使用 [无](https://www.npmjs.com/)数字 : ```bash npm install -S @carbon/ibmdotcom-web-components ``` 如果你喜欢 [雅伦](https://yarnpkg.com/en/),使用以下命令 相反: ```bash yarn add @carbon/ibmdotcom-web-components ``` > 注:从IBM.com开始,Lit依赖性将由Carbon管理 `v1.13.0`。对于较早的版本,必须安装 Lit 依赖性 单独: > > 无 : > > ```bash > npm install -S lit-html lit-element > ``` > > 亚伦: > > ```bash > yarn add lit-html lit-element > ``` `@carbon/ibmdotcom-web-components` 用途 [`lit`](https://lit-html.polymer-project.org/) 上面的活性诱导 原始 Web 组件标准和 [`lit/decorators`](https://lit-element.polymer-project.org/) 用于反应 顶端的属性/属性 `lit`。 。 。 . ## 用法实例 ### Webpack 应用程序设置 #### 基本设置 对于生产用途,我们的建议是 **设置模块捆绑器** 改为 解决 ECMAScript `import`编号. 你可以从大多数模块捆绑器的最小配置开始. 对于 示例,与 [网络软件包](https://webpack.js.org/),你不需要一个 配置 . 一旦你建立了一个模块捆绑器, 你可以开始导入我们的组件模块, 例如: ```javascript import '@carbon/ibmdotcom-web-components/es/components/masthead/masthead-container'; ``` 一旦你这样做,你可以像使用HTML标记那样容易地使用我们的组件,例如: ```html ``` > 检查我们 [代码框](https://githubbox.com/carbon-design-system/carbon-for-ibm-dotcom/tree/main/packages/web-components/examples/codesandbox/usage/webpack-basic) 实例执行. [![Edit @carbon/ibmdotcom-web-components](https://codesandbox.io/static/img/play-codesandbox.svg)](https://githubbox.com/carbon-design-system/carbon-for-ibm-dotcom/tree/main/packages/web-components/examples/codesandbox/usage/webpack-basic) > \\\\\\ 高于代码Sandbox 示例 [`html-webpack-plugin`](https://webpack.js.org/plugins/html-webpack-plugin/) 允许 [WebPack 服务器](https://webpack.js.org/configuration/dev-server/) 服务 `.html` 文件,但您可以使用其他方式服务 `.html` 文档, 例如,使用 [快递](http://expressjs.com/) 服务器. #### 使用萨斯 虽然样式作为网络组件的一部分,但设置 Sass 工具链通常对内容的造型有用. 要使用 Sass,可以在模块捆绑器中添加 Sass 工具链. 一对夫妇 sass 工具链所需的关键设置如下: 1. [`autoprefixer`](https://github.com/postcss/autoprefixer)。这是 要求使用碳核心 Sass 代码. 2. `enable-css-custom-properties` Carbon Sass 特征旗帜. 这是一个 iBM.com样式对Carbon的要求,特别是使用 [表达式主题](https://github.com/carbon-design-system/carbon-for-ibm-dotcom/blob/main/packages/styles/README.md)。 。 。 . 3. `grid-column-16` Carbon Sass 特征旗帜. 这是碳的要求 iBM.com 样式,因为设计偏好碳16列网格 [`carbon-components` 库默认的12列网格](https://github.com/carbon-design-system/carbon/blob/v10.22.0/packages/components/src/globals/grid/_grid.scss#L17-L43)。 。 。 . 以下是WebPack的例子: ```javascript module: { rules: [ { test: /\.scss$/, sideEffects: true, use: [ 'style-loader', 'css-loader', { loader: 'postcss-loader', options: { postcssOptions: { // `autoprefixer` is a requirement for Carbon core Sass code plugins: [autoprefixer], }, }, }, { loader: 'sass-loader', options: { implementation: require('sass'), sassOptions: { includePaths: ['../node_modules', '../../../node_modules'], // `enable-css-custom-properties` and `grid-columns-16` feature flags // are requirements for Carbon for IBM.com styles data: ` $feature-flags: ( enable-css-custom-properties: true, grid-columns-16: true, ); `, }, }, }, ], }, ], }, ``` > 检查我们 [代码框](https://githubbox.com/carbon-design-system/carbon-for-ibm-dotcom/tree/main/packages/web-components/examples/codesandbox/usage/webpack-sass) 实例执行. [![Edit @carbon/ibmdotcom-web-components](https://codesandbox.io/static/img/play-codesandbox.svg)](https://githubbox.com/carbon-design-system/carbon-for-ibm-dotcom/tree/main/packages/web-components/examples/codesandbox/usage/webpack-sass) 为了防止在您的页面上出现一闪未命名内容(FOUC) 一定会 `display: none` 如果一个组件尚未定义。 举个例子 ```css c4d-button-group:not(:defined) { display: none; } ``` #### Process.env 错误 有提及 `process.env` 全球变量 网络组件包和依赖性。 如果构建工具链( 例如 WebPack) 用于替换 `process.env.*` 您的应用程序中没有使用, 您可以在 `polyfills.ts` 申请文件. ```javascript (window as any).process = { env: { DEBUG: undefined }, }; ``` ### CDN 组件 为了让应用程序运行而不需要前端捆绑,有 为每个组件预建的CDN捆绑. 以下是执行《公约》的实例 `dotcom-shell`数字 : ```html ... ``` #### Carbon CDN 样式助手( 可选) 有可选的CDN文物可以协助全球碳 样式代替包含在您的特定应用程序包中. 例如,下文在“碳重置”中添加了碳重置和必要的Plex字体 页面: ```html ... ``` [在此了解更多关于碳 CDN 样式的助手](https://github.com/carbon-design-system/carbon-for-ibm-dotcom/blob/main/packages/web-components/docs/carbon-cdn-style-helpers.md) > 参见 ["IBM.com的大楼"](https://www.ibm.com/standards/carbon/web-components/?path=/docs/overview-building-for-ibm-dotcom--page) 页面 `window.digitalData` 财务报告和审定财务报表 ``。 。 。 . > 检查我们 [代码框](https://githubbox.com/carbon-design-system/carbon-for-ibm-dotcom/tree/main/packages/web-components/examples/codesandbox/usage/dotcom-shell-cdn) 实例执行. [![Edit @carbon/ibmdotcom-web-components](https://codesandbox.io/static/img/play-codesandbox.svg)](https://githubbox.com/carbon-design-system/carbon-for-ibm-dotcom/tree/main/packages/web-components/examples/codesandbox/usage/dotcom-shell-cdn) #### 已版本套装 CDN软件包由国家预防机制标签提供 `latest` (全部释放), `next` (最晚发布候选),和特定版本. 导入的 URL 模式 将: ```html ``` 或者说 ```html ``` 标签发布将称为: ```html ``` 具体的释放将称为: ```html ``` > 注:最新/下个标签是移动版本。 虽然总是有好处 保留最新版本,建议选择一个特定的 版本,并在升级到更新版本时适当测试应用程序. ### 使用其他设计系统(例如Northstar v18) [阴影DOM](https://w3c.github.io/webcomponents/spec/shadow/),其中一个 carbon中用于IBM.com网络组件的标准,将网络组件隔离 样式来自应用程序样式。 也就是说这两种风格不会不利 互相影响. 对于目前运行在其他设计系统上的应用程序,例如 [遗产 北星 v18](https://www.ibm.com/standards/web/v18/),这种隔离 将协助从IBM.com Northstar v18风格逐渐迁移到 碳为IBM.com风格. 两种技术都能够安全共存 应用。 以下是IBM.com的"碳"的例子 IBM.com 北星页脚: ```html ...
...
``` > 如前所述,上面的例子需要设置模块捆绑器 节. > 检查我们 [代码框](https://githubbox.com/carbon-design-system/carbon-for-ibm-dotcom/tree/main/packages/web-components/examples/codesandbox/usage/v18) 实例执行. [![Edit @carbon/ibmdotcom-web-components](https://codesandbox.io/static/img/play-codesandbox.svg)](https://githubbox.com/carbon-design-system/carbon-for-ibm-dotcom/tree/main/packages/web-components/examples/codesandbox/usage/v18) ## 浏览器支持 依据 [ibm.com 浏览器支持](https://w3.ibm.com/w3publisher/ibm-web-standards-external/standards-mandatory/browser-standards)数字 : - 最新Chrome/Safari/FF ESR - IE和经典边缘 _没有_ 支持 ## 可用组件清单 查看可用的网络组件 : [https://www.ibm.com/标准/碳/web-组件/](https://www.ibm.com/standards/carbon/web-components/)。您可以看到用法 以几种方式提供信息: 1. 前往 Docs 标签,其中显示用途和可用的属性, 属性和自定义事件. 2. 点击 **诺比** 选项卡,在底部和正在更改的值。 多数 旋钮显示为类似 `Button kind (kind)`时 `kind` 这是 属性名称 3. 点击 **行动** 选项卡在下方,并与 选定组件。 你可能会看到类似的东西 `bx-modal-closed` 哪个 通常表示带有此类事件类型的事件被发射. ## 网络组件中的稳定选择器(用于分析和集成/E2E测试) 可见于 [这里](https://npmcn.com/package/%40carbon/ibmdotcom-web-components/docs/stable-selectors.md)。 。 。 . ## 高级 ### 在组件中使用自定义样式 作为 Shadow DOM( Web 组件规格之一) `@carbon/ibmdotcom-web-components` 承诺、风格 `@carbon/ibmdotcom-web-components` 定义不影响您的样式 应用程序,或反之亦然. 然而,如果您的应用程序或出自碳的样式指南想要 要改变我们组件的样式,有几个选项. #### 创建不同样式的衍生组件 您可以创建我们组件的衍生类并覆盖 [静态 `styles` 属性](https://lit-element.polymer-project.org/guide/styles#static-styles), (中文(简体) ), 例如: ```javascript import { css, customElement } from 'lit'; import C4DLinkWithIcon from '@carbon/ibmdotcom-web-components/es/components/link-with-icon/link-with-icon'; @customElement('my-link-with-icon') class MyLinkWithIcon extends C4DLinkWithIcon { // Custom CSS to enforce `g100` color of the link text static styles = css` ${C4DLinkWithIcon.styles} .bx--link-with-icon { color: #3d70b2; } `; } ``` #### 使用 CSS 自定义属性 对 CSS 自定义主题属性的修改以颜色反映 计划 `@carbon/ibmdotcom-web-components` 组件 : 例如,如果将 CSS 添加如下: ```css c4d-link-with-icon { --c4d-link-01: #3d70b2; /* `$link-01` token for `g100` theme */ } ``` 下方代码中链接的颜色修改为 `g100` 主题: ```html Link text ``` CSS 自定义属性的名称您可以使用 Carbon 主题符号 前缀为 `--cds-`。碳主题符号列表可见于 [这里](https://github.com/carbon-design-system/carbon/blob/v10.7.0/packages/themes/scss/generated/_themes.scss#L14-L454)。 。 。 . 使用 CSS 自定义属性方法,您可以在 特定要素: ```scss @use '@carbon/styles/scss/themes' as *; c4d-link-with-icon { // Emits all theme tokens in CSS Custom Properties @include theme(g100, true); } ``` #### CSS 阴影部件 一些构成部分支助 [CSS 阴影部件](https://www.w3.org/TR/css-shadow-parts-1/) 你也可以这样 使用您的应用程序的 CSS 来影响 `@carbon/ibmdotcom-web-components` 样式 以更灵活的方式. 例如,样式下方修改后按钮的文字颜色 `` 对其中之一 `g100` 主题: ```css cds-locale-modal::part(back-button) { color: #152935; } ``` > **ưμ㼯A** > 虽然阴影部件选择器是可供选择的,但用在自己 风险。 更改组件样式可能导致组件不作为 预期。 您负责确保您的组件保持功能 同时使用阴影部件选择器。 我们无法保证我们的更新 库组件样式不会与阴影部分修改相冲突. #### IBM.com 站点所有者的先进用途 还有其他一些关键高级使用模式适合IBM.com 网站所有者。 IBM.com网站所有者可以在 [这里](https://ibm.biz/Bdq5q2)。 。 。 . ## 为IBM.com网络组件贡献碳 可见于 [这里](https://npmcn.com/package/%40carbon/ibmdotcom-web-components/docs/contributing-to-web-components.md)。 。 。 . ## ![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/ibmdotcom-web-components 是什么？ IBM\.com 的碳组件 ### 如何安装 @carbon/ibmdotcom-web-components？ 在项目目录运行 npm install @carbon/ibmdotcom-web-components，或使用 pnpm add / yarn add / bun add。 ### @carbon/ibmdotcom-web-components 支持 TypeScript 吗？ 该包的 package\.json 没有声明类型入口。需要类型提示时，可以在 npm 上查找社区维护的 @types/carbon\_\_ibmdotcom-web-components 是否存在。 ### @carbon/ibmdotcom-web-components 支持 ESM 还是 CommonJS？ 以 CommonJS 形式发布，可以直接 require\(\)；在 ES Module 项目中也可以用 import 引入（Node\.js 会把 module\.exports 作为默认导出）。 ### @carbon/ibmdotcom-web-components 可以商用吗？ @carbon/ibmdotcom-web-components 使用 Apache-2\.0 许可。宽松许可：允许商业使用、修改和再分发，并附带明确的专利授权；分发时需保留许可与 NOTICE 文件，修改过的文件要注明改动。以上为概括，不构成法律意见，请以许可原文为准。 ### @carbon/ibmdotcom-web-components 的下载量有多少？ 根据 npm 官方下载统计，@carbon/ibmdotcom-web-components 在 2026/10/09 – 2026/11/07 这 30 天内被下载 7,901 次，日均约 263 次。下载量会把 CI 构建、镜像同步和作为其他包依赖的安装一并计入，适合横向比较热度，不能直接等同于使用人数。 ### @carbon/ibmdotcom-web-components 还在维护吗？ 最新版本 2\.63\.1 发布于 2026/11/06（3 天前）；至今共发布 4225 个版本，其中过去 12 个月发布了 44 个；首次发布于 2020/06/27。发布频率只是参考信号：功能稳定的工具可能很少需要更新，建议结合源码仓库的 issue 和提交记录判断。