# @carbon/icon-helpers 中文文档

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

版本：10\.85\.0
npm 元数据更新时间：2026-11-04T14:06:49.546Z
中文译文更新时间：2026-11-09T02:37:28.505Z
软件包许可：Apache-2\.0

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

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

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

- 包体积（解压后）：32.2 kB，22 个文件
- 模块格式：ESM + CJS
- TypeScript 类型：包内自带
- 运行依赖：1 个
- 首次发布：2018-11-18T02:46:01.701Z
- 最新版本发布：2026-11-04T14:06:48.529Z
- 近 30 天下载量：1646049（2026-10-09 至 2026-11-07，npm 官方下载统计）
- 已发布版本数：252（近 12 个月 34 个）

## 中文简介

使用碳设计系统的数字和软件产品与图标一起使用的帮助者

## 安装

```sh
npm install @carbon/icon-helpers
```

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

## README

# @ 碳/ icon- 帮助器

> 帮助者与图标一起使用 碳设计系统

## 开始

要安装 `@carbon/icon-helpers` 在您的项目中,您需要运行 根据命令使用 [无](https://www.npmjs.com/)数字 :

```bash
npm install -S @carbon/icon-helpers
```

如果你喜欢 [雅伦](https://yarnpkg.com/en/),使用以下命令 相反:

```bash
yarn add @carbon/icon-helpers
```

## 使用量

`@carbon/icon-helpers` 为渲染提供两个助手 `<svg>` 节点 ,或帮助使正确的属性设置在 `<svg>` 节点. 其中包括:

| 名称 | 类型 | 说明 |
| --- | --- | --- |
| `getAttributes` | `(attributes: Object) => Object` | 获取属性为 `<svg>` 节点 |
| `formatAttributes` | `(attributes: Object) => String` | 将属性格式化为可以应用到 DOM 中节点的字符串 |
| `toString` | `(descriptor: Object) => String` | 将给定的图标描述符格式化为字符串。 用于模板 |
| `toSVG` | `(descriptor: Object) => DOMNode` | 将给定的图标描述符格式化为 DOM 节点 |

对于大多数方法, `attributes` 与名称相对应 值是,如果您为 `<svg>`。例如,如果我们 想要设置 `width` 财务报告和审定财务报表 `height` 我们将采取以下行动:

```js
const { getAttributes } = require('@carbon/icon-helpers');
const attributes = getAttributes({ width: 20, height: 20 });
```

要将图标视为可聚焦,您需要提供 无论是 `aria-label` 或者说 `aria-labelledby` 在给定中 `attributes` 此外,还有: 改为 `tabindex`。例如:

```js
const { getAttributes } = require('@carbon/icon-helpers');
const attributes = getAttributes({
  'aria-label': 'My icon label',
  tabindex: '0',
});
```

### 图标描述符

我们用来描述图标对象的术语是图标描述符 `@carbon/icons`。默认情况下,其形状如下:

```js
{
  elem: 'svg',
  attrs: {
    xmlns: 'http://www.w3.org/2000/svg',
    viewBox: '0 0 16 16',
    width: 16,
    height: 16,
  },
  content: [
    {
      elem: 'path',
      attrs: {
        d: '...',
      },
    },
  ],
  name: 'IconName',
  size: 16,
}
```

您可以直接从 `@carbon/icons` 并使用它们 并行 `toSVG` 或者说 `toString` 具体做法是:

```js
import { IconName } from '@carbon/icons';
import { toString, toSVG } from '@carbon/icon-helpers';

const iconString = toString(IconName);
const iconSVG = toSVG({
  ...IconName,
  attrs: {
    ...IconName.attrs,
    myCustomAttribute: 'myCustomAttributeValue',
  },
});
```

## 捐款

我们总是寻找贡献者 帮助我们修复错误, 建立新的特性, 或者帮助我们改进项目文件。 如果你有兴趣,肯定 看看我们 [贡献指南](https://npmcn.com/.github/CONTRIBUTING.md)!

## 许可证

凭 [Apache 2.0 许可证](https://npmcn.com/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/icon-helpers 是什么？

使用碳设计系统的数字和软件产品与图标一起使用的帮助者

### 如何安装 @carbon/icon-helpers？

在项目目录运行 npm install @carbon/icon-helpers，或使用 pnpm add / yarn add / bun add。

### @carbon/icon-helpers 支持 TypeScript 吗？

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

### @carbon/icon-helpers 支持 ESM 还是 CommonJS？

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

### @carbon/icon-helpers 可以商用吗？

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

### @carbon/icon-helpers 的下载量有多少？

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

### @carbon/icon-helpers 还在维护吗？

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