# @brightlocal/icons 中文文档

规范地址：https://npmcn.com/package/%40brightlocal/icons/

版本：2\.5\.0
npm 元数据更新时间：2026-11-03T10:46:34.663Z
中文译文更新时间：2026-11-08T15:38:35.387Z
软件包许可：MIT

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

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

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

- 包体积（解压后）：10.6 MB，4687 个文件
- 模块格式：ESM + CJS
- TypeScript 类型：包内自带
- 运行依赖：1 个
- peer 依赖：react ^17\.0\.0 \|\| ^18\.0\.0 \|\| ^19\.0\.0，react-dom ^17\.0\.0 \|\| ^18\.0\.0 \|\| ^19\.0\.0
- 首次发布：2025-11-17T09:21:49.209Z
- 最新版本发布：2026-11-03T10:46:34.453Z
- 近 30 天下载量：2433（2026-10-09 至 2026-11-07，npm 官方下载统计）
- 已发布版本数：14（近 12 个月 14 个）

## 中文简介

亮度本地设计系统图标 - Lucide 默认和自定义图标

## 安装

```sh
npm install @brightlocal/icons
```

也可以使用：`pnpm add @brightlocal/icons`、`yarn add @brightlocal/icons`、`bun add @brightlocal/icons`

## README

# @ brightlocal/ icons (英语)

亮度本地设计系统图标 - Lucide 默认和自定义图标

## 概览

这个软件包为亮度本地设计系统提供了一个统一的图标系统,结合了:

-   所有 5000+ Lucide 反应图标( 树能震动)
-   自定义亮度本地图标
-   动态图标加载数据库驱动 UI
-   完整类型脚本支持

## 安装

```bash
pnpm add @brightlocal/icons
```

## 使用量

### 1\. 直接进口(建议)

最适合摇树- 只导入您使用的图标 .

```tsx
import { Check, Heart, Star } from "@brightlocal/icons";

<Check className="w-4 h-4" />
<Heart size={20} color="red" fill="red" />
<Star size={16} strokeWidth={2} />
```

### 2\. 动态Icon组件

对于数据库驱动的图标渲染,并带有代码分割. 图标仅在使用时才能动态加载 .

```tsx
import { DynamicIcon } from "@brightlocal/icons";

// From database or CMS
const iconName = user.settings.preferredIcon; // "heart"
<DynamicIcon name={iconName} size={20} />

// Works with custom icons too
<DynamicIcon name="bright-local-logo" size={32} />

// With Suspense fallback (optional)
<React.Suspense fallback={<div className="w-6 h-6 animate-pulse bg-gray-200 rounded" />}>
  <DynamicIcon name={dbIconName} size={16} />
</React.Suspense>
```

### 3\. 自定义亮度本地图标

```tsx
import { BrightLocalLogo } from "@brightlocal/icons";

<BrightLocalLogo className="h-8 w-8 text-blue-600" />;
```

## 组件道具

### 动态Icon 组件

-   `name`:图标名称(kebab-case,例如"相机","chevron-down","Bright-local-logo")
-   `size`: 以像素表示的图标大小( 默认: 16)
-   `color`: 图标颜色(默认使用当前颜色)
-   `strokeWidth`: 弦宽( 默认: 1. 33)
-   所有其他 SVG 道具

### 旗帜和社交媒体图标

-   `size`: 以像素表示的图标大小( 默认: 16)
-   `className`: 用于造型的CSS课程
-   所有标准 SVG 道具

## 福利

-   **树能震动**: 只导入您使用的图标( 有直接导入)
-   **类型安全**: 自动完成的完整类型脚本支持
-   **弹性**: 用于不同用途的多导入模式
-   **懒惰装入**: 动态Icon将图标分割成单独的块
-   **一致**: 覆盖所有图标的统一 API
-   **优化**: 最小捆绑撞击

## 添加自定义图标

### 方法1:使用创建LusideIcon(建议)

与DynamicIcon兼容并遵循了Lucide的准则(16×16画布,2px中风).

