从 lucide-angular 迁移到 @lucide/angular

🌐 Migrating from lucide-angular ⇒ @lucide/angular

发生了什么变化

🌐 What changed

@lucide/angular 从基于模块 + 单组件的 API 转向更现代的 Angular 方法：

• 该库定义了基于现代信号的独立组件，不使用基于 zone.js 的变更检测。
• 图标作为独立导入使用（每个图标一个组件）。
• 动态图标注册是通过 provideLucideIcons() 完成的，而不是使用 NgModule。
• 静态图标使用每个图标的组件以实现更好的树摇优化。
• 动态图标仍然使用单个动态组件（svg[lucideIcon]）。
• 全局默认值通过 provideLucideConfig() 配置。
• 品牌图标已被移除，请参见下一部分。

---

步骤 1 – 更新依赖

🌐 Step 1 – Update dependencies

去掉'lucide-angular'，再加'@lucide/angular'，见：
[开始 # 安装]（/guide/angular/getting-started.md#installation）

🌐 Remove lucide-angular, and add @lucide/angular, see:
Getting Started # Installation

---

步骤 2 – 将 LucideAngularModule.pick(...) 替换为 provideLucideIcons(...)

🌐 Step 2 – Replace LucideAngularModule.pick(...) with provideLucideIcons(...)

注意事项：

• 像 AirVentIcon / AlarmClock 这样从 lucide-angular 导入的旧方式，应替换为新的按图标导出的 LucideAirVent 和 LucideAlarmClock。
• 如果你主要使用静态图标，可能根本不需要提供它们，请参阅第 3 步。

之前

🌐 Before

基于 NgModule

🌐 NgModule based

import { BrowserModule, NgModule } from '@angular/core';
import { LucideAngularModule, AirVent, AlarmClock } from 'lucide-angular';

@NgModule({
  imports: [
    BrowserModule,
    LucideAngularModule.pick({ AirVent, AlarmClock }),
  ],
})
export class AppModule {}

独立

🌐 Standalone

import { ApplicationConfig } from '@angular/core';
import { LucideAngularModule, AirVent, AlarmClock } from 'lucide-angular';

export const appConfig: ApplicationConfig = {
  providers: [
    // ...
    importProvidersFrom(LucideAngularModule.pick({ AirVent, AlarmClock })),
  ]
};

之后

🌐 After

import { ApplicationConfig } from '@angular/core';
import { provideLucideIcons, LucideAirVent, LucideAlarmClock } from '@lucide/angular';

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

---

步骤 3 – 替换 <lucide-angular> / <lucide-icon> / <i-lucide> / <span-lucide>

🌐 Step 3 – Replace <lucide-angular> / <lucide-icon> / <i-lucide> / <span-lucide>

旧版包通过单个组件渲染所有内容。所有这些选择器都必须迁移到 <svg> 使用方式。

🌐 The legacy package rendered everything through a single component. All of these selectors must be migrated to <svg> usage.

A. 按名称的静态图标

🌐 A. Static icons by name

如果图标在构建时已知，只需使用静态导入：

🌐 If the icon is known at build time, just use a static import:

之前

🌐 Before

<lucide-angular name="circle-check"></lucide-angular>

之后

🌐 After

<svg lucideCircleCheck></svg>

B. 带有图标数据绑定的静态图标

🌐 B. Static icons with icon data binding

之前

🌐 Before

import { CircleCheck } from 'lucide-angular';

<lucide-icon [img]="CircleCheck"></lucide-icon>

之后

🌐 After

import { LucideCircleCheck } from '@lucide/angular';

<svg lucideCircleCheck></svg>

...并从 @lucide/angular 导入 LucideCircleCheck。

---

C. 动态图标

🌐 C. Dynamic icons

如果图标在运行时变化，请使用动态组件：

🌐 If the icon varies at runtime, use the dynamic component:

之前

🌐 Before

<lucide-icon [name]="item.icon"></lucide-icon>

之后

🌐 After

<svg [lucideIcon]="item.icon"></svg>

---

步骤4 – 将 LucideIconConfig 替换为 provideLucideConfig()

🌐 Step 4 – Replace LucideIconConfig with provideLucideConfig()

之前

🌐 Before

import { inject } from '@angular/core';
import { LucideIconConfig } from 'lucide-angular';

inject(LucideIconConfig).size = 12;

之后

🌐 After

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

providers: [
  provideLucideConfig({ size: 12 }),
]

放在哪里

🌐 Where to place it

• 全应用：AppModule.providers 或 bootstrapApplication(...providers)
• 特性级：特性模块提供者
• 组件级别（独立）：组件 providers

---

故障排除

🌐 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.

已移除品牌图标

🌐 Removed Brand Icons

品牌图标在 v1 中已被移除。如果你正在使用以下任何图标，你将需要用自定义 SVG 或替代图标来替换它们：

🌐 Brand icons are removed in v1. If you are using any of the following icons, you will need to replace them with a custom SVG or an alternative icon:

• Chromium
• Codepen
• 代码沙箱
• Dribbble
• 脸书
• Figma
• Framer
• Github
• Gitlab
• Instagram
• LinkedIn
• Pocket
• RailSymbol（基于英国 Rail 图标）
• Slack

我们建议使用各个品牌提供的官方 SVG 图标，大多数可以在它们的网站或品牌指南中找到。或者，你也可以使用 Simple Icons 提供的图标，该网站提供大量品牌图标，并附有官方品牌指南和 SVG 图标的链接。

🌐 We recommend to use the official SVG icons provided by the respective brands, most of them can be found on their websites or in their brand guidelines. Alternatively, you can use the icons from Simple Icons, which provides a large collection of brand icons. Also with links to the official Brand Guidelines and SVG icons.

一个支持独立组件的 Simple Icons 的 Angular 包 也可用。

🌐 An Angular package for Simple Icons with standalone component support is also available.

---

摘要

🌐 TL;DR

• LucideAngularModule ⇒ 静态：已移除；动态：LucideIcon
• LucideAngularModule.pick(...) ⇒ provideLucideIcons(...)
• <lucide-angular name="foo-bar"> ⇒ <svg lucideFooBar>
• <lucide-icon [name]="expr"> ⇒ <svg [lucideIcon]="expr">
• <lucide-icon [img]="expr"> ⇒ <svg [lucideIcon]="expr">
• LucideIconConfig ⇒ provideLucideConfig(...)
• 将品牌图标的使用替换为 simple-icons。