构建选项

¥Build Options

开发者有两种使用 Ionic 组件的选择：独立或模块。本指南涵盖了这两种选择以及每种方法的优点和缺点。

¥Developers have two options for using Ionic components: Standalone or Modules. This guide covers both options as well as the benefits and downsides of each approach.

虽然独立方法较新并且使用了更现代的 Angular API，但 Ionic 将继续支持模块方法。本文档网站上的大多数 Angular 示例都使用模块方法。

¥While the Standalone approach is newer and makes use of more modern Angular APIs, the Modules approach will continue to be supported in Ionic. Most of the Angular examples on this documentation website use the Modules approach.

独立式

¥Standalone

信息

从 Ionic v7.5 开始，支持将 Ionic UI 组件作为 Angular 独立组件。

¥Ionic UI components as Angular standalone components is supported starting in Ionic v7.5.

概述

¥Overview

开发者可以将 Ionic 组件用作独立组件，以利用 treeshaking 和更新的 Angular 功能。此选项涉及将特定的 Ionic 组件导入到你想要使用它们的 Angular 组件中。即使开发者的 Angular 应用是基于 NgModule 的，开发者也可以使用 Ionic 独立组件。

¥Developers can use Ionic components as standalone components to take advantage of treeshaking and newer Angular features. This option involves importing specific Ionic components in the Angular components you want to use them in. Developers can use Ionic standalone components even if their Angular application is NgModule-based.

请参阅独立迁移指南，了解有关如何更新 Ionic 应用以使用 Ionic 独立组件的说明。

¥See the Standalone Migration Guide for instructions on how to update your Ionic app to make use of Ionic standalone components.

好处

¥Benefits

启用 treeshaking，因此最终的构建输出仅包含运行应用所需的代码，从而减少总体构建大小。

¥Enables treeshaking so the final build output only includes the code necessary to run your app which reduces overall build size.
避免使用 NgModules 来简化开发体验并使你的代码更易于理解。

¥Avoids the use of NgModules to streamline the development experience and make your code easier to understand.
允许开发者使用较新的 Angular 功能，例如 ESBuild。

¥Allows developers to also use newer Angular features such as ESBuild.

缺点

¥Drawbacks

Ionic 组件需要导入到使用它们的每个 Angular 组件中，这可能非常耗时。

¥Ionic components need to be imported into every Angular component they are used in which can be time consuming to set up.

与基于独立的应用一起使用

¥Usage with Standalone-based Applications

警告

所有 Ionic 导入都应从 @ionic/angular/standalone 子模块导入。这包括组件、指令、提供程序和类型等导入。从 @ionic/angular 导入可能会引入延迟加载的 Ionic 代码，这可能会干扰 treeshaking。

¥All Ionic imports should be imported from the @ionic/angular/standalone submodule. This includes imports such as components, directives, providers, and types. Importing from @ionic/angular may pull in lazy loaded Ionic code which can interfere with treeshaking.

引导和配置

¥Bootstrapping and Configuration

当 Angular 应用使用 provideIonicAngular 函数调用 bootstrapApplication 时，需要配置 Ionic Angular。开发者可以在此函数中将任何 IonicConfig 值作为对象传递。请注意，即使没有传递自定义配置，也需要调用 provideIonicAngular。

¥Ionic Angular needs to be configured when the Angular application calls bootstrapApplication using the provideIonicAngular function. Developers can pass any IonicConfig values as an object in this function. Note that provideIonicAngular needs to be called even if no custom config is passed.

main.ts

import { enableProdMode, importProvidersFrom } from '@angular/core';

import { bootstrapApplication } from '@angular/platform-browser';

import { RouteReuseStrategy, provideRouter } from '@angular/router';

import { provideIonicAngular, IonicRouteStrategy } from '@ionic/angular/standalone';

import { routes } from './app/app.routes';
import { AppComponent } from './app/app.component';
import { environment } from './environments/environment';

if (environment.production) {
  enableProdMode();
}

bootstrapApplication(AppComponent, {
  providers: [
    { provide: RouteReuseStrategy, useClass: IonicRouteStrategy },
    provideIonicAngular({ mode: 'ios' }),
    provideRouter(routes),
  ],
});

