构建选项
¥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.
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';
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.
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.
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.
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.
<!--
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.
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 {}
<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
所有 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
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.
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.
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
中。
¥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
. The IonIcon
component should be added in app.module.ts
just like the other Ionic components.
我们建议在 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.
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
之类的入口点中,以避免需要多次调用 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.
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.
<!--
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.
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 {}
<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/*)@)"]
模块
¥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.