ionic-angular

Compare original and translation side by side

🇺🇸

Original

English

🇨🇳

Translation

Chinese

Ionic Angular

Ionic development with Angular — project structure, Angular-specific components, navigation, lazy loading, forms, and lifecycle integration.

基于Angular的Ionic开发 —— 包括项目结构、Angular专属组件、导航、懒加载、表单和生命周期集成。

Prerequisites

前置条件

Ionic Framework 7 or 8 with
```
@ionic/angular
```
.
Angular 16+ (Angular 17+ recommended for standalone architecture).
Node.js and npm installed.
Ionic CLI installed (
```
npm install -g @ionic/cli
```
).

Ionic Framework 7或8 搭配
```
@ionic/angular
```
。
Angular 16+（独立组件架构推荐使用Angular 17+）。
已安装Node.js和npm。
已安装Ionic CLI（
```
npm install -g @ionic/cli
```
）。

Agent Behavior

Agent行为规范

Auto-detect architecture. Check
```
src/main.ts
```
for
```
bootstrapApplication
```
(standalone) vs.
```
platformBrowserDynamic().bootstrapModule
```
(NgModule). Adapt all code examples to the detected architecture.
Guide step-by-step. Walk the user through one topic at a time.
Adapt imports. For standalone components, import each Ionic component from
```
@ionic/angular/standalone
```
. For NgModule components, import
```
IonicModule
```
in the page module.

自动检测架构：检查
```
src/main.ts
```
中是
```
bootstrapApplication
```
（独立组件模式）还是
```
platformBrowserDynamic().bootstrapModule
```
（NgModule模式）。所有代码示例都要适配检测到的架构。
分步指导：一次只引导用户完成一个主题。
适配导入逻辑：对于独立组件，从
```
@ionic/angular/standalone
```
导入每个Ionic组件；对于NgModule组件，在页面模块中导入
```
IonicModule
```
。

Procedures

操作流程

Step 1: Analyze the Project

步骤1：分析项目

Auto-detect the following by reading project files — do not ask the user for information that can be inferred:

Ionic version: Read
```
@ionic/angular
```
version from
```
package.json
```
.
Angular version: Read
```
@angular/core
```
version from
```
package.json
```
.

Architecture: Check

src/main.ts

for

bootstrapApplication

(standalone) or

platformBrowserDynamic().bootstrapModule

(NgModule). If

src/app/app.module.ts

exists and imports

IonicModule

, confirm NgModule.

Capacitor: Check if
```
@capacitor/core
```
is in
```
package.json
```
. Check for
```
android/
```
and
```
ios/
```
directories.

Routing: Check for

src/app/app.routes.ts

(standalone) or

src/app/app-routing.module.ts

(NgModule).

Navigation pattern: Check
```
src/app/
```
for a
```
tabs/
```
directory (tab-based) or
```
ion-menu
```
usage in templates (side menu).

通过读取项目文件自动检测以下内容——不要向用户询问可以推断出的信息：

Ionic版本：从
```
package.json
```
中读取
```
@ionic/angular
```
的版本。
Angular版本：从
```
package.json
```
中读取
```
@angular/core
```
的版本。
架构类型：检查
```
src/main.ts
```
中的
```
bootstrapApplication
```
（独立组件）或
```
platformBrowserDynamic().bootstrapModule
```
（NgModule）。如果
```
src/app/app.module.ts
```
存在且导入了
```
IonicModule
```
，则确认为NgModule架构。
Capacitor配置：检查
```
package.json
```
中是否包含
```
@capacitor/core
```
，检查是否存在
```
android/
```
和
```
ios/
```
目录。
路由配置：检查是否存在
```
src/app/app.routes.ts
```
（独立组件模式）或
```
src/app/app-routing.module.ts
```
（NgModule模式）。
导航模式：检查
```
src/app/
```
下是否有
```
tabs/
```
目录（基于标签页的导航），或者模板中是否使用了
```
ion-menu
```
（侧边菜单导航）。