组件

¥Components

在下面的示例中，我们从 @ionic/angular/standalone 导入 IonContent 和 IonButton，并将它们传递给 imports 以在组件模板中使用。如果未导入这些组件并将其提供给 imports 数组，我们将收到编译器错误。

¥In the example below, we are importing IonContent and IonButton from @ionic/angular/standalone and passing them to imports for use in the component template. We would get a compiler error if these components were not imported and provided to the imports array.

home.page.ts


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




import { IonButton, IonContent } from '@ionic/angular/standalone';



@Component({
  selector: 'app-home',
  templateUrl: 'home.page.html',
  styleUrls: ['home.page.scss'],
  standalone: true,
  imports: [IonButton, IonContent],
})
export class HomePage {
  constructor() {}
}

图标

¥Icons

图标 SVG 数据需要在 Angular 组件中定义，以便可以正确加载。开发者可以使用 ionicons 中的 addIcons 函数将 SVG 数据映射到字符串名称。然后，开发者可以使用 IonIcon 上的 name 属性通过字符串名称引用图标。

¥The icon SVG data needs to be defined in the Angular component so it can be loaded correctly. Developers can use the addIcons function from ionicons to map the SVG data to a string name. Developers can then reference the icon by its string name using the name property on IonIcon.

我们建议在 Angular 组件 constructor 中调用 addIcons，这样只有在使用 Angular 组件时才会添加数据。

¥We recommend calling addIcons in the Angular component constructor so the data is only added if the Angular component is being used.

对于使用 Ionicons 7.2 或更高版本的开发者，仅传递 SVG 数据将导致自动生成字符串名称。

¥For developers using Ionicons 7.2 or newer, passing only the SVG data will cause the string name to be automatically generated.

home.page.ts


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




import { IonIcon } from '@ionic/angular/standalone';


import { addIcons } from 'ionicons';
import { logoIonic } from 'ionicons/icons';

@Component({
  selector: 'app-home',
  templateUrl: 'home.page.html',
  styleUrls: ['home.page.scss'],
  standalone: true,
  imports: [IonIcon],
})
export class HomePage {
  constructor() {
    /**

     * On Ionicons 7.2+ this icon

     * gets mapped to a "logo-ionic" key.

     * Alternatively, developers can do:

     * addIcons({ 'logo-ionic': logoIonic });
     */
    addIcons({ logoIonic });
  }
}

图标也可以注册在诸如 app.component.ts 之类的入口点中，以避免需要多次调用 addIcons。开发者应该意识到，初始应用块可能会增加，因为需要在应用启动时加载注册的图标。但是，如果你的应用使用少量图标，则其影响可能很小。

¥Icons can also be registered in entry points such as app.component.ts to avoid the need to call addIcons multiple times. Developers should be aware that the initial application chunk may increase because the registered icons will need to be loaded at application start. However, if your application uses a small number of icons the impact of this may be minimal.

app.component.ts


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


import { addIcons } from 'ionicons';
import { logoIonic } from 'ionicons/icons';

@Component({
  selector: 'app-root',
  templateUrl: 'app.component.html',
  styleUrls: ['app.component.scss'],
  standalone: true,
})
export class AppComponent {
  constructor() {
    /**

     * Any icons you want to use in your application

     * can be registered in app.component.ts and then

     * referenced by name anywhere in your application.
     */
    addIcons({ logoIonic });
  }
}

然后，可以在应用中的任何位置通过名称引用在应用入口点中注册的图标。

¥Icons registered in an application entry point can then be referenced by name anywhere in the application.

home.page.html
<!-- 
  logoIonic was registered in app.component.ts instead of home.page.ts,
  but it can still be used in home.page.html.
-->
<ion-icon name="logo-ionic"></ion-icon>

路由

¥Routing

希望在 Ionic 组件上使用 routerLink、routerAction 或 routerDirection 的开发者应导入 IonRouterLink 指令。希望在锚点 (<a>) 元素上使用这些路由功能的开发者应该导入 IonRouterLinkWithHref。

