# @ai-matrx/icons 中文文档
规范地址：https://npmcn.com/package/%40ai-matrx/icons/
版本：0\.3\.96
npm 元数据更新时间：2026-10-28T14:59:07.024Z
中文译文更新时间：2026-11-05T18:24:00.324Z
软件包许可：MIT
本文由上游 README 翻译，可能存在偏差，请结合原文核对 API、命令与配置。版权与许可归原作者所有。
原始 npm 页面：https://www.npmjs.com/package/%40ai-matrx/icons
原文对照：https://npmcn.com/package/%40ai-matrx/icons/?lang=original
项目主页：https://github.com/AI-Matrix-Engine/aidream/tree/main/apps/shared/icons#readme
源码仓库：https://github.com/AI-Matrix-Engine/aidream
## 关键信息（来自 npm 元数据）
- 包体积（解压后）：733 kB，30 个文件
- 模块格式：ESM + CJS
- TypeScript 类型：包内自带
- Node.js 要求：\>=20
- 运行依赖：2 个
- peer 依赖：react \>=18\.0\.0
- 首次发布：2026-08-29T06:28:34.922Z
- 最新版本发布：2026-10-28T14:59:05.727Z
- 近 30 天下载量：77169（2026-10-05 至 2026-11-03，npm 官方下载统计）
- 已发布版本数：110（近 12 个月 110 个）
## 中文简介
AI Matrx 图标解析器:将任意图标 NAME 变成已渲染的组件 – 由 ~140 热的 Lucide 图标来解析零纬度命中, Lucide 分类目录其余部分验证的动态导入,模块级缓存, kebab/ Pascal 案件名称规范
## 安装
```sh
npm install @ai-matrx/icons
```
也可以使用：`pnpm add @ai-matrx/icons`、`yarn add @ai-matrx/icons`、`bun add @ai-matrx/icons`
## README
# @ai-matrx/相册
翻转任意图标 **名称** 变成一个成品 一个解析器,四个来源,零 闪光一无:
- **由 ~140 个热Lucide 图标所绘制的静态图** - 击中会同步,不 动态输入延迟。 导出此映射( E)`staticLucideIconMap`)和可扩展 (单位:千美元)`extendStaticIcons`) (中文(简体) ).
- **完整的Lucide目录通过验证的动态 `import("lucide-react")`** ——解决 一次,在模块一级缓存,并检查导出是否为可转换 之前的组件.
- **被禁的品牌图标 `react-icons` 可选依赖性** ——安装人员 默认, 首次使用时懒惰导入 `react-icons` 不存在( 安装为 `--omit=optional`,或失败的可选安装) 倒置图标而不是失败 . `lucide-react` 它本身就是一种真正的依赖—— 软件包载有自己的目录; `react` 是唯一的对等点.
- **您自己的 SVG 资产通过 `svg:` 编号** - 可注入的登记册地图 `svg:icons/Home` → `/icons/Home.svg` 并制作一个 `![]()
`;您注册您的应用程序 启动时的资产路径.
当动态图标加载时,倒置图标(默认) `Zap`(a) 以下列方式取代: 布局从未跳出,也没有闪出空出.
```bash
npm install @ai-matrx/icons lucide-react
# optional, for the curated brand icons (FcGoogle, FaBrave, …):
npm install react-icons
```
端点 : `react >= 18`, (中文(简体) ), `lucide-react >= 0.400.0`,可选择 `react-icons >= 5`。 。 。 .
## 使用量
```tsx
import { IconResolver, DynamicIcon, getIconComponent, renderIcon } from "@ai-matrx/icons";
// The unified component — static, dynamic, custom, and svg: names all work:
// Color/size convenience wrapper (Tailwind color names or hex):
// Synchronous lookup (static map + already-cached icons only; always returns a component):
const Icon = getIconComponent("Settings");
// Direct element render:
{renderIcon("Check", { className: "h-4 w-4" })}
```
存在检查(从未推断存在来自 `getIconComponent`,它总是返回 a 组件 : `isIconRegisteredSync(name)` 为同步登记册, `await isRegisteredOrLucideIconName(name)` 包括Lucide目录.
用户类型/粘贴输入的规范化名称 : `collectLucideIconNameCandidates("alarm-clock")` → `["alarm-clock", "Alarm-clock", "AlarmClock"]`,以及 `extractLucideJsxIconName("")` → `"BugPlay"` - 对候选人进行验证 `isRegisteredOrLucideIconName`。 。 。 .
图标拾取器 : `getCuratedIconIdsForPicker()` 返回有限的、排序的每组 静态的Lucide名称, 装饰品牌代号, 并注册 `svg:` 编号.
## 注册您的应用程序的 SVG 资产
包裹船装有 **空** `svg:` 登记 - 登记您的公共资产路径 一旦启动( 任何在图标渲染前运行的模块) :
```ts
import { registerSvgIcons } from "@ai-matrx/icons";
registerSvgIcons({
"icons/Home": "/icons/Home.svg",
"icons/brands/microsoft": "/icons/brands/microsoft.svg",
"icons/copy": "/icons/copy.svg",
"icons/hamburger": "/icons/hamburger.svg",
"icons/loading-circle": "/icons/loading-circle.svg",
"icons/logo": "/icons/logo.svg",
"icons/play": "/icons/play.svg",
"icons/share": "/icons/share.svg",
"icons/three-dots": "/icons/three-dots.svg",
"matrx/matrx-icon": "/matrx/matrx-icon.svg",
"matrx/matrx-icon-blue": "/matrx/matrx-icon-blue.svg",
"matrx/matrx-icon-cyan": "/matrx/matrx-icon-cyan.svg",
"matrx/matrx-icon-green": "/matrx/matrx-icon-green.svg",
"matrx/matrx-icon-indigo": "/matrx/matrx-icon-indigo.svg",
"matrx/matrx-icon-orange": "/matrx/matrx-icon-orange.svg",
"matrx/matrx-icon-pink": "/matrx/matrx-icon-pink.svg",
"matrx/matrx-icon-purple": "/matrx/matrx-icon-purple.svg",
"matrx/matrx-icon-slate": "/matrx/matrx-icon-slate.svg",
"matrx/matrx-icon-teal": "/matrx/matrx-icon-teal.svg",
"matrx/matrx-icon-yellow": "/matrx/matrx-icon-yellow.svg",
"matrx/matrx-imagen-logo-text": "/matrx/matrx-imagen-logo-text.svg",
"matrx/safari-pinned-tab": "/matrx/safari-pinned-tab.svg",
"dark-turbulence-noise": "/dark-turbulence-noise.svg",
});
```
礛 `` 调制 `
`。调用合并,所以特性可以注册自己的 独立编号。 未登记 `svg:` id像任何未知的名字一样倒回.
## 保持自己热的图标同步
```ts
import { BrainCircuit } from "lucide-react";
import { extendStaticIcons } from "@ai-matrx/icons";
extendStaticIcons({ BrainCircuit }); // now a zero-latency static hit everywhere
```
## 设计
- 静态映射 + 经验证的动态导入 + 模块缓存 + 回放加载 结构 **实值** (a) 产品.
- `react-icons` 通过构造是可选的:它只能是懒惰地装入的,而且每个 路径在缺失时会降解为后退图标.
- 帮助者的类名( N)`getTextColorClass`, (中文(简体) ), `DynamicIcon` izing)为尾风形 字符串; 包船没有 CSS .
- 无害环境管理+共同JS条件,并附有相应的申报,证明来自包装的柏油球, `"use client"` 盖在每块地上.
麻省理工学院
## 常见问题
### @ai-matrx/icons 是什么？
AI Matrx 图标解析器:将任意图标 NAME 变成已渲染的组件 – 由 ~140 热的 Lucide 图标来解析零纬度命中, Lucide 分类目录其余部分验证的动态导入,模块级缓存, kebab/ Pascal 案件名称规范
### 如何安装 @ai-matrx/icons？
在项目目录运行 npm install @ai-matrx/icons，或使用 pnpm add / yarn add / bun add。它还需要宿主项目提供 peer 依赖：react（\>=18\.0\.0）。npm 7 及以上与 pnpm 8 及以上默认会自动安装必需的 peer 依赖，Yarn 需要手动安装。
### @ai-matrx/icons 支持 TypeScript 吗？
支持。包内自带 TypeScript 类型声明（package\.json 声明了 types 入口），安装后即可获得类型提示，无需再安装 @types 包。
### @ai-matrx/icons 支持 ESM 还是 CommonJS？
同时提供 ES Module 与 CommonJS 入口，import 和 require\(\) 都可以使用，打包工具会自动选择合适的版本。
### @ai-matrx/icons 需要什么版本的 Node\.js？
package\.json 的 engines 字段要求 Node\.js \>=20。版本不符时 npm 默认只给出警告，开启 engine-strict 后会拒绝安装。
### @ai-matrx/icons 可以商用吗？
@ai-matrx/icons 使用 MIT 许可。宽松许可：允许商业使用、修改和再分发，通常只需在分发时保留原版权与许可声明。以上为概括，不构成法律意见，请以许可原文为准。
### @ai-matrx/icons 的下载量有多少？
根据 npm 官方下载统计，@ai-matrx/icons 在 2026/10/05 – 2026/11/03 这 30 天内被下载 77,169 次，日均约 2,572 次。下载量会把 CI 构建、镜像同步和作为其他包依赖的安装一并计入，适合横向比较热度，不能直接等同于使用人数。
### @ai-matrx/icons 还在维护吗？
最新版本 0\.3\.96 发布于 2026/10/28（8 天前）；至今共发布 110 个版本，其中过去 12 个月发布了 110 个；首次发布于 2026/08/29。发布频率只是参考信号：功能稳定的工具可能很少需要更新，建议结合源码仓库的 issue 和提交记录判断。