ionic-angular

Ionic Angular

使用 Angular 进行 Ionic 开发——项目结构、Angular 专属组件、导航、惰性加载、表单和生命周期集成。

前置条件

1. Ionic Framework 7 或 8，并使用 @ionic/angular。
2. Angular 16+（推荐使用 Angular 17+，以采用独立架构）。
3. 已安装 Node.js 和 npm。
4. 已安装 Ionic CLI（npm install -g @ionic/cli）。

Agent 行为

• 自动检测架构。 检查 src/main.ts 中的 bootstrapApplication（独立架构）或 platformBrowserDynamic().bootstrapModule（NgModule）。根据检测到的架构调整所有代码示例。
• 逐步引导。 一次引导用户了解一个主题。
• 调整导入方式。 对于独立组件，从 @ionic/angular/standalone 导入每个 Ionic 组件。对于 NgModule 组件，在页面模块中导入 IonicModule。

操作步骤

第 1 步：分析项目

读取项目文件，自动检测以下信息——不要询问用户可以从项目文件推断出的信息：

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

第 2 步：了解项目结构

阅读 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。

第 3 步：了解架构差异

阅读 references/standalone-vs-ngmodules.md，了解详细差异。

摘要：

方面	独立架构	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	是	否

步骤 4：设置导航

阅读 references/navigation.md，了解完整的导航模式。

涵盖主题：

• 路由配置 — 为两种架构定义路由并启用惰性加载。
• 根组件布局 — 使用 <ion-app> 和 <ion-router-outlet>。
• 模板导航 — 使用 routerLink 和 routerDirection 设置转场动画。
• 编程式导航 — NavController（navigateForward、navigateBack、navigateRoot、back）。
• 路由参数 — 通过 ActivatedRoute 读取参数。
• 标签导航 — 使用 <ion-tabs>，并为每个标签设置子路由。
• 侧边菜单 — 使用 <ion-menu> 和 <ion-menu-toggle>，并设置子路由。
• 路由守卫 — 使用 CanActivateFn 的函数式守卫（Angular 15.2+）。
• 模态框 — 使用 ModalController 实现带数据传递的覆盖式导航。
• 线性与非线性路由 — 了解何时使用各模式。

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

阅读 references/lifecycle.md，了解 Ionic 页面生命周期钩子的详细信息。

关键规则：

• ngOnInit 仅触发一次（首次创建时）。用于一次性设置。
• ionViewWillEnter 在每次访问页面时触发。用于刷新数据。
• ionViewDidEnter 在转场动画后触发。用于不会阻塞动画的繁重工作。
• ionViewWillLeave 在离开页面前触发。用于清理、暂停订阅。
• 页面从导航栈中弹出时会触发 ngOnDestroy。用于最终清理。
• 实现来自 @ionic/angular 的接口 ViewWillEnter、ViewDidEnter、ViewWillLeave、ViewDidLeave。

步骤 6：构建表单

阅读 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。
• 验证信息显示 — 使用 errorText（Ionic 7+），或在较旧版本中手动使用 <ion-note>。
• 标签位置 — labelPlacement 属性（floating、stacked、fixed）。

步骤 7：管理服务和状态

阅读 references/services-and-state.md，了解服务和状态管理模式。

涵盖主题：

• 可注入服务 — @Injectable({ providedIn: 'root' })。
• HTTP 数据获取 — 为独立组件和 NgModule 设置 HttpClient，以及 CRUD 服务模式。
• 响应式状态 — 使用 BehaviorSubject 管理共享的可观察状态。
• Angular 信号 — 使用 signal() 和 computed() 管理响应式状态（Angular 16+）。
• 加载指示器 — 使用 LoadingController 处理异步操作。
• 错误反馈 — 使用 ToastController 显示面向用户的错误或成功消息。
• 环境配置 — 使用 environment.ts / environment.prod.ts 配置 API URL。

步骤 8：优化性能

阅读 references/performance.md，了解性能优化技巧。

涵盖主题：

• 惰性加载 — 使用 loadComponent（独立组件）和 loadChildren（NgModule）。
• trackBy / track — 使用 *ngFor 和 @for 高效渲染列表。
• 虚拟滚动 — 使用 Angular CDK 的 cdk-virtual-scroll-viewport 处理大型列表。
• OnPush 变更检测 — 减少不必要的重新渲染。
• 预加载策略 — 使用 PreloadAllModules 实现后续导航即时加载。
• 骨架文本 — 使用 ion-skeleton-text，提升加载期间的感知性能。

步骤 9：编写测试

阅读 references/testing.md，了解测试模式。

涵盖主题：

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

错误处理

• NullInjectorError: No provider for IonRouterOutlet：在独立应用中，确认已在 app.config.ts 中调用 provideIonicAngular({})。在 NgModule 应用中，确认已在 app.module.ts 中导入 IonicModule.forRoot()。
• Ionic 组件未渲染：在独立组件中，确认已从 @ionic/angular/standalone 导入每个 Ionic 组件，并将其列在 imports 数组中。在 NgModule 组件中，确认已在页面模块中导入 IonicModule。
• 图标未显示（独立组件）：确认已使用 ionicons/icons 中所需的图标调用 addIcons()，并已从 @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>。
• routerLink 在 Ionic 组件上不起作用：在独立组件中，在组件的 imports 数组中从 @angular/router 导入 RouterLink。
• 页面转场没有动画：使用来自 @ionic/angular 的 NavController，而非 Angular 的 Router，以实现带动画的导航。或者，在 routerLink 元素上添加 routerDirection。
• 标签页导航异常：确认 <ion-tab-button> 上的 tab 属性与子路由的 path 匹配。不要以编程方式在标签页之间导航。

相关技能

• capacitor-angular — Capacitor 专用的 Angular 模式（插件服务、NgZone、深层链接、平台检测）。
• ionic-app-development — 通用 Ionic 开发（组件、主题、CLI）。
• ionic-app-creation — 从头开始创建新的 Ionic 应用。
• ionic-app-upgrades — 将 Ionic 升级到较新版本。