¥Developers who wish to use routerLink, routerAction, or routerDirection on Ionic components should import the IonRouterLink directive. Developers who wish to use these routing features on anchor (<a>) elements should import IonRouterLinkWithHref instead.

home.page.ts

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

import { RouterLink } from '@angular/router';

import { IonButton, IonRouterLink } from '@ionic/angular/standalone';

@Component({
  selector: 'app-home',
  templateUrl: 'home.page.html',
  styleUrls: ['home.page.scss'],
  standalone: true,
  imports: [
    IonButton,
    RouterLink, // required to get base routerLink behavior for @angular/router
    IonRouterLink, // use IonRouterLinkWithHref if you are using an <a> element instead
  ],
})
export class HomePage {}

home.page.html
<ion-button routerLink="/foo" routerDirection="root">Go to Foo Page</ion-button>

测试

¥Testing

Ionic Angular 的独立组件使用 ES 模块。因此，使用 Jest 的开发者应该确保 ES 模块被转换为 Jest 可以使用的格式。使用 Jest 的开发者应将以下内容添加到其 Jest 配置中：

¥Ionic Angular's standalone components use ES Modules. As a result, developers using Jest should ensure that ES Modules are transpiled to a format that Jest can use. Developers using Jest should add the following to their Jest config:

npm
pnpm


"transformIgnorePatterns": ["<rootDir>/node_modules/(?!(@ionic/angular|@ionic/core|ionicons|@stencil/core|@angular/*)/)"]


"transformIgnorePatterns": ["<rootDir>/node_modules/.pnpm/(?!(@ionic/angular|@ionic/core|ionicons|@stencil/core|@angular/*)@)"]

与基于 NgModule 的应用一起使用

¥Usage with NgModule-based Applications

警告

引导和配置

¥Bootstrapping and Configuration

Ionic Angular 需要使用 provideIonicAngular 函数在 app.module.ts 的 providers 数组中进行配置。开发者可以在此函数中将任何 IonicConfig 值作为对象传递。请注意，即使没有传递自定义配置，也需要调用 provideIonicAngular。

¥Ionic Angular needs to be configured in the providers array of app.module.ts using the provideIonicAngular function. Developers can pass any IonicConfig values as an object in this function. Note that provideIonicAngular needs to be called even if no custom config is passed.

app.module.ts

import { NgModule } from '@angular/core';

import { BrowserModule } from '@angular/platform-browser';

import { RouteReuseStrategy } from '@angular/router';

import { IonicRouteStrategy, provideIonicAngular } from '@ionic/angular/standalone';

import { AppComponent } from './app.component';
import { AppRoutingModule } from './app-routing.module';

@NgModule({
  declarations: [AppComponent],
  imports: [BrowserModule, AppRoutingModule],
  providers: [provideIonicAngular(), { provide: RouteReuseStrategy, useClass: IonicRouteStrategy }],
  bootstrap: [AppComponent],
})
export class AppModule {}

组件

¥Components

在下面的示例中，我们从 @ionic/angular/standalone 导入 IonContent 和 IonButton，并将它们传递到 Angular 组件的 NgModule 中的 imports 数组，以便在组件模板中使用。如果未导入这些组件并将其提供给 imports 数组，我们将收到编译器错误。

¥In the example below, we are importing IonContent and IonButton from @ionic/angular/standalone and passing them to imports array in the Angular component's NgModule for use in the component template. We would get a compiler error if these components were not imported and provided to the imports array.

home.module.ts

import { NgModule } from '@angular/core';

import { IonButton, IonContent } from '@ionic/angular/standalone';

import { HomePage } from './home.page';

import { HomePageRoutingModule } from './home-routing.module';

@NgModule({
  imports: [IonButton, IonContent, HomePageRoutingModule],
  declarations: [HomePage],
})
export class HomePageModule {}

图标

¥Icons

图标 SVG 数据需要在 Angular 组件中定义，以便可以正确加载。开发者可以使用 ionicons 中的 addIcons 函数将 SVG 数据映射到字符串名称。然后，开发者可以使用 IonIcon 上的 name 属性通过字符串名称引用图标。IonIcon 组件应该像其他 Ionic 组件一样添加到 app.module.ts 中。

