@lucide/icons

@lucide/icons 是一个辅助库，它以可树摇的格式导出 Lucide 图标数据，并提供动态导入图标的工具函数。

它有意不包含实际的渲染逻辑或组件——但你可以使用此软件包为我们尚未支持的框架构建第三方集成。

安装

pnpm

pnpm add @lucide/icons

yarn

yarn add @lucide/icons

npm

npm install @lucide/icons

bun

bun add @lucide/icons

图标数据格式

每个图标都由以下接口描述：

export type LucideIconData = {
  name: string;
  node: LucideIconNode[];
} & ({ size: number } | { width: number; height: number });

name	type	description
name	string	图标的名称。
node	LucideIconNode[]	作为 [tagName, attributes] 元组的 SVG 子节点。
size or width & height	number	图标的尺寸（size 是正方形图标的简写）。

如何使用

图标可以单独导入。只有你导入的图标才会被你的应用代码引用 —— 其余的将通过树摇被消除。

import { House } from '@lucide/icons';
// House 是图标数据（不是渲染后的组件）。

构建图标

@lucide/icons 提供了一些小型辅助函数，可将 Lucide 图标数据转换为不同的可渲染输出。 所有构建器都接受相同的 params 对象（LucideBuildParams）来自定义生成的 SVG。

构建参数

支持以下参数（名称反映当前实现）：

param	type	effect
color	string	设置 stroke（默认为 currentColor）。
size	number	同时设置 width 和 height（默认为 24）。
width	number	仅设置 width。
height	number	仅设置 height。
strokeWidth	number	设置 stroke-width（默认为 2）。
nonScalingStroke	boolean	将 vector-effect="non-scaling-stroke" 添加到子元素。
className	string	附加到生成的 class 属性。
attributes	Record<string, string>	添加或覆盖任何生成的 SVG 属性（包括 class、viewBox 等）。

INFO

构建器生成的 SVG 属性包括默认的 Lucide 设置（xmlns、viewBox、fill="none"、stroke="currentColor"、stroke-width="2"、stroke-linecap="round"、stroke-linejoin="round"），以及形式为 lucide lucide-{iconName} 的 class 字符串。

buildLucideIconNode

创建类似 svgson 格式的根 SVG 节点：

import { buildLucideIconNode } from '@lucide/icons/builders';
import { House } from '@lucide/icons';

const node = buildLucideIconNode(House, {
  size: 32,
  strokeWidth: 1.5,
  className: 'my-icon',
});

// -> ['svg', 属性，子节点]

如果你想将 Lucide 图标插入到自己的渲染器、模板系统或框架集成中，这很有用。

buildLucideSvg

创建 SVG 字符串：

import { buildLucideSvg } from '@lucide/icons/builders';
import { House } from '@lucide/icons';

const svg = buildLucideSvg(House, { size: 24, color: '#111' });

buildLucideIconElement

在提供的文档中创建实际的 DOM 元素（SVG）：

import { buildLucideIconElement } from '@lucide/icons/builders';
import { House } from '@lucide/icons';

const el = buildLucideIconElement(document, House, { size: 24 });
document.body.appendChild(el);

buildLucideDataUri

从 Lucide 图标对象创建 base64 编码的 SVG 数据 URI。

此辅助函数同时适用于浏览器和 Node.js：

• 在浏览器中使用 btoa（并正确处理 UTF-8）
• 在 Node.js 中回退到 Buffer

import { buildLucideDataUri } from '@lucide/icons/builders';
import { House } from '@lucide/icons';

const uri = buildLucideDataUri(House, { size: 24 });

返回的值可以直接用于以下场景：

• <img src="...">
• CSS background-image
• Canvas 绘图
• HTML 或 SVG 中的内联数据 URL

环境说明

SVG 在进行 base64 转换之前会编码为 UTF-8，以确保正确处理非 ASCII 字符。

无需运行时配置。该函数会自动选择适当的编码策略。

如果 btoa 和 Buffer 均不可用，则会抛出错误。

动态导入

当你只在运行时才知道图标名称时，动态导入很有用（例如，存储在数据库或 CMS 中的图标名称）。对于纯静态用例，首选直接导入以获得最佳的树摇效果。

TIP

在索引映射之前验证 iconName（并提供后备图标）以避免运行时错误。

动态导入

当图标名称仅在运行时已知时，动态导入很有用（例如，存储在 CMS 或数据库中的图标名称）。对于纯静态用法，首选直接导入以实现最大程度的树摇。

import { lucideDynamicIconImports } from '@lucide/icons/dynamic';

const name = 'house';
const icon = await lucideDynamicIconImports[name]?.();

if (!icon) {
  // 处理未知的图标名称（后备）
}