# @cdx-ui/icons 中文文档

规范地址：https://npmcn.com/package/%40cdx-ui/icons/

版本：0\.3\.12
npm 元数据更新时间：2026-11-04T15:57:06.987Z
中文译文更新时间：2026-11-09T09:28:03.356Z
软件包许可：未声明

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

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

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

- 包体积（解压后）：24.1 MB，13440 个文件
- 模块格式：ESM + CJS
- TypeScript 类型：包内自带
- 运行依赖：0 个
- peer 依赖：react ^18\.2\.0 \|\| ^19\.0\.0，react-native \>=0\.76\.0，react-native-svg ^13\.0\.0 \|\| ^14\.0\.0 \|\| ^15\.0\.0
- 首次发布：2026-03-11T18:48:12.792Z
- 最新版本发布：2026-11-04T15:57:06.770Z
- 近 30 天下载量：3107（2026-10-10 至 2026-11-08，npm 官方下载统计）
- 已发布版本数：243（近 12 个月 243 个）

## 中文简介

![coverage](https://unpkg.com/@cdx-ui/icons/coverage.svg)

## 安装

```sh
npm install @cdx-ui/icons
```

也可以使用：`pnpm add @cdx-ui/icons`、`yarn add @cdx-ui/icons`、`bun add @cdx-ui/icons`

## README

# 翻译:

![coverage](https://unpkg.com/@cdx-ui/icons/coverage.svg)

Forge UI 的跨平台图标库, 以 [材料符号](https://fonts.google.com/icons) (外形,重量400,光学尺寸24). 通过 `react-native-svg` 并且目标iOS,Android,和Web 从一个代码库.

完整的材料符号概要集可供使用,每个图标都有概要和已填充的变体,同时支持自定义的SVG. 浏览 [图标浏览器](https://design.candescent.com/docs/foundations/expressions/icons)。 。 。 .

## 安装

```sh
pnpm add @cdx-ui/icons
```

### 同伴依赖关系

| 软件包 | 版本 |
| --- | --- |
| `react` | `^18.2.0 || ^19.0.0` |
| `react-native` | `>=0.76.0` (可选) |
| `react-native-svg` | `^13.0.0 || ^14.0.0 || ^15.0.0` |

## 使用量

```tsx
import { Home, Favorite, Settings } from '@cdx-ui/icons';

// Outlined (default)
<Home size={24} color="blue" />

// Filled variant
<Favorite size={24} color="red" filled />

// Toggle between variants
<Home filled={isActive} />
```

每个图标都是 `forwardRef` 接受所有标准的组件 `SvgProps` 加上下面的道具.

### 道具

| Prop | 类型 | 默认 | 说明 |
| --- | --- | --- | --- |
| `size` | `number | string` | `24` | 设置两者 `width` 财务报告和审定财务报表 `height`。 。 。 . |
| `color` | `string` | `'currentColor'` | 用于图标的填充颜色 . |
| `filled` | `boolean` | `false` | 当 `true`。如果不存在填充数据,则重新列出. |
| `accessibilityLabel` | `string` | —— 说 | 图标一旦提供,即成为信息(`accessible={true}`, (中文(简体) ), `accessibilityRole="image"`) (中文(简体) ). 省略时,图标默认为装饰. |
| `data-testid` | `string` | —— 说 | 转发到根 `<Svg>` 用于测试的元素. |

所有其他道具都分布在根上 `<Svg>` 元素,包括标准 React 本地无障碍道具.

### 工厂和类型

| 导出 | 说明 |
| --- | --- |
| `createForgeIcon` | 从 SVG 数据创建自定义 Forge 风格图标组件的工厂函数 |
| `ForgeIconProps` | 工厂创建的图标的道具界面 |
| `ForgeIcon` | Forge 图标组件的别名类型 |
| `IconNode` | 工厂消耗的SVG路径数据类型 |
| `IconData` | 概要 + 已填充路径数据对的类型 |

### 命名公约

每个图标都有三种导出模式:

| 图案 | 示例 | 使用大小写 |
| --- | --- | --- |
| 帕斯卡案件 | `Home` | 初级进口 |
| 后缀 | `HomeIcon` | 避免与自己的碰撞 `Home` 组件 |
| 前缀 | `CdxHome` | 混合多个图标库时的命名空间 |

```tsx
import { Home } from '@cdx-ui/icons';
import { HomeIcon } from '@cdx-ui/icons';
import { CdxHome } from '@cdx-ui/icons';
```

### 别名

图标可以在 `icon-metadata.json`. 异名允许您在替代名下引用相同的基本图标——用于遗留相容性,域名名名词,或与其他图标集使用的名称相匹配. 生成脚本与标准出品同时生产出别名再出品,因此别名在运行时为零成本.

每个条目 `icon-metadata.json` 将基准图标名称(将其 SVG 文件名匹配)映射到一系列别名。 异名可以是普通字符串或对象 `deprecated: true` (单位:千美元) `deprecationReason` 以标记应该移出的名称.

```jsonc
// icon-metadata.json
{
  "home": {
    "aliases": [
      "house",
      {
        "name": "old-home-icon",
        "deprecated": true,
        "deprecationReason": "Renamed to Home",
      },
    ],
  },
  "settings": {
    "aliases": ["gear", "preferences"],
  },
}
```

上面的配置产生以下行为:

-   `House`, (中文(简体) ), `HouseIcon`,以及 `CdxHouse` 所有决心 `Home` 图标
-   `Gear` 财务报告和审定财务报表 `Preferences` 决议 `Settings` 图标
-   `OldHomeIcon` 决定: `Home` 但显示 `@deprecated Renamed to Home` JSDoc在你的编辑中警告, 将消费者裸体到犬名

```tsx
import { House } from '@cdx-ui/icons'; // alias → Home
import { Gear } from '@cdx-ui/icons'; // alias → Settings
import { OldHomeIcon } from '@cdx-ui/icons'; // deprecated alias → Home (editor warning)
```

与现有图标名称相撞的异名在生成过程中被默默跳过,以避免重复导出 .

## 国家旗帜

国家旗帜从 `@cdx-ui/icons/flags` 子路径,不是主路径 `@cdx-ui/icons` 枪管 每个旗帜是 `ForgeIcon`。一个α-2代码将其字母保留在组件名中,例如 `FlagUS` 或者说 `FlagXK`。一个子分区代码在组件名称中用下划线取代连字符(`FlagGB_ENG` 页:1 `GB-ENG`) (中文(简体) ). 子路径还输出 a `flags` 以代码键入,包括连字符,以及 a `FlagCode` 工会. `FlagCode` 与 [国家 -- -- 旗子](https://www.npmjs.com/package/country-flag-icons) 3x2 设定此套件是用该套件构建的,包括包船用于 [手机号码-js](https://www.npmjs.com/package/libphonenumber-js)。 。 。 .

每个旗道都有明确的填充,所以艺术品保持了源色. 文本颜色类和主题符号不重彩.

[`CountryFlag`](https://design.candescent.com/docs/components/country-flag) 从 `@cdx-ui/components` 是产品UI的组件,包括选定国家的主要槽。 它解决艺术通过 `flags` 记录,所以渲染 `CountryFlag` 包住每一面旗帜。 一个显示一面固定旗帜的应用程序可以导入图标 :

```tsx
import { FlagUS, flags, type FlagCode } from '@cdx-ui/icons/flags';

<FlagUS />;

const Flag = flags.US;
```

## 无障碍

图标是 **默认装饰** 在无辅助技术时隐藏在辅助技术中 `accessibilityLabel` 提供。 这是文本标签旁边或标签容器内部图标的正确行为.

```tsx
// Decorative (default) — screen readers skip this
<Home size={20} color={theme.colors.icon} />

// Informative — screen readers announce "Home, image"
<Home size={20} accessibilityLabel="Home" />
```

| 假设 | 怎么办 |
| --- | --- |
| 文本标签旁边的图标 | 留作默认(装饰) |
| 标签内的图标 `Button` | 留作默认——按钮的标签覆盖 |
| 独立图标传递意义 | 添加 `accessibilityLabel` 在上下文中描述图标的目的 |
| 只有图标的按钮 | 标记 `Pressable` 包装,不是图标 |

跨平台行为 :

-   **iOS(声音over):** 宣布为“ { label}, 图像 ”
-   **Android (TalkBack) (英语:** 宣布为“ { label}, 图形 ”
-   **网络( 反应土著网络) :** 渲染器 `role="img"` + 键 `aria-label`

反应原生 0.76别名 `aria-label` 改为 `accessibilityLabel`,所以无论是道具工作.

详细情况见 [图标无障碍指导](https://design.candescent.com/docs/foundations/expressions/icons) 在文件网站.

## 自定义图标

将自定义 SVG 置入 `icons/custom/`。生成脚本从两者中读取 `icons/material/outlined/` 财务报告和审定财务报表 `icons/custom/`,因此自定义图标与材料符号图标得到相同的处理.

-   使用 `{name}.svg` 备选案文
-   可选添加 `{name}-fill.svg` 用于填充的变体
-   **在 `0 -960 960 960` 坐标空间.** `createForgeIcon` 部队 `viewBox="0 -960 960 960"` 在每一个图标上,生成器只保留根的孩子 元素——它丢弃每个SVG自己的 `viewBox`编号 :`width`编号 :`height`。标准 24px 导出 (路径坐标在 `0..24`)为 **没有** 相容性:它使一个微小的斑点在 视图框(有效隐形).
-   **可提取的元素必须是: `<svg>`。 。 。 .** 解析器是深一层,所以 `<path>` 窝在一 `<g>` 被删除。 平整任何团体(并将其转换成 路径 `d`) 承诺之前.

要将一个 24px 品牌/ Figma 输出转换为 960 格网, 请应用 afine 转换 `x' = 40·x`, (中文(简体) ), `y' = 40·y − 960` (统一尺度×40,再由−960将y翻译为路径数据-) 例如,与 [`svgpath`](https://www.npmjs.com/package/svgpath)数字 : `svgpath(d).scale(40).translate(0, -960).round(2).toString()`。见 `icons/custom/whats_app.svg` 用于正常参考。 注意图标在 `currentColor`; 任何来源 `fill` 被压在地上 `color` 道具 (英语).

### 品牌标志

品牌标志 (WhatsApp, Google, GitHub,.) 被命名 `Logo<Brand>` 在图片图标库中, 但已公布 **无** 前缀并带有品牌外壳——例如:Figma `LogoWhatsApp` → 导出 `WhatsApp`。将 SVG 命名为已去除前缀、 蛇 cased 文件名, 因此生成器 生成正确的导出 :

| 图像组件 | SVG 文件名 | 导出 |
| --- | --- | --- |
| `LogoWhatsApp` | `whats_app.svg` | `WhatsApp` |
| `LogoYouTube` | `you_tube.svg` | `YouTube` |
| `LogoGitHub` | `git_hub.svg` | `GitHub` |
| `LogoLinkedIn` | `linked_in.svg` | `LinkedIn` |

代码连接批次脚本( repo- root) `scripts/generate-icon-batch.ts`剥去 `Logo` 前缀 当 对照本地文件交叉引用 Figma 组件,因此映射自动解决. 真正开始的材料符号 `Logo` (例如:. `logo_dev`)首先按确切名称匹配 且不受影响.

## 发展

### 正在下载材料符号 SVGs

SVG通过自定义下载脚本直接取自Google Fonts CDN(`scripts/download-icons.ts`) (中文(简体) ). 脚本查询 Google 的元数据 API 活动图标列表,然后只下载 **概述** 样式( 重量 400, opsz 24 ) , 两种填充状态。 下载的 SVG 不检查为 git .

```sh
pnpm --filter @cdx-ui/icons download-icons
```

此下载每个图标的大纲和已填入的 SVG `icons/material/outlined/`。通过 `--clean` 从头重新下载,而不是跳过已有文件.

### 生成图标组件

生成脚本( E)`scripts/generate-icons.ts`)从两者读取 SVGs `icons/material/outlined/` 财务报告和审定财务报表 `icons/custom/`,用 `svgson`,然后将 TypeScript 文件写入 `src/icons/` 财务报告和审定财务报表 `src/aliases/`。 。 。 .

```sh
pnpm --filter @cdx-ui/icons generate
```

生成的文件包括:

-   `src/icons/{name}.ts` – 每个图标有一个文件,其中既有概述的也有填充的路径数据
-   `src/icons/index.ts` - 所有图标的桶导出
-   `src/aliases/aliases.ts` ——由元数据驱动的后遗症名图
-   `src/aliases/suffixed.ts` —— 说 `{Name}Icon` 导出每个图标和别名
-   `src/aliases/prefixed.ts` —— 说 `Cdx{Name}` 导出每个图标和别名

每个生成的图标文件都包含一个基数64编码 `@preview` JSDoc标签,所以在您编辑器中的图标导入上徘徊显示一个视觉预览.

### 生成下塔布图标

原生底标签需要图像资产,而不是反应组件. 第二代剧本( A)`scripts/generate-tab-icons.ts`光栅化 所申报的被管理子集 `tab-icons.config.json` 成为单色模板 PNGs (24/48/72 px −) `@1x`编号 :`@2x`编号 :`@3x`)使用 `@resvg/resvg-js`,并发布通过 `@cdx-ui/icons/tab-icons` 子路径导出 .

```sh
pnpm --filter @cdx-ui/icons generate:tab-icons
```

生成文件( gitignored, 如 `src/icons/`:

-   `src/tab-icons/assets/{name}[-fill][@2x|@3x].png` – 模板 PNG (黑色 + alpha; 标签栏在运行时将其涂入)
-   `src/tab-icons/generated/{name}.ts` ——网络描述符(仅包含SVG组件,不包含资产进口)
-   `src/tab-icons/generated/{name}.native.ts` ——以静态为主的本土描述词 `require()` 资产进口
-   `src/tab-icons/generated/registry.ts` —— 说 `TAB_ICON_NAMES` 扭伤, `TabIconName` 类型,以及 `TAB_ICON_COMPONENTS` 地图
-   `src/tab-icons/generated/index.ts` - 桶出口描述器+登记册

要在所编集中添加图标,请将其基名添加到 `tab-icons.config.json` 以及重建——未知名称使建设失败. 消费者化的用法记录在寄存器的图标指南中.

### 标签图标注册

生成脚本也发出 a **登记册模块** ,提供程序访问所设置的标签图标集。 登记册出口可从 `@cdx-ui/icons/tab-icons` 子路径 :

| 导出 | 类型 | 说明 |
| --- | --- | --- |
| `TAB_ICON_NAMES` | `readonly string[]` (连翘) | 从配置中排序了全部蛇 大小写图标名称的数组 |
| `TabIconName` | 联盟类型 | 弦字结合由 tu(如. `'home' | 'settings' | …`(中文(简体) ) |
| `TAB_ICON_COMPONENTS` | `Record<TabIconName, ForgeIcon>` | 将每个名称映射到它的 SVG 图标组件 |

```tsx
import { TAB_ICON_NAMES, TAB_ICON_COMPONENTS, type TabIconName } from '@cdx-ui/icons/tab-icons';

// Iterate available names
TAB_ICON_NAMES.forEach((name) => console.log(name));

// Look up a component by name
const Icon = TAB_ICON_COMPONENTS['home'];

// Type-safe name parameter
function getTabIcon(name: TabIconName) {
  return TAB_ICON_COMPONENTS[name];
}
```

### 大楼

```sh
pnpm --filter @cdx-ui/icons build
```

这个运行 `clean` - > (中文) `generate` - > (中文) `generate:tab-icons` - > (中文) `bob build`A级 `prebuild` 钩子运行 `download-icons` 首先,一个干净的取出会自动在生成前获取源 SVG 。 输出到 `lib/` 有三个目标:

-   `lib/commonjs/` - CJS模块
-   `lib/module/` ——无害环境管理模块
-   `lib/typescript/` ——每个文件 `.d.ts` 声明

软件包由 `react-native-builder-bob`,与所有其他工作空间软件包一致。 不同于其他工作空间软件包 `react-native` 字段指向 `lib/module/index.js` (预先建立的无害环境管理产出)而不是来源。 这意味着图标包 **必须建造** (单位:千美元)`pnpm build:packages` 或者说 `pnpm --filter @cdx-ui/icons build`在Metro解决之前 原始地图被排除在已出版的软件包之外(`!lib/**/*.map` 内 `files`)来减少安装大小.

### 软件包结构

```
icons/
├── icons/
│   ├── material/outlined/     # Downloaded SVGs (not checked in)
│   └── custom/                # Hand-authored custom SVGs
├── scripts/
│   ├── download-icons.ts      # Downloads outlined SVGs from Google Fonts CDN
│   ├── generate-icons.ts      # SVG → TypeScript generation script
│   ├── generate-tab-icons.ts  # SVG → template PNG + descriptor generation
│   ├── generate-manifest.ts   # Emits icon-manifest.json (the ./manifest export)
│   └── shared.ts              # Naming utilities shared by both generators
├── src/
│   ├── icons/                 # Generated icon components
│   ├── aliases/               # Generated alias re-exports
│   ├── tab-icons/             # Bottom-tab descriptors (entry + generated assets)
│   ├── createForgeIcon.ts       # Factory function
│   ├── defaultAttributes.ts   # SVG defaults (viewBox, fill)
│   ├── types.ts               # TypeScript types
│   └── index.ts               # Main entry point
├── types/png.d.ts             # Ambient *.png module declaration (kept out of src/)
├── icon-metadata.json         # Alias and deprecation metadata
├── tab-icons.config.json      # Curated bottom-tab icon subset
├── package.json
├── tsconfig.json
└── tsconfig.build.json
```

`src/icons/`, (中文(简体) ), `src/aliases/`, (中文(简体) ), `src/tab-icons/assets/`,以及 `src/tab-icons/generated/` 包含生成的文件(除 `.gitkeep` 卫所.

## 建筑

软件包遵循的是 [清晰的反应-内在](https://github.com/lucide-icons/lucide),为材料符号所改编. 关键差异 :

-   **基于填充的图标** — 材料符号图标使用 `fill` 完全(无) `stroke` 属性)。 这个 `color` 道具映射到 `fill`。 。 。 .
-   **960x960坐标系统** —— 说 `viewBox="0 -960 960 960"` 而不是卢西德的 `0 0 24 24`编辑 `size` 道具控件使尺寸化;视图Box处理内部坐标.
-   **大纲/填充变体** ——每个图标通过 `filled` 道具,建模材料符号"填充轴. 此选项将导出计数对单独的组件减半 .
-   **默认装饰** ——图标隐藏在辅助技术中,除非 `accessibilityLabel` 提供.
-   **OTA 兼容性** —— 说 `childDefaultAttributes` 明确设定 `fill` 围绕CodePush/expo-updates中的继承错误工作.

完整的研究和设计原理记录在寄存器的图标包研究尖锐.

## 常见问题

### 如何安装 @cdx-ui/icons？

在项目目录运行 npm install @cdx-ui/icons，或使用 pnpm add / yarn add / bun add。它还需要宿主项目提供 peer 依赖：react（^18\.2\.0 \|\| ^19\.0\.0）、react-native-svg（^13\.0\.0 \|\| ^14\.0\.0 \|\| ^15\.0\.0）。npm 7 及以上与 pnpm 8 及以上默认会自动安装必需的 peer 依赖，Yarn 需要手动安装。

### @cdx-ui/icons 支持 TypeScript 吗？

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

### @cdx-ui/icons 支持 ESM 还是 CommonJS？

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

### @cdx-ui/icons 可以商用吗？

@cdx-ui/icons 使用 未声明 许可。package\.json 没有声明许可证。没有许可证的代码默认保留全部权利，商用前请联系作者或查看仓库中的 LICENSE 文件。以上为概括，不构成法律意见，请以许可原文为准。

### @cdx-ui/icons 的下载量有多少？

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

### @cdx-ui/icons 还在维护吗？

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