我们建议在 Angular 组件 constructor 中调用 addIcons，这样只有在使用 Angular 组件时才会添加数据。

¥We recommend calling addIcons in the Angular component constructor so the data is only added if the Angular component is being used.

对于使用 Ionicons 7.2 或更高版本的开发者，仅传递 SVG 数据将导致自动生成字符串名称。

¥For developers using Ionicons 7.2 or newer, passing only the SVG data will cause the string name to be automatically generated.

home.page.ts


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


import { addIcons } from 'ionicons';
import { logoIonic } from 'ionicons/icons';

@Component({
  selector: 'app-home',
  templateUrl: 'home.page.html',
  styleUrls: ['home.page.scss'],
})
export class HomePage {
  constructor() {
    /**

     * On Ionicons 7.2+ this icon

     * gets mapped to a "logo-ionic" key.

     * Alternatively, developers can do:

     * addIcons({ 'logo-ionic': logoIonic });
     */
    addIcons({ logoIonic });
  }
}

app.component.ts


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


import { addIcons } from 'ionicons';
import { logoIonic } from 'ionicons/icons';

@Component({
  selector: 'app-root',
  templateUrl: 'app.component.html',
  styleUrls: ['app.component.scss'],
})
export class AppComponent {
  constructor() {
    /**

     * Any icons you want to use in your application

     * can be registered in app.component.ts and then

     * referenced by name anywhere in your application.
     */
    addIcons({ logoIonic });
  }
}

然后，可以在应用中的任何位置通过名称引用在应用入口点中注册的图标。

¥Icons registered in an application entry point can then be referenced by name anywhere in the application.

home.page.html
<!-- 
  logoIonic was registered in app.component.ts instead of home.page.ts,
  but it can still be used in home.page.html.
-->
<ion-icon name="logo-ionic"></ion-icon>

路由

¥Routing

home.module.ts

import { NgModule } from '@angular/core';

import { RouterLink } from '@angular/router';

import { IonButton, IonRouterLink } from '@ionic/angular/standalone';

import { HomePage } from './home.page';

import { HomePageRoutingModule } from './home-routing.module';

@NgModule({
  imports: [
    IonButton,
    RouterLink, // required to get base routerLink behavior for @angular/router
    IonRouterLink, // use IonRouterLinkWithHref if you are using an <a> element instead
    HomePageRoutingModule,
  ],
  declarations: [HomePage],
})
export class HomePageModule {}

home.page.html
<ion-button routerLink="/foo" routerDirection="root">Go to Foo Page</ion-button>

测试

¥Testing

npm
pnpm


"transformIgnorePatterns": ["<rootDir>/node_modules/(?!(@ionic/angular|@ionic/core|ionicons|@stencil/core|@angular/*)/)"]


"transformIgnorePatterns": ["<rootDir>/node_modules/.pnpm/(?!(@ionic/angular|@ionic/core|ionicons|@stencil/core|@angular/*)@)"]

模块

¥Modules

概述

¥Overview

开发者还可以使用模块方法，在 app.module.ts 中导入 IonicModule 并在 imports 数组中调用 IonicModule.forRoot()。这会注册一个 Ionic 版本，其中 Ionic 组件将在运行时延迟加载。

¥Developers can also use the Modules approach by importing IonicModule and calling IonicModule.forRoot() in the imports array in app.module.ts. This registers a version of Ionic where Ionic components will be lazily loaded at runtime.

好处

¥Benefits

由于组件是根据需要延迟加载的，因此开发者无需花费时间手动导入和注册每个 Ionic 组件。

¥Since components are lazily loaded as needed, developers do not need to spend time manually importing and registering each Ionic component.

缺点

¥Drawbacks

延迟加载 Ionic 组件意味着编译器在构建时不知道需要哪些组件。这意味着你的最终应用包可能比它需要的大得多。