Step 2: Understand Project Structure

步骤2：了解项目结构

Read

references/project-structure.md

for the standard Ionic Angular directory layout.

Key points:

Standalone projects have
```
app.config.ts
```
,
```
app.routes.ts
```
, and standalone page components.

NgModule projects have

app.module.ts

app-routing.module.ts

, and per-page

*.module.ts

files.

Ionic config lives in
```
ionic.config.json
```
.
Theme variables are in
```
src/theme/variables.scss
```
.
Global styles and Ionic CSS imports are in
```
src/global.scss
```
.

阅读

references/project-structure.md

了解标准Ionic Angular目录结构。

关键要点：

独立组件项目包含
```
app.config.ts
```
、
```
app.routes.ts
```
和独立页面组件。
NgModule项目包含
```
app.module.ts
```
、
```
app-routing.module.ts
```
，以及每个页面对应的
```
*.module.ts
```
文件。
Ionic配置存放在
```
ionic.config.json
```
中。
主题变量存放在
```
src/theme/variables.scss
```
中。
全局样式和Ionic CSS导入存放在
```
src/global.scss
```
中。

Step 3: Understand Architecture Differences

步骤3：了解架构差异

Read

references/standalone-vs-ngmodules.md

for detailed differences.

Summary:

Aspect	Standalone	NgModule
Bootstrap	`bootstrapApplication` in `main.ts`	`platformBrowserDynamic().bootstrapModule`
Ionic setup	`provideIonicAngular({})` in `app.config.ts`	`IonicModule.forRoot()` in `app.module.ts`
Component imports	Import each Ionic component per file	`IonicModule` provides all globally
Import source	`@ionic/angular/standalone`	`@ionic/angular`
Lazy loading	`loadComponent` in routes	`loadChildren` in routes
Icon registration	`addIcons()` from `ionicons` required	Automatic
Tree-shaking	Yes	No

阅读

references/standalone-vs-ngmodules.md

了解详细差异。

摘要：

维度	独立组件（Standalone）	NgModule
引导方式	`main.ts` 中的 `bootstrapApplication`	`platformBrowserDynamic().bootstrapModule`
Ionic配置	`app.config.ts` 中的 `provideIonicAngular({})`	`app.module.ts` 中的 `IonicModule.forRoot()`
组件导入	每个文件单独导入所需Ionic组件	`IonicModule` 全局提供所有组件
导入来源	`@ionic/angular/standalone`	`@ionic/angular`
懒加载	路由中使用 `loadComponent`	路由中使用 `loadChildren`
图标注册	需要调用 `ionicons` 导出的 `addIcons()` 注册	自动注册
Tree-shaking	支持	不支持

Step 4: Set Up Navigation

步骤4：配置导航

Read

references/navigation.md

for full navigation patterns.

Topics covered:

Route configuration — defining routes with lazy loading for both architectures.
Root component layout —
```
<ion-app>
```
with
```
<ion-router-outlet>
```
.
Template navigation —
```
routerLink
```
with
```
routerDirection
```
for transition animations.

Programmatic navigation —

NavController

(

navigateForward

navigateBack

navigateRoot

back

Route parameters — reading params via
```
ActivatedRoute
```
.
Tab navigation —
```
<ion-tabs>
```
with child routes per tab.
Side menu —
```
<ion-menu>
```
with
```
<ion-menu-toggle>
```
and child routes.
Route guards — functional guards (Angular 15.2+) with
```
CanActivateFn
```
.
Modals —
```
ModalController
```
for overlay navigation with data passing.
Linear vs. non-linear routing — when to use each pattern.

阅读

references/navigation.md

了解完整导航模式。

涵盖的主题：

路由配置——为两种架构定义支持懒加载的路由。
根组件布局——包含
```
<ion-router-outlet>
```
的
```
<ion-app>
```
。
模板内导航——搭配
```
routerDirection
```
实现转场动画的
```
routerLink
```
。

编程式导航——

NavController

（

navigateForward

、

navigateBack

、

navigateRoot

、

back

）。

路由参数——通过
```
ActivatedRoute
```
读取参数。
标签页导航——每个标签页对应子路由的
```
<ion-tabs>
```
。
侧边菜单——搭配
```
<ion-menu-toggle>
```
和子路由的
```
<ion-menu>
```
。
路由守卫——Angular 15.2+版本中使用
```
CanActivateFn
```
的函数式守卫。
模态框——用于覆盖层导航并支持数据传递的
```
ModalController
```
。
线性与非线性路由——各自的适用场景。

Step 5: Implement Lifecycle Hooks

步骤5：实现生命周期钩子

Read

references/lifecycle.md

for Ionic page lifecycle hook details.

Key rules:

```
ngOnInit
```
fires once (first creation). Use for one-time setup.
```
ionViewWillEnter
```
fires on every page visit. Use for refreshing data.
```
ionViewDidEnter
```
fires after the transition animation. Use for heavy work that would block animations.
```
ionViewWillLeave
```
fires before leaving. Use for cleanup, pausing subscriptions.
```
ngOnDestroy
```
fires when the page is popped from the navigation stack. Use for final cleanup.

Implement interfaces

ViewWillEnter

ViewDidEnter

ViewWillLeave

ViewDidLeave

from

@ionic/angular

阅读

references/lifecycle.md

了解Ionic页面生命周期钩子的详细信息。

关键规则：

```
ngOnInit
```
仅触发一次（页面首次创建时），用于一次性初始化操作。
```
ionViewWillEnter
```
在每次进入页面时触发，用于刷新数据。
```
ionViewDidEnter
```
在转场动画完成后触发，用于执行会阻塞动画的重型操作。
```
ionViewWillLeave
```
在离开页面前触发，用于清理、暂停订阅。
```
ngOnDestroy
```
在页面从导航栈中弹出时触发，用于最终清理。

实现

@ionic/angular

导出的

ViewWillEnter

、

ViewDidEnter

、

ViewWillLeave

、

ViewDidLeave

接口。

Step 6: Build Forms

步骤6：构建表单

Read

references/forms.md

for form patterns with Ionic components.

Topics covered:

Reactive forms —
```
FormBuilder
```
,
```
FormGroup
```
,
```
Validators
```
with Ionic input components.
Template-driven forms —
```
[(ngModel)]
```
with
```
FormsModule
```
.

Ionic form components —

ion-input

ion-textarea

ion-select

ion-checkbox

ion-toggle

ion-radio-group

ion-range

ion-datetime

Validation display —
```
errorText
```
(Ionic 7+) or manual
```
<ion-note>
```
for older versions.
Label placement —
```
labelPlacement
```
attribute (
```
floating
```
,
```
stacked
```
,
```
fixed
```
).

阅读

references/forms.md

了解结合Ionic组件的表单模式。

涵盖的主题：

响应式表单——搭配Ionic输入组件使用
```
FormBuilder
```
、
```
FormGroup
```
、
```
Validators
```
。
模板驱动表单——搭配
```
FormsModule
```
使用
```
[(ngModel)]
```
。

Ionic表单组件——

ion-input

、

ion-textarea

、

ion-select

、

ion-checkbox

、

ion-toggle

、

ion-radio-group

、

ion-range

、

ion-datetime

。

校验提示展示——Ionic 7+使用
```
errorText
```
，旧版本手动使用
```
<ion-note>
```
。
标签位置——
```
labelPlacement
```
属性（
```
floating
```
浮动、
```
stacked
```
堆叠、
```
fixed
```
固定）。

Step 7: Manage Services and State

步骤7：管理服务与状态

Read

references/services-and-state.md

for service and state management patterns.

Topics covered:

Injectable services —
```
@Injectable({ providedIn: 'root' })
```
.
HTTP data fetching —
```
HttpClient
```
setup for standalone and NgModule, CRUD service pattern.
Reactive state —
```
BehaviorSubject
```
for shared observable state.
Angular signals —
```
signal()
```
and
```
computed()
```
for reactive state (Angular 16+).
Loading indicators —
```
LoadingController
```
for async operations.
Error feedback —
```
ToastController
```
for user-facing error/success messages.
Environment config —
```
environment.ts
```
/
```
environment.prod.ts
```
for API URLs.

阅读

references/services-and-state.md

了解服务与状态管理模式。

涵盖的主题：

可注入服务——
```
@Injectable({ providedIn: 'root' })
```
。
HTTP数据获取——适配独立组件和NgModule的
```
HttpClient
```
配置，CRUD服务模式。
响应式状态——用于共享可观察状态的
```
BehaviorSubject
```
。
Angular signals——Angular 16+中用于响应式状态的
```
signal()
```
和
```
computed()
```
。
加载指示器——用于异步操作的
```
LoadingController
```
。
错误反馈——向用户展示错误/成功消息的
```
ToastController
```
。
环境配置——存放API地址的
```
environment.ts
```
/
```
environment.prod.ts
```
。

Step 8: Optimize Performance

步骤8：优化性能

Read

references/performance.md

for performance optimization techniques.

Topics covered:

Lazy loading —
```
loadComponent
```
(standalone) and
```
loadChildren
```
(NgModule).
trackBy / track — efficient list rendering with
```
*ngFor
```
and
```
@for
```
.
Virtual scrolling — Angular CDK
```
cdk-virtual-scroll-viewport
```
for large lists.
OnPush change detection — reduce unnecessary re-renders.
Preloading strategy —
```
PreloadAllModules
```
for instant subsequent navigation.
Skeleton text —
```
ion-skeleton-text
```
for perceived performance during loading.

阅读

references/performance.md

了解性能优化技巧。

涵盖的主题：

懒加载——独立组件使用
```
loadComponent
```
，NgModule使用
```
loadChildren
```
。
trackBy / track——搭配
```
*ngFor
```
和
```
@for
```
实现高效列表渲染。
虚拟滚动——用于长列表的Angular CDK
```
cdk-virtual-scroll-viewport
```
。
OnPush变更检测——减少不必要的重渲染。
预加载策略——实现后续导航秒开的
```
PreloadAllModules
```
。
骨架屏——提升加载过程中感知性能的
```
ion-skeleton-text
```
。

Step 9: Write Tests

步骤9：编写测试

Read

references/testing.md

for testing patterns.

Topics covered:

Unit testing pages —
```
TestBed
```
setup for standalone and NgModule pages.
Testing services — basic services and HTTP services with
```
HttpTestingController
```
.
Mocking dependencies —
```
jasmine.createSpyObj
```
for service and controller mocks.
Testing navigation — mocking
```
NavController
```
.
Testing guards —
```
TestBed.runInInjectionContext
```
for functional guards.
E2E testing — Cypress and Playwright setup.

阅读

references/testing.md

了解测试模式。

涵盖的主题：

页面单元测试——适配独立组件和NgModule页面的
```
TestBed
```
配置。
服务测试——基础服务测试，以及使用
```
HttpTestingController
```
测试HTTP服务。
依赖Mock——使用
```
jasmine.createSpyObj
```
模拟服务和控制器。
导航测试——模拟
```
NavController
```
。
守卫测试——针对函数式守卫的
```
TestBed.runInInjectionContext
```
。
E2E测试——Cypress和Playwright配置。

Error Handling

错误处理

NullInjectorError: No provider for IonRouterOutlet
: In standalone apps, verify

provideIonicAngular({})

is called in

app.config.ts

. In NgModule apps, verify

IonicModule.forRoot()

is imported in

app.module.ts

Ionic components not rendering: In standalone components, verify each Ionic component is imported from
```
@ionic/angular/standalone
```
and listed in the
```
imports
```
array. In NgModule components, verify
```
IonicModule
```
is imported in the page module.
Icons not showing (standalone): Verify
```
addIcons()
```
is called with the required icons from
```
ionicons/icons
```
, and
```
IonIcon
```
is imported from
```
@ionic/angular/standalone
```
.
ionViewWillEnter
not firing: Verify the component is directly routed via
```
<ion-router-outlet>
```
. Child components do not receive Ionic lifecycle events.
Page data not refreshing on back navigation: Use
```
ionViewWillEnter
```
instead of
```
ngOnInit
```
for data loading. Ionic caches pages in the DOM, so
```
ngOnInit
```
only fires once.
Form validation errors not displaying: For Ionic 7+, use
```
errorText
```
on
```
<ion-input>
```
. For older versions, manually check
```
control.invalid && control.touched
```
and show
```
<ion-note>
```
.
routerLink
not working on Ionic components: In standalone components, import
```
RouterLink
```
from
```
@angular/router
```
in the component's
```
imports
```
array.
Page transitions not animating: Use
```
NavController
```
from
```
@ionic/angular
```
instead of Angular's
```
Router
```
for animated navigation. Alternatively, add
```
routerDirection
```
to
```
routerLink
```
elements.
Tab navigation broken: Verify the
```
tab
```
attribute on
```
<ion-tab-button>
```
matches the child route
```
path
```
. Do not programmatically navigate between tabs.

NullInjectorError: No provider for IonRouterOutlet
：独立组件应用中，请确认

app.config.ts

中调用了

provideIonicAngular({})

；NgModule应用中，请确认

app.module.ts

中导入了

IonicModule.forRoot()

。

Ionic组件不渲染：独立组件中，请确认每个Ionic组件都从
```
@ionic/angular/standalone
```
导入并添加到
```
imports
```
数组中；NgModule组件中，请确认页面模块中导入了
```
IonicModule
```
。
图标不显示（独立组件模式）：请确认调用了
```
addIcons()
```
引入
```
ionicons/icons
```
中的所需图标，且已从
```
@ionic/angular/standalone
```
导入了
```
IonIcon
```
。
ionViewWillEnter
不触发：请确认组件是通过
```
<ion-router-outlet>
```
直接路由的，子组件不会收到Ionic生命周期事件。
返回导航时页面数据不刷新：数据加载请使用
```
ionViewWillEnter
```
而非
```
ngOnInit
```
，Ionic会在DOM中缓存页面，因此
```
ngOnInit
```
仅会触发一次。
表单校验错误不展示：Ionic 7+请在
```
<ion-input>
```
上使用
```
errorText
```
；旧版本请手动检查
```
control.invalid && control.touched
```
并展示
```
<ion-note>
```
。
Ionic组件上的
routerLink
不生效：独立组件中，请在组件的
```
imports
```
数组中从
```
@angular/router
```
导入
```
RouterLink
```
。
页面转场无动画：请使用
```
@ionic/angular
```
导出的
```
NavController
```
而非Angular原生
```
Router
```
实现带动画的导航，也可以在
```
routerLink
```
元素上添加
```
routerDirection
```
属性。
标签页导航失效：请确认
```
<ion-tab-button>
```
上的
```
tab
```
属性与子路由的
```
path
```
匹配，不要通过编程方式在标签页之间跳转。

ionic-angular

Original

Translation

Ionic Angular

Ionic Angular

Prerequisites

前置条件

Agent Behavior

Agent行为规范

Procedures

操作流程

Step 1: Analyze the Project

步骤1：分析项目

Step 2: Understand Project Structure

步骤2：了解项目结构

Step 3: Understand Architecture Differences

步骤3：了解架构差异

Step 4: Set Up Navigation

步骤4：配置导航

Step 5: Implement Lifecycle Hooks

步骤5：实现生命周期钩子

Step 6: Build Forms

步骤6：构建表单

Step 7: Manage Services and State

步骤7：管理服务与状态

Step 8: Optimize Performance

步骤8：优化性能

Step 9: Write Tests

步骤9：编写测试

Error Handling

错误处理

Related Skills

相关技能