```tsx
// src/custom-icons/my-icon.tsx
import { createLucideIcon } from "@brightlocal/icons";

export const MyIcon = createLucideIcon("MyIcon", [
  ["path", { d: "M12 2v20M2 12h20", key: "cross" }],
  ["circle", { cx: "12", cy: "12", r: "3", key: "center" }],
]);

export default MyIcon;
```

然后加入动态导入:

```ts
// src/icons/dynamic-icon-imports.ts
const customIconImports = {
  "my-icon": () =>
    import("../custom-icons/my-icon.js").then((m) => ({
      default: m.MyIcon,
    })),
};
```

### 方法2:普通SVG组件

对于不需要动态加载的图标.

```tsx
// src/custom-icons/my-icon.tsx
import * as React from "react";

export const MyIcon = (props: React.SVGProps<SVGSVGElement>) => (
  <svg viewBox="0 0 16 16" fill="none" {...props}>
    <path d="M12 2v20M2 12h20" stroke="currentColor" strokeWidth={2} />
  </svg>
);
```

## 实例

### 图标图片库

```tsx
import { Check, X, Plus, Minus, Heart, Star } from "@brightlocal/icons";

const icons = [Check, X, Plus, Minus, Heart, Star];

<div className="grid grid-cols-6 gap-4">
  {icons.map((Icon, i) => (
    <Icon key={i} size={16} />
  ))}
</div>;
```

### 数据库驱动图标

```tsx
import { DynamicIcon } from "@brightlocal/icons";

// Icons stored in database
const features = [
  { id: 1, name: "Fast", icon: "zap" },
  { id: 2, name: "Secure", icon: "shield" },
  { id: 3, name: "Scalable", icon: "trending-up" },
];

<div className="grid grid-cols-3 gap-4">
  {features.map((feature) => (
    <div key={feature.id}>
      <DynamicIcon name={feature.icon} size={32} />
      <h3>{feature.name}</h3>
    </div>
  ))}
</div>;
```

### 装入国

```tsx
import { Loader2 } from "@brightlocal/icons";

<button disabled>
  <Loader2 className="mr-2 animate-spin" size={16} />
  Loading...
</button>;
```

## 图标命名公约

使用时 `DynamicIcon`,图标名称遵循 kebab 大小写格式 :

-   路西德图标: 将 PascalCase 转换为 kebab- case
    -   `ChevronDown` → `"chevron-down"`
    -   `AlertCircle` → `"alert-circle"`
    -   `UserPlus` → `"user-plus"`
-   自定义图标: 一致使用 kebab 大小写
    -   `BrightLocalLogo` → `"bright-local-logo"`

## 业绩考量

### 直接导入对 DynamicIcon

**当 :**

-   图标在构建时已知
-   需要最大摇动树
-   你想要最小的可能捆绑

```tsx
import { Camera, Heart } from "@brightlocal/icons";
```

**当 :**

-   图标名称来自数据库/ API
-   大型图标集需要代码共享
-   建筑可配置的UI组件

```tsx
<DynamicIcon name={iconFromDatabase} />
```

### 套装大小影响

-   直接导入: ~1-2KB 每个图标( 树形)
-   DynamicIcon: ~4KB + 按要求装入图标

## 默认图标属性

所有路西德图标来自 `@brightlocal/icons` 包含设计系统默认值:

| 财产 | 默认 | 说明 |
| --- | --- | --- |
| `size` | 16个 | 像素中的图标尺寸 |
| `strokeWidth` | 1.33 国家 | 匹配图像设计规格 |
| `absoluteStrokeWidth` | 真实 | 无论图标大小, 都保持中风的一致性 |

### 按图标类型分列的默认大小

| 图标类型 | 默认大小 | 使用大小写 |
| --- | --- | --- |
| 路西德图标 | 16px 时 | 用户界面元素、按钮、输入 |
| 动态图像 | 16px 时 | 数据库驱动图标 |
| 旗帜图标 | 16px 时 | 国家/区域指标 |
| 社交媒体图标 | 16px 时 | 品牌标志,社会链接 |

```tsx
// Lucide icons default to 16px with 1.33 strokeWidth
<Check />

// Explicit size — stroke stays consistent (absoluteStrokeWidth: true)
<Check size={20} />
<Check size={12} />
```

## 类型脚本支持

完全类型脚本支持和类型推论 :

```tsx
import { DynamicIcon } from "@brightlocal/icons";
import type { DynamicIconProps } from "@brightlocal/icons";

// Props are fully typed
const props: DynamicIconProps = {
  name: "heart",
  size: 16,
  color: "#ff0000",
};
```

## 无障碍

图标应包括适当的无障碍属性:

```tsx
// Decorative icons (no semantic meaning)
<Check aria-hidden="true" />

// Meaningful icons (provide label)
<Heart aria-label="Like this post" role="img" />

// Interactive icons (use with button/link)
<button aria-label="Close dialog">
  <X size={20} />
</button>
```

## 解决问题

### 未显示图标

1.  检查图标名称是否正确( 对直接导入的大小写敏感)
2.  校验图标存在于 Lucide 库
3.  对于 DynamicIcon ,请确保图标在 `dynamic-icon-imports.ts`

### 类型脚本出错

确保您安装了最新的类型 :

```bash
pnpm add -D @types/react
```

### 套装大小太大

使用直接导入而不是导入所有 :

```tsx
// ❌ Don't do this
import * as Icons from "@brightlocal/icons";

// ✅ Do this
import { Camera, Heart, Star } from "@brightlocal/icons";
```

## 从其他图标图书馆迁移

### 从反应图标

```tsx
// Before (react-icons)
import { FaHeart } from "react-icons/fa";
<FaHeart size={16} />;

// After (brightlocal/icons)
import { Heart } from "@brightlocal/icons";
<Heart size={16} />;
```

### 从赫罗伊孔斯

```tsx
// Before (heroicons)
import { HeartIcon } from "@heroicons/react/16/outline";
<HeartIcon className="h-6 w-6" />;

// After (brightlocal/icons)
import { Heart } from "@brightlocal/icons";
<Heart className="h-6 w-6" />;
```

## 资源

-   [Lucide 图标画廊](https://lucide.dev/icons) - 浏览所有可用的 5000+ 图标
-   [路西德文档](https://lucide.dev/guide) - 更多地了解Lucide图标
-   [故事书文档](https://npmcn.com/apps/docs/src/stories/Lucide.mdx) - 交互式图标画廊
-   [软件包来源](https://github.com/BrightLocal/design-system/tree/main/packages/icons) - 查看源代码

## 捐款

要添加新自定义图标 :

1.  在其中创建图标文件 `src/custom-icons/`
2.  导出自 `src/index.ts`
3.  添加到动态导入 `src/icons/dynamic-icon-imports.ts`
4.  更新 `customIconsData` 在故事书文档中
5.  运行构建 : `pnpm build`

### 添加社交媒体图标

社交媒体的图标 `src/social-media/` 使用自动生成的枪管(`index.ts`) (中文(简体) ). 这个 `SourceLogo` 构成部分 `@brightlocal/ui-components` 自动解析图标名称 以公约方式执行的`name` → `<PascalName>Original` 编号 : `<PascalName>Neutral`),所以大多数新图标 工作时无需更改代码 `ui-components`。 。 。 .

**何时添加别名**: 如果消费者造型源密钥与图标文件干不匹配 (例如消费者通过) `"twitter"` 但图标文件是 `x-ex-twitter-original.tsx`,添加一个 条目为 `SOURCE_ICON_ALIASES` 内 `packages/ui-components/src/components/source-logo.tsx`。 。 。 .

## 许可证

明亮局部设计系统的一部分. 许可证详情见主仓库.

## 常见问题

### @brightlocal/icons 是什么？

亮度本地设计系统图标 - Lucide 默认和自定义图标

### 如何安装 @brightlocal/icons？

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

### @brightlocal/icons 支持 TypeScript 吗？

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

### @brightlocal/icons 支持 ESM 还是 CommonJS？

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

### @brightlocal/icons 可以商用吗？

@brightlocal/icons 使用 MIT 许可。宽松许可：允许商业使用、修改和再分发，通常只需在分发时保留原版权与许可声明。以上为概括，不构成法律意见，请以许可原文为准。

### @brightlocal/icons 的下载量有多少？

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

### @brightlocal/icons 还在维护吗？

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