¥Lazily loading Ionic components means that the compiler does not know which components are needed at build time. This means your final application bundle may be much larger than it needs to be.
开发者无法使用较新的 Angular 功能，例如 ESBuild。

¥Developers are unable to use newer Angular features such as ESBuild.

用法

¥Usage

在下面的示例中，我们使用 IonicModule 创建 Ionic 的延迟加载版本。然后我们可以引用任何 Ionic 组件，而无需显式导入它。

¥In the example below, we are using IonicModule to create a lazily loaded version of Ionic. We can then reference any Ionic component without needing to explicitly import it.

import { NgModule } from '@angular/core';

import { BrowserModule } from '@angular/platform-browser';

import { IonicModule } from '@ionic/angular';

import { AppComponent } from './app.component';

@NgModule({
  declarations: [AppComponent],
  imports: [BrowserModule, IonicModule.forRoot()],
  bootstrap: [AppComponent],
})
export class AppModule {}

从模块迁移到独立

¥Migrating from Modules to Standalone

提示

尝试我们的自动化实用程序以迁移到独立版！

¥Try our automated utility for migrating to standalone!

有关如何开始的说明，请参阅 https://github.com/ionic-team/ionic-angular-standalone-codemods。与迁移实用程序相关的所有问题都应在链接的存储库上归档。

¥See https://github.com/ionic-team/ionic-angular-standalone-codemods for instructions on how to get started. All issues related to the migration utility should be filed on the linked repo.

独立选项比模块选项更新，因此开发者可能希望在应用开发过程中进行切换。本指南详细介绍了迁移所需的步骤。

¥The Standalone option is newer than the Modules option, so developers may wish to switch during the development of their application. This guide details the steps needed to migrate.

迁移到 Ionic 独立组件必须同时完成，不能逐步完成。模块和独立方法使用两个不同的 Ionic 构建系统，不能同时使用。

¥Migrating to Ionic standalone components must be done all at the same time and cannot be done gradually. The Modules and Standalone approaches use two different build systems of Ionic that cannot be used at the same time.

我们鼓励开发者尝试自动迁移实用程序，但如果他们想手动迁移应用，也可以按照以下步骤操作。

¥Developers are encouraged to try the automated migration utility, though they can also follow the steps below if they would like to manually migrate their applications.

基于独立的应用

¥Standalone-based Applications

如果你的 Angular 应用已在使用独立架构，并且你也希望将 Ionic UI 组件用作独立组件，请按照以下步骤操作。

¥Follow these steps if your Angular application is already using the standalone architecture, and you want to use Ionic UI components as standalone components too.

运行 npm install @ionic/angular@latest 以确保你运行的是最新版本的 Ionic。Ionic v7.5 或更高版本支持 Ionic UI 独立组件。

¥Run npm install @ionic/angular@latest to ensure you are running the latest version of Ionic. Ionic UI Standalone Components is supported in Ionic v7.5 or newer.
运行 npm install ionicons@latest 以确保你运行的是最新版本的 Ionicons。Ionicons v7.2 带来了可用性改进，减少了将图标与独立组件一起使用所需的代码样板。

¥Run npm install ionicons@latest to ensure you are running the latest version of Ionicons. Ionicons v7.2 brings usability improvements that reduce the code boilerplate needed to use icons with standalone components.
删除 main.ts 中的 IonicModule 调用，转而使用从 @ionic/angular/standalone 导入的 provideIonicAngular。传递给 IonicModule.forRoot 的任何配置都可以作为对象传递给这个新函数。

¥Remove the IonicModule call in main.ts in favor of provideIonicAngular imported from @ionic/angular/standalone. Any config passed to IonicModule.forRoot can be passed as an object to this new function.

main.ts

import { enableProdMode, importProvidersFrom } from '@angular/core';

import { bootstrapApplication } from '@angular/platform-browser';

import { RouteReuseStrategy, provideRouter } from '@angular/router';

- import { IonicModule, IonicRouteStrategy } from '@ionic/angular';
+ import { provideIonicAngular, IonicRouteStrategy } from '@ionic/angular/standalone';

import { routes } from './app/app.routes';
import { AppComponent } from './app/app.component';
import { environment } from './environments/environment';

if (environment.production) {
  enableProdMode();
}

bootstrapApplication(AppComponent, {
  providers: [
    { provide: RouteReuseStrategy, useClass: IonicRouteStrategy },
    /**

     * The custom config serves as an example

     * of how to pass a config to provideIonicAngular.

     * You do not need to set "mode: 'ios'" to

     * use Ionic standalone components.
     */
-   importProvidersFrom(IonicModule.forRoot({ mode: 'ios' })),
+   provideIonicAngular({ mode: 'ios' }),
    provideRouter(routes),
  ],
});

删除在你的应用中其他地方找到的对 IonicModule 的任何引用。

¥Remove any references to IonicModule found elsewhere in your application.
将 @ionic/angular 中的任何现有导入更新为从 @ionic/angular/standalone 导入。

¥Update any existing imports from @ionic/angular to import from @ionic/angular/standalone instead.

- import { Platform } from '@ionic/angular';
+ import { Platform } from '@ionic/angular/standalone';

在使用它们的 Angular 组件中为每个 Ionic 组件添加导入。请务必将导入传递到 Angular 组件上的 imports 数组。

¥Add imports for each Ionic component in the Angular component where they are used. Be sure to pass the imports to the imports array on your Angular component.

app.component.ts


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


+ import { IonApp, IonRouterOutlet } from '@ionic/angular/standalone';

@Component({
  selector: 'app-root',
  templateUrl: 'app.component.html',
  styleUrls: ['app.component.scss'],
  standalone: true,
+ imports: [IonApp, IonRouterOutlet],
})
export class AppComponent {
  constructor() {}
}

如果你使用 Ionicons，请使用 addIcons 定义每个 Angular 组件中使用的图标 SVG 数据。这允许你继续在组件模板中按字符串名称引用图标。请注意，你需要对添加的任何其他图标执行此操作。

¥If you are using Ionicons, define the icon SVG data used in each Angular component using addIcons. This allows you to continue referencing icons by string name in your component template. Note that you will need to do this for any additional icons added.

test.component.ts


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


+ import { IonIcon } from '@ionic/angular/standalone';
+ import { addIcons } from 'ionicons';
+ import { alarm, logoIonic } from 'ionicons/icons';

@Component({
  selector: 'app-root',
  templateUrl: 'app.component.html',
  styleUrls: ['app.component.scss'],
  standalone: true,
+ imports: [IonIcon],
})
export class TestComponent {
  constructor() {
+   addIcons({ alarm, logoIonic });
  }
}

从 angular.json 文件中删除以下代码（如果存在）。请注意，它可能会出现多次。

¥Remove the following code from your angular.json file if present. Note that it may appear multiple times.

angular.json
- {
-   "glob": "**/*.svg",
-   "input": "node_modules/ionicons/dist/ionicons/svg",
-   "output": "./svg"
- }

如果你使用 routerLink、routerDirection 或 routerAction，请务必导入 Ionic 组件的 IonRouterLink 指令或 <a> 元素的 IonRouterLinkWithHref 指令。

¥If you are using routerLink, routerDirection, or routerAction be sure to import the IonRouterLink directive for Ionic components or IonRouterLinkWithHref directive for <a> elements.

test.component.ts


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


- import { IonButton } from '@ionic/angular/standalone';
+ import { IonButton, IonRouterLink } from '@ionic/angular/standalone';

@Component({
  selector: 'app-root',
  templateUrl: 'app.component.html',
  styleUrls: ['app.component.scss'],
  standalone: true,
  imports: [
    IonButton,
+   IonRouterLink
  ],
})
export class TestComponent {}

如果你使用 VSCode，建议忽略导入建议的 @ionic/angular/common 和 @ionic/angular 模块说明符。

¥If you are using VSCode it is recommended to ignore the @ionic/angular/common and @ionic/angular module specifiers for import recommendations.

.vscode/settings.json
{
  "typescript.preferences.autoImportFileExcludePatterns": ["@ionic/angular/common", "@ionic/angular"]
}

基于 NgModule 的应用

¥NgModule-based Applications

如果你的 Angular 应用仍在使用 NgModule 架构，但你现在希望采用 Ionic UI 组件作为独立组件，请按照以下步骤操作。

¥Follow these steps if your Angular application is still using the NgModule architecture, but you want to adopt Ionic UI components as standalone components now.

运行 npm install @ionic/angular@latest 以确保你运行的是最新版本的 Ionic。Ionic v7.5 或更高版本支持 Ionic UI 独立组件。

¥Run npm install @ionic/angular@latest to ensure you are running the latest version of Ionic. Ionic UI Standalone Components is supported in Ionic v7.5 or newer.
运行 npm install ionicons@latest 以确保你运行的是最新版本的 Ionicons。Ionicons v7.2 带来了可用性改进，减少了将图标与独立组件一起使用所需的代码样板。

¥Run npm install ionicons@latest to ensure you are running the latest version of Ionicons. Ionicons v7.2 brings usability improvements that reduce the code boilerplate needed to use icons with standalone components.
删除 app.module.ts 中的 IonicModule 调用，转而使用从 @ionic/angular/standalone 导入的 provideIonicAngular。传递给 IonicModule.forRoot 的任何配置都可以作为对象传递给这个新函数。

¥Remove the IonicModule call in app.module.ts in favor of provideIonicAngular imported from @ionic/angular/standalone. Any config passed to IonicModule.forRoot can be passed as an object to this new function.

app.module.ts


import { enableProdMode, importProvidersFrom } from '@angular/core';




import { bootstrapApplication } from '@angular/platform-browser';




import { RouteReuseStrategy, provideRouter } from '@angular/router';


- import { IonicModule, IonicRouteStrategy } from '@ionic/angular';
+ import { provideIonicAngular, IonicRouteStrategy } from '@ionic/angular/standalone';

import { routes } from './app/app.routes';
import { AppComponent } from './app/app.component';
import { environment } from './environments/environment';

if (environment.production) {
  enableProdMode();
}

@NgModule({
  declarations: [AppComponent],
- imports: [BrowserModule, IonicModule.forRoot({ mode: 'ios' }), AppRoutingModule],
+ imports: [BrowserModule, AppRoutingModule],
  providers: [
    { provide: RouteReuseStrategy, useClass: IonicRouteStrategy },
    /**

     * The custom config serves as an example

     * of how to pass a config to provideIonicAngular.

     * You do not need to set "mode: 'ios'" to

     * use Ionic standalone components.
     */
+   provideIonicAngular({ mode: 'ios' }),
  ],
  bootstrap: [AppComponent],
})
export class AppModule {}

删除在你的应用中其他地方找到的对 IonicModule 的任何引用。

¥Remove any references to IonicModule found elsewhere in your application.
将 @ionic/angular 中的任何现有导入更新为从 @ionic/angular/standalone 导入。

¥Update any existing imports from @ionic/angular to import from @ionic/angular/standalone instead.

- import { Platform } from '@ionic/angular';
+ import { Platform } from '@ionic/angular/standalone';

为使用它们的 Angular 组件的 NgModule 中的每个 Ionic 组件添加导入。确保将组件传递到模块上的 imports 数组。

¥Add imports for each Ionic component in the NgModule for the Angular component where they are used. Be sure to pass the components to the imports array on the module.

app.module.ts


import { enableProdMode, importProvidersFrom } from '@angular/core';




import { bootstrapApplication } from '@angular/platform-browser';




import { RouteReuseStrategy, provideRouter } from '@angular/router';


- import { provideIonicAngular, IonicRouteStrategy } from '@ionic/angular/standalone';
+ import { provideIonicAngular, IonicRouteStrategy, IonApp, IonRouterOutlet } from '@ionic/angular/standalone';

import { routes } from './app/app.routes';
import { AppComponent } from './app/app.component';
import { environment } from './environments/environment';

if (environment.production) {
  enableProdMode();
}

@NgModule({
  declarations: [AppComponent],
- imports: [BrowserModule, AppRoutingModule],
+ imports: [BrowserModule, AppRoutingModule, IonApp, IonRouterOutlet],
  providers: [
    { provide: RouteReuseStrategy, useClass: IonicRouteStrategy },
    provideIonicAngular({ mode: 'ios' })
  ],
  bootstrap: [AppComponent],
})
export class AppModule {}

例如，所有使用 Ionic 组件的模块都需要在其组件模块中导入 Ionic 组件。

¥For example, all modules that are using Ionic components need to have the Ionic components imported in their component module.

home.module.ts

import { NgModule } from '@angular/core';

import { CommonModule } from '@angular/common';

import { FormsModule } from '@angular/forms';

import { HomePage } from './home.page';

import { HomePageRoutingModule } from './home-routing.module';

+ import { IonContent, IonHeader, IonTitle, IonToolbar } from '@ionic/angular/standalone';

@NgModule({
  imports: [
    CommonModule,
    FormsModule,
    HomePageRoutingModule,
+    IonContent,
+    IonHeader,
+    IonTitle,
+    IonToolbar
  ],
  declarations: [HomePage]
})
export class HomePageModule {}

如果你使用 Ionicons，请使用 addIcons 定义每个 Angular 组件中使用的图标 SVG 数据。这允许你继续在组件模板中按字符串名称引用图标。请注意，你需要对添加的任何其他图标执行此操作。NgModule 中仍应提供 IonIcon 组件。

¥If you are using Ionicons, define the icon SVG data used in each Angular component using addIcons. This allows you to continue referencing icons by string name in your component template. Note that you will need to do this for any additional icons added. The IonIcon component should still be provided in the NgModule.

test.component.ts


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


+ import { addIcons } from 'ionicons';
+ import { alarm, logoIonic } from 'ionicons/icons';

@Component({
  selector: 'app-root',
  templateUrl: 'app.component.html',
  styleUrls: ['app.component.scss'],
})
export class TestComponent {
  constructor() {
+   addIcons({ alarm, logoIonic });
  }
}

test.module.ts


import { NgModule } from '@angular/core';


import { TestComponent } from './test.component';
+ import { IonIcon } from '@ionic/angular/standalone';

@NgModule({
  imports: [
+   IonIcon,
  ],
  declarations: [TestComponent]
})
export class TestComponentModule {}

从 angular.json 文件中删除以下代码（如果存在）。请注意，它可能会出现多次。

¥Remove the following code from your angular.json file if present. Note that it may appear multiple times.

angular.json
- {
-   "glob": "**/*.svg",
-   "input": "node_modules/ionicons/dist/ionicons/svg",
-   "output": "./svg"
- }

如果你使用 routerLink、routerDirection 或 routerAction，请务必导入 Ionic 组件的 IonRouterLink 指令或 <a> 元素的 IonRouterLinkWithHref 指令。

¥If you are using routerLink, routerDirection, or routerAction be sure to import the IonRouterLink directive for Ionic components or IonRouterLinkWithHref directive for <a> elements.

test.module.ts


import { NgModule } from '@angular/core';


import { TestComponent } from './test.component';
- import { IonButton } from '@ionic/angular/standalone';
+ import { IonButton, IonRouterLink } from '@ionic/angular/standalone';

@NgModule({
  imports: [
    IonButton,
+   IonRouterLink,
  ],
  declarations: [TestComponent]
})

如果你使用 VSCode，建议忽略导入建议的 @ionic/angular/common 和 @ionic/angular 模块说明符。

¥If you are using VSCode it is recommended to ignore the @ionic/angular/common and @ionic/angular module specifiers for import recommendations.

.vscode/settings.json
{
  "typescript.preferences.autoImportFileExcludePatterns": ["@ionic/angular/common", "@ionic/angular"]
}

构建选项

独立式​

概述​

与基于独立的应用一起使用​

与基于 NgModule 的应用一起使用​

模块​

概述​

用法​

从模块迁移到独立​

基于独立的应用​

基于 NgModule 的应用​

目录

独立式

概述

与基于独立的应用一起使用

与基于 NgModule 的应用一起使用

模块

概述

用法

从模块迁移到独立

基于独立的应用

基于 NgModule 的应用