14. 附录
14.1. 安装 Node.js
[Node.js] 可从 nodejs.org 下载:选择 LTS(长期支持)版本,撰写本文时为 24 版。[Windows] 安装程序同时会安装 [npm]。[Node.js] 对于 [Ionic] 项目([Angular CLI] 22 要求 22.22 或更高版本)和 JSON 服务器都是必需的。在控制台中验证安装:
如果另一个项目需要较旧版本的 [Node.js],可以用版本管理器安装多个版本并在它们之间切换:[nvm-windows] 用于 [Windows],[nvm] 用于 [Linux] 和 [macOS] ([nvm install 24],然后 [nvm use 24])。
在 [Windows] 下,[PowerShell] 可能会拒绝运行 [npm] 和 [npx] 命令(“script execution is disabled on this system”):[Set-ExecutionPolicy -Scope CurrentUser RemoteSigned] 命令可为当前用户启用它。
14.2. 安装 Android Studio 和模拟器
[Android Studio] 可从 developer.android.com/studio 下载。它不是用来编写代码的,而是用来安装 [Android] 的 SDK、提供 JDK 并创建模拟器(详情见“搭建开发环境”一章):
- 首次启动时,向导会安装 [Android] 的 SDK;
- “More Actions”菜单 / “SDK Manager”,“SDK Tools”选项卡:勾选“Android SDK Platform-Tools”([adb])、“Android Emulator”和“Android SDK Command-line Tools”;
- 创建环境变量 [ANDROID_HOME] (SDK 文件夹)和 [JAVA_HOME]([Android Studio] 的 [jbr] 子文件夹),[Capacitor] 构建应用程序时需要它们;
- “More Actions”菜单 / “Virtual Device Manager”:使用较新的系统映像创建一部虚拟手机(例如“Pixel”)。点击 ▶ 按钮启动它;[adb devices] 随后会以名称 [emulator-5554] 检测到它。你也可以不打开 [Android Studio] 就启动它:[npx cap run android] 会列出你已创建的模拟器——即使它们处于停止状态——并启动你选择的那个;或者通过命令行,使用 SDK 中的 [emulator] 程序:[emulator -list-avds] 列出模拟器的名称,[emulator -avd <name>] 启动其中一个(在 [Windows] 下:[%ANDROID_HOME%\emulator\emulator.exe])。
对于真机:在“设置 / 关于手机”中,连续点按“版本号”七次会出现“开发者选项”,你可以在其中启用“USB 调试”。连接到电脑时,手机会要求你授权这台电脑;[adb devices] 随后就能检测到它。
由 [Android] 创建的 [Capacitor] 项目([android/] 文件夹)可通过 [npx cap open android] 在 [Android Studio] 中打开。其中包含 [Logcat] 窗口(应用程序和系统的消息,包括来自 [Capacitor] 插件的消息)和 [Run] 按钮,后者的作用与 [npx cap run android] 相同。
14.3. 安装 Visual Studio Code
[Visual Studio Code] 可从 code.visualstudio.com 下载。它内置了对 [TypeScript] 和 [JavaScript] 的支持。在“扩展”面板(Ctrl+Shift+X)中安装:
- [Angular Language Service] 扩展(来自 [Angular] 团队):模板中的自动补全和验证([HTML]——类的属性和方法、组件的输入,以及 [Ionic] 的组件属性)、从模板导航到其类代码(F12),以及在输入时显示模板编译错误;
- [Ionic] 扩展(来自 [Ionic] 团队):一个面板,用于在浏览器或 [Android] 设备上启动应用程序、管理 [Capacitor] 的插件,并通知用户 [Ionic] 和 [Capacitor] 包的更新;
- 可选地,安装 [Prettier] 扩展,它会在保存时按照项目的 [.prettierrc] 文件中指定的规则格式化代码。
通过“File / Open Folder”菜单打开项目(例如 [examples_ionic] 文件夹),并通过“Terminal / New Terminal”菜单打开控制台;你要在那里输入 [npm install]、[npm start]、[npx ng build]、[npx cap run android]……项目中的 [.vscode/launch.json] 文件还允许你通过 F5 启动应用程序:[VS Code] 随后会执行 [npm start],在 [Chrome] 中打开应用程序,你可以直接在编辑器中的 [TypeScript] 代码里设置断点。
14.4. Chrome 开发者工具
[Chrome] 的开发者工具之于 [Ionic] 应用,就如同 [Flutter DevTools] 之于 [Flutter] 应用。你可以用 F12(或 Ctrl+Shift+I)打开它们。其中最有用的选项卡有:
- 设备模拟栏(Ctrl-Shift-M):应用程序缩放到手机的尺寸(从列表中选择一款型号,或指定尺寸),并带有触摸事件。你就是这样先开发应用程序,然后再切换到 [Android] 的;
- “Elements”:页面的元素树,以及每个元素的样式(可以实时编辑)。左上角的箭头图标可以让你点击页面元素,在树中定位它。在那里你可以看到标签 [<ion-...>] 以及每个标签内部的“shadow DOM”:构成它的 HTML 元素。这个工具回答的问题是:“为什么这个元素不在它应该在的位置?”;
- “Console”:应用程序的消息([console.log()])和错误,以及它们产生所在的文件和行([TypeScript]);
- “Sources”:应用程序代码([TypeScript])(借助 [development] 配置中的“source map”),可以在其中设置断点;
- “Network”:应用程序的(HTTP)请求及其请求头和请求体:在这里(在浏览器中)可以看到令牌 Cookie 的发送和接收;
- “Application”:页面的存储([localStorage],在浏览器中 [@capacitor/preferences] 扩展把它的值存放在这里)及其 Cookie。
[Angular DevTools] 扩展(从 [Chrome Web Store] 安装)会添加一个“Angular”选项卡:屏幕的 [Angular] 组件树,以及每个组件的输入、信号和属性,可以实时修改;其“Profiler”选项卡会显示每个事件之后 [Angular] 更新了什么,以及花了多长时间。
同样的工具也可以调试安装在模拟器或手机上的应用程序。在电脑上的 [Chrome] 中,打开地址 [chrome://inspect]:该页面会列出通过 [adb] 连接的设备,以及每个设备上当前正在运行且允许调试的应用程序的 WebView(这适用于以“debug”模式构建的 [Capacitor] 应用,例如通过 [npx cap run android] 运行的)。“Inspect”链接会打开一个与应用程序的 WebView 相连的开发者工具窗口,手机的屏幕显示在左侧:你会在这里找到“Elements”、“Console”、“Sources”、“Network”等选项卡……由于 [CapacitorHttp] 发出的请求经过 [Android] 的原生代码,并非所有请求都会出现在“Network”选项卡中:[Logcat] 窗口(位于 [Android Studio] 中)会显示它们。
14.5. 使用 Laragon 安装 MySQL
JSON 服务器需要 [MySQL] (或 [MariaDB])。[Laragon] (laragon.org)会在 [Windows] 下安装其中一个,开箱即用,并带有 [HeidiSQL] 管理工具。安装之后:
- “Start All”按钮会在 3306 端口启动 [MySQL] 服务器;
- 用户 [root] 没有密码:这是服务器 [.env.example] 文件中的默认值;
- 在 [HeidiSQL] 中(“Database”按钮),通过“File / Run SQL”菜单项运行 [database/dbrdvmedecins2.sql] 脚本。
在 [Linux] 或 [macOS] 上,使用系统的包管理器安装 [MySQL] 或 [MariaDB] ,并使用命令行客户端运行该脚本:[mysql -u root -p < database/dbrdvmedecins2.sql]。
14.6. 安装 curl
[curl] 已包含在 [Windows] 10 和 11 版本、[macOS] 以及大多数 [Linux] 发行版中。检查其版本:
本文档中使用的选项 [--json] 自 7.82 版(2022 年)起可用。如果你使用的是较旧的版本,请把 [--json @file] 替换为 [-H "Content-Type: application/json" -d @file],或者从 curl.se 开始安装较新的版本。
在 [PowerShell] 中,必须输入 [curl.exe],而不是 [curl]:在 [PowerShell] 中,[curl] 是另一个命令([Invoke-WebRequest])的别名,该命令不包含 [curl] 的那些选项。命令提示符([cmd])则没有这个问题。