Skip to content

1. 简介

本文档的 PDF 在 这里。

本文档的代码在 这里。

本文档由 Anthropic 的 AI Claude 创作。它沿用课程 “Flutter 移动框架分步入门”的大纲、示例和案例研究,并借用课程 “Angular 框架分步入门”中的工具:

  • 在 [Flutter] 课程中,应用是一个 移动应用,使用 [Dart] 编写,其引擎 [Flutter] 自己渲染每一个像素;
  • 在 [Angular] 课程中,应用是一个 Web应用:HTML、CSS 和 [TypeScript],由浏览器执行;
  • 在本课程中,应用二者兼备:它是一个 Web 应用,使用 [Angular] 和 [Ionic] 框架的组件编写,再由 [Capacitor] 工具打包成安装在手机上的 [Android] 应用。同样的代码无需任何修改,也可以在浏览器中运行。

不过,服务器保持不变:它仍是前面课程中的 JSON [RdvMedecins] 服务器,使用 [NestJS] 编写。应用的屏幕也是其他课程的读者已经熟悉的那些(带验证码的登录、医生的日程、预约窗口、患者门户、医生和客户管理、账户创建、法语和英语),只是针对手机屏幕做了调整。

本文档沿用与前几篇相同的结构:先是大量简短的示例,每个示例聚焦 [Ionic] 或 [Angular] 的一个概念,然后是完整的案例研究,即应用 [RdvMedecins] 的 [Ionic] 客户端,其所有文件都有注释。这 25 个示例的编号相同,显示的屏幕也与 [Flutter] 课程(以及 [React] 和 [Vue.js] 课程)中的一致:熟悉其中某个框架的读者会认出相同的示例,只不过是以 [Ionic] 和 [Angular] 的风格编写的。每个示例最后还会与 [Flutter] 做一番比较。

假定读者已熟悉 [TypeScript] 语言和 [Angular] 框架的基础知识:这些内容见课程 “通过示例入门 TypeScript 语言”和 “Angular 框架分步入门”。不过,所用到的 [Angular] 概念(信号、模板、依赖注入、路由器、响应式表单等)会在各示例中根据需要进行复习。

1.1. Ionic 在客户端/服务器应用中的角色

应用由两部分组成,它们之间只通过 HTTP 请求进行通信:

Image

  • 1:运行在手机上的 [Ionic] 应用向服务器发送 HTTP 请求,例如 [GET /api/schedule?doctorId=1&day=2026-10-05];
  • 2:服务器以 JSON 数据作为响应:即该医生当天的日程。它不生成任何页面;
  • 3:利用这些数据,[Angular] 更新手机屏幕。

这正是 [Flutter]、[React]、[Vue.js] 和 [Angular] 客户端的架构:唯一的区别在于由谁来生成显示。在这一点上,[Ionic] 与 [Flutter] 恰好相反。[Flutter] 是一个渲染引擎:它完全不依赖浏览器,自己渲染屏幕上的每一个像素。[Ionic] 则相反,它本身不渲染任何内容:它是一个 Web 组件库:即新的 HTML 元素——[<ion-button>]、[<ion-input>]、[<ion-list>]、[<ion-tabs>]……,它们由 [Stencil] 工具(来自 [Ionic] 团队)创建,任何浏览器都能显示。这些组件以两种“模式”模仿手机的原生组件:[md] ([Material Design],即 [Android] 的外观)和 [ios] ([iPhone] 的外观)。本课程在所有地方(包括浏览器中)都强制使用 [md] 模式。由于它们只是普通的 HTML 元素,[Ionic] 的组件可以与 [Angular]、[React] 或 [Vue.js] 一起使用:本课程将它们与 [Angular] (即 [@ionic/angular] 包)搭配使用。

因此,应用是一个标准的 Web应用:一个 HTML 页面、一个样式表,以及由 [JavaScript] 代码,它们是从 [TypeScript] 编译而来的。将它变成 [Android] 应用的是 [Capacitor] (与 [Ionic] 来自同一团队):

  • [Capacitor] 会生成一个原生的 [Android] 项目,其唯一的屏幕是一个 WebView:即手机上 [Chrome] 浏览器引擎,全屏显示,没有地址栏。编译后的 Web 应用被复制到这个项目中,WebView 在启动时加载它。对用户来说,它与任何其他应用无异:有图标、启动画面,以及 [Android] 的返回按钮;
  • [JavaScript] 代码通过 [Capacitor] 插件访问手机的功能(存储、相机、通知、地理定位等),这些插件充当通往原生代码的桥梁。本课程使用其中两个:[@capacitor/preferences](设备上的一个小型键值存储,见示例 20)和 [CapacitorHttp] (由 [Android] 的原生代码发出的 HTTP 请求,见示例 22 至 25);
  • 同样的代码在浏览器中运行,插件在浏览器中有 Web 版本(此时 [Capacitor] 的存储使用浏览器的 [localStorage])。因此我们在 [Chrome] 中以手机尺寸、借助其开发者工具进行开发,然后再切换到 [Android] 上进行测试。

应用的三个层次,以及它们各自提供的功能:

  • [Angular]:应用框架。它提供组件(一个 [TypeScript] 类和一个 HTML 模板)、信号(即状态,其变化会更新屏幕)、依赖注入(服务、共享状态)、路由器(每个屏幕一个地址)、表单、HTTP 客户端,以及“管道”(格式化)。[Flutter] 课程的读者会认出这一原则:界面是状态的函数。我们从不直接修改屏幕本身:我们修改状态,由 [Angular] 更新所有依赖于该状态的内容;
  • [Ionic]:界面组件,它们类似于移动应用的组件(工具栏、列表、字段、悬浮按钮、选项卡、警告窗口、日历等),以及移动应用的导航:一个页面栈,带有如同 [Android] 中的动画,返回按钮会将页面从栈中弹出;
  • [Capacitor]:[Android] 应用以及对手机的访问。

与 [Flutter] 不同,与服务器通信不需要额外的包:[Angular] 提供了 HTTP 客户端、路由器、表单和依赖注入;[JavaScript] 连同 [Intl] 对象,为每种语言提供日期和数字格式化;随 [RxJS] 库一起包含在 [Angular] 中,提供异步数据流。翻译(示例 21)由一个专门为此编写的小类处理,它读取 JSON 字典。

1.2. 所用工具

这些示例是使用以下工具编写和测试的(它们的安装见下一章和附录):

  • [Node.js] 24 及其包管理器 [npm]:[Angular CLI] 22 要求 [Node.js] 22.22.3(或更新的 22 版本)、24.15 或更高版本,或 26 及以上版本。[Node.js] 还负责运行 JSON 服务器;
  • [Angular CLI] 22.2([ng] 命令)、[Angular] 22.2 和 [TypeScript] 6.0;
  • [Ionic] 9.0([@ionic/angular] 9.0.6 包)及其图标 [ionicons] 8.1;
  • [Capacitor] 8.5(包 [@capacitor/core]、[@capacitor/android] 和 [@capacitor/cli])及其插件 [@capacitor/preferences] 8.0;
  • [Visual Studio Code] 编辑器及其扩展 [Angular Language Service] 和 [Ionic];
  • [Android Studio],用于获取 [Android] SDK、其 JDK 以及模拟器管理器:[Android] 模拟器 (电脑上的模拟手机),或连接到电脑的真实 [Android] 手机;
  • [Chrome] 浏览器,用于在电脑和手机上开发和调试应用;
  • [MySQL] 数据库管理系统 (或 [MariaDB]),例如 [Laragon] 在 [Windows] 下提供的那个:JSON 服务器需要它,详见介绍服务器的那一章;
  • 命令行工具 [curl],用于显示原始的 HTTP 响应。

所用的包来自两个 [package.json] 文件,它们所属的两个 [Ionic] 项目是相同的:[@angular/...] 22.2、[@ionic/angular] 9.0、[ionicons] 8.1、[@capacitor/...] 8.5、[@capacitor/app] 8.1、[@capacitor/preferences] 8.0、[rxjs] 7.8,以及仅用于开发的 [typescript] 6.0、[prettier] 3(代码排版)和 [playwright] 1.56(截图)。

1.3. 截图

本文档中的截图是由使用 [Playwright] 库的程序自动生成的(来自两个 [captures/] 文件夹,它们属于两个 [Ionic] 项目)。[captures/captures.mjs] 程序控制一个 [Chromium] 浏览器([Chrome] 的免费版本),其大小为 [Android] 手机的尺寸:412 x 892 点,每点 2.625 像素,得到 1082 x 2342 像素的图像。对于每个示例,它会运行 [captures/scenarios/] 文件夹中的一个“场景”:打开示例页面,像用户一样与之交互(输入文本、按下按钮),然后将屏幕保存为图像文件。

因此这些是应用的真实截图,由 [Chrome] 引擎渲染——与手机 WebView 所用的正是同一个引擎;缺少的只有手机的状态栏(时间、电量)和屏幕键盘。读者可以自行重新生成它们(应用必须处于运行状态;见下文):

1
2
3
npx playwright install chromium
npm run captures
node captures/captures.mjs 05 17
  • 第 1 行:仅需执行一次:下载 [Chromium] 浏览器,供 [Playwright] 使用;
  • 第 2 行:重新生成 [captures/images/] 文件夹中的所有截图;
  • 第 3 行:仅重新生成示例 05 和 17 的截图。

示例 22 至 25 和案例研究的截图还要求 JSON 服务器以验证码(CAPTCHA)的“测试模式”运行(见介绍服务器的那一章)。

1.4. 示例

本文档中的代码分为三个文件夹:

1
2
3
4
ionic-etape-par-etape-oct-2026/
├── examples_ionic/            the 25 small Ionic examples (a single project)
├── rdvmedecins-nestjs-json/   the RdvMedecins JSON server (the "black box")
└── rdvmedecins_ionic/         the Ionic client of the case study

这些示例构成一个单独的项目 [Ionic]:一个主页、示例菜单,以及每个示例一个页面,各自位于自己的 [src/app/] 文件夹中(示例 01 详细介绍了该项目):

examples_ionic/
├── angular.json               the Angular project configuration
├── capacitor.config.ts        the Capacitor configuration
├── package.json               the packages and the scripts of the project
├── proxy.conf.json            the relay to the JSON server (examples 22 to 25)
├── captures/                  the making of the screenshots
├── public/                    files delivered as is (icon, images, dictionaries)
└── src/
    ├── index.html             the page that hosts the application
    ├── main.ts                the entry point
    ├── styles.scss            the styles of the whole application
    └── app/
        ├── app.ts             the root component
        ├── app.routes.ts      the routes: one address per example
        ├── examples.ts        the list of the 25 examples
        ├── home/              the menu of the examples
        ├── common/            the code shared by examples 22 to 25
        ├── ex01-first-application/
        │   ├── ex01.page.ts   the page of example 01 (its class)
        │   └── ex01.page.html (its template)
        ├── ex02-state/
        ├── ...
        └── ex25-server-errors/

文件夹 [node_modules/] (各个包)和 [android/] ([Android] 项目)并未提供:前者由 [npm install] 填充,后者由 [Capacitor] 生成。在 [examples_ionic] 文件夹上打开的控制台中(在 [VS Code] 中:Terminal 菜单 / New Terminal):

npm install
npm start
  • 第 1 行:对所有示例只需执行一次:将 [package.json] 所描述的包下载到 [node_modules/] 文件夹中;
  • 第 2 行:启动 [ng serve],即 [Angular] 的开发服务器,地址为 [http://localhost:8100]。

在 [Chrome] 中打开此地址:主页按章节分组列出 25 个示例;点按某个示例即可打开它,其工具栏上的返回按钮会带你回到菜单。你也可以通过地址直接进入某个示例:[http://localhost:8100/ex05] 即示例 05。要以手机尺寸查看应用,请打开开发者工具(F12),然后打开设备模拟栏(Ctrl+Shift+M)。只要 [ng serve] 在运行,每次文件更改都会立即被编译并应用到浏览器中;按 Ctrl+C 可停止它。

在 [Android] 中,示例应用连同其 25 个示例和菜单一次性安装:

1
2
3
4
npx cap add android
npx ng build
npx cap sync android
npx cap run android
  • 第 1 行:只运行一次:创建 [android/] 文件夹和一个完整的 [Android Studio] 项目;
  • 第 2 行:将 Web 应用编译到 [dist/examples_ionic/browser/] 文件夹中;
  • 第 3 行:将其复制到 [Android] 项目中;
  • 第 4 行:构建 [Android] 应用,将其安装到正在运行的模拟器或已连接的手机上(如果有多个,该命令会询问使用哪一个),并启动它。

第 2 行到第 4 行在每次代码更改后都必须重新运行。示例 01 还展示了如何在手机上启用 [ng serve] 的自动重新加载。

示例 22 至 25 会查询 JSON 和 [RdvMedecins] 服务器:你需要按专门介绍它们的那一章所述,先安装并运行它们。在浏览器中,开发服务器会把请求 [/api] (文件 [proxy.conf.json])转发给它们;在模拟器上,它们连接到地址为 [http://10.0.2.2:8080] 的服务器(见示例 22)。

1.5. 文档内容

章节
内容
示例
Ionic 入门
一个 Ionic 项目(Angular + Capacitor)、Ionic 组件、状态(signal、computed、effect)、模板(@if、@for)、事件、所有字段类型、reducer、验证、响应式表单、格式化(Intl、管道)
01 至 09
组件
输入(input)、输出(output、model)、组合(内容投影、ng-template)、生命周期、依赖注入(服务、inject)、指令和动画、确认对话框(AlertController)
10 至 16
路由
Angular 的路由器和 ion-router-outlet:路由、参数、带 ion-tabs 的外壳、懒加载、404 页面、守卫
17 和 18
异步操作和共享状态
Promise、Observable(RxJS)、定时器、防抖、过期响应、async 管道、toSignal、resource、基于信号的服务、@capacitor/preferences、深色主题
19 和 20
国际化
法语和英语的应用
21
RdvMedecins 服务器,一个黑盒
安装 JSON 服务器、其 API、curl 示例
-
与服务器交互
HttpClient、开发代理、服务器地址、Android 上的 CapacitorHttp、httpOnly 令牌 Cookie(由浏览器或 Android 存储)、API 访问层、服务器错误
22 至 25
案例研究
RdvMedecins 应用的 Ionic 客户端
-
部署
由 JSON 服务器提供服务的已编译 Web 客户端;Android 应用
-

每个示例都附有完整的代码(逐行注释)和运行时的截图。代码本身有大量注释:这些注释是课程的一部分。