@lucide/angular

WARNING

本文件适用于 @lucide/angular。

要了解我们的 Angular 传统包，请参阅 lucide-angular。

🌐 To learn about our legacy package for Angular, please refer to lucide-angular. :::

一个独立的、基于信号、无区域的 Angular Lucide 图标实现。

🌐 A standalone, signal-based, zoneless implementation of Lucide icons for Angular.

你可以完成的事:

• 将图标作为独立的 Angular 组件使用，并支持完整的依赖注入
• 通过现代 Angular 提供者全局配置图标
• 与 Angular 的响应式表单和数据绑定集成
• 构建支持树摇图标和懒加载的可扩展应用

先决条件

🌐 Prerequisites

此包需要 Angular 17 及以上版本，并使用独立组件、信号和无区域变更检测。

🌐 This package requires Angular 17+ and uses standalone components, signals, and zoneless change detection.

安装

🌐 Installation

pnpm

pnpm add @lucide/angular

yarn

yarn add @lucide/angular

npm

npm install @lucide/angular

bun

bun add @lucide/angular

如何使用

🌐 How to use

独立图标

🌐 Standalone icons

每个图标都可以作为可直接使用的独立组件导入：

🌐 Every icon can be imported as a ready-to-use standalone component:

<svg lucideFileText></svg>

import { Component } from '@angular/core';
import { LucideFileText } from '@lucide/angular';

@Component({
  selector: 'app-foobar',
  templateUrl: './foobar.html',
  imports: [LucideFileText],
})
export class Foobar { }

TIP

独立图标组件使用选择器 svg[lucide{PascalCaseIconName}]。

这确保了 DOM 的最小膨胀，并能够直接操作生成的 SVG 元素的所有属性。

🌐 This ensures minimal bloating of the DOM and the ability to directly manipulate all attributes of the resulting SVG element.

动态图标组件

🌐 Dynamic icon component

你也可以使用动态 LucideIcon 组件来动态渲染图标。

🌐 You may also use the dynamic LucideIcon component to dynamically render icons.

使用树摇优化的导入

🌐 With tree-shaken imports

你可以直接将导入的图标传递给组件：

🌐 You may pass imported icons directly to the component:

@for (item of items) {
  <a navbarItem [routerLink]="item.routerLink">
    <svg [lucideIcon]="item.icon"></svg>
    {{ item.title }}
  </a>
}

import { Component } from '@angular/core';
import { LucideIcon, LucideHouse, LucideUsersRound } from '@lucide/angular';
import { NavbarItem, NavbarItemModel } from './navbar-item';

@Component({
  selector: 'app-navbar',
  templateUrl: './navbar.html',
  imports: [LucideIcon, NavbarItem],
})
export class Navbar {
  readonly items: NavbarItemModel[] = [
    {
      title: 'Home',
      icon: LucideHouse,
      routerLink: [''],
    },
    {
      title: 'Users',
      icon: LucideUsersRound,
      routerLink: ['admin/users'],
    },
  ];
}

通过依赖注入提供的图标

🌐 With icons provided via dependency injection

或者，该组件也接受字符串输入。

🌐 Alternatively, the component also accepts string inputs.

要以这种方式使用图标，首先，你必须通过 provideLucideIcons 提供图标：

🌐 To use icons this way, first, you have to provide icons via provideLucideIcons:

app.config.ts

import { ApplicationConfig } from '@angular/core';
import { provideLucideIcons, LucideCircleCheck, LucideCircleX } from '@lucide/angular';

export const appConfig: ApplicationConfig = {
  providers: [
    // ...
    provideLucideIcons(
      LucideCircleCheck,
      LucideCircleX,
    ),
  ]
};

foobar.html

<svg lucideIcon="circle-check"></svg>

foobar.ts

import { Component } from '@angular/core';
import { LucideIcon } from '@lucide/angular';

@Component({
  selector: 'app-foobar',
  templateUrl: './template-url',
  imports: [LucideIcon],
})
export class Foobar { }

TIP

为了获得最佳的包大小，请在应用中提供最高适当级别的图标。

在根级别提供所有图标可能会增加你的初始包大小，而在功能模块级别提供它们则可以实现更好的代码拆分。

🌐 Providing all icons at the root level may increase your initial bundle size, while providing them at feature module level enables better code splitting.

WARNING

虽然你可以在依赖注入树的任何层级提供你的图标，但请注意Angular 的 DI 系统是分层的：LucideIcon 将只能访问树中离它最近提供的图标。

可访问标签

🌐 Accessible labels

你可以使用 title 输入属性在 SVG 上设置 可访问名称元素:

🌐 You can use the title input property to set the accessible name element on the SVG:

<svg lucideIcon="house" title="转到仪表板"></svg>

这将产生以下输出：

🌐 This will result in the following output:

<svg class="lucide lucide-house" ...>
  <title>Go to dashboard</title>
  
</svg>

属性

🌐 Props

你可以传递其他属性来调整图标外观。

🌐 You can pass additional props to adjust the icon appearance.

名称	类型	默认值
size	数字	24
color	字符串	currentColor
strokeWidth	数字	2
absoluteStrokeWidth	布尔值	false

<svg lucideHouse size="48" color="red" strokeWidth="1"></svg>

全局配置

🌐 Global configuration

你可以使用 provideLucideConfig 来配置如上所定义的默认属性值：

🌐 You can use provideLucideConfig to configure the default property values as defined above:

import { ApplicationConfig } from '@angular/core';
import { provideLucideConfig } from '@lucide/angular';

export const appConfig: ApplicationConfig = {
  providers: [
    // ...
    provideLucideConfig({
      strokeWidth: 1.5
    }),
  ]
};

通过 CSS 进行样式设置

🌐 Styling via CSS

图标也可以通过使用自定义 CSS 类进行样式设置：

🌐 Icons can also be styled by using custom CSS classes:

<svg lucideHousePlus class="my-icon"></svg>

svg.my-icon {
    width: 12px;
    height: 12px;
    stroke-width: 3;
}

使用 Lucide Lab 或自定义图标

🌐 With Lucide lab or custom icons

Lucide lab 是一个图标集合，它不属于 Lucide 主库。

虽然它们不是作为独立组件提供的，但仍然可以像官方图标一样传递给 LucideIcon 组件：

🌐 While they aren't provided as standalone components, they can be still be passed to the LucideIcon component the same way as official icons:

<svg [lucideIcon]="CoconutIcon"></svg>


<svg lucideIcon="coconut"></svg>

import { provideLucideIcons } from '@lucide/angular';
import { coconut } from '@lucide/lab';

@Component({
  templateUrl: './foobar.html',
  // For using by name via provider:
  providers: [provideLucideIcons({ coconut })],
  imports: [LucideIcon]
})
export class Foobar {
  // For passing directly as LucideIconData:
  readonly CoconutIcon = coconut;
}

故障排除

🌐 Troubleshooting

图标未显示

🌐 The icon is not being displayed

如果使用每个图标组件：

🌐 If using per-icon-components:

1. 如果使用按图标组件，请确保图标组件被导入
2. 检查图标名称是否完全匹配（区分大小写）

如果使用动态组件：

🌐 If using the dynamic component:

1. 如果使用字符串名称，请确保通过 provideLucideIcons() 提供图标
2. 确认图标是从 @lucide/angular 导入的，而不是从旧版包导入的

TypeScript 错误？

🌐 TypeScript errors?

确保你是从 @lucide/angular 导入，而不是从 lucide-angular 导入。

🌐 Make sure you're importing from @lucide/angular and not lucide-angular.

图标以错误的默认值呈现

🌐 Icons render with wrong defaults

确保 provideLucideConfig() 在正确的级别使用。

🌐 Ensure provideLucideConfig() is used at the right level.

迁移指南

🌐 Migration guide

从 lucide-angular 迁移？请阅读我们的全面迁移指南。

🌐 Migrating from lucide-angular? Read our comprehensive migration guide.