从 Capacitor 3 升级至 Capacitor 4
相较于之前的版本升级，Capacitor 3 和 4 之间的重大变更相对较少。本指南将提供将项目升级到当前 Capacitor 4 版本的步骤，以及我们官方插件的重大变更列表。
使用 CLI 进行迁移
通过 npm i -D @capacitor/cli@latest-4 安装最新版 Capacitor CLI 到项目中。安装完成后，只需运行 npx cap migrate，CLI 将自动处理迁移工作。如果迁移过程中的任何步骤无法完成，终端输出中会提供额外信息。以下还列出了手动迁移的步骤。
iOS 升级指南
以下指南描述如何将 Capacitor 3 iOS 项目升级至 Capacitor 4。
提升 iOS 部署目标
在 Xcode 项目中执行以下操作：在项目编辑器中选择 Project 并打开 Build Settings 标签页。在 Deployment 部分，将 iOS Deployment Target 改为 iOS 13.0。对任何应用 Targets 重复相同步骤。
然后，打开 ios/App/Podfile 并执行以下步骤：
- 在第一行添加：
require_relative '../../node_modules/@capacitor/ios/scripts/pods_helpers'
- 将 iOS 版本更新至 13.0：
platform :ios, '13.0'
- 在最后一行添加以下代码块：
post_install do |installer|
assertDeploymentTarget(installer)
end
移除不需要的代码
从 AppDelegate.swift 中移除未使用的 touchesBegan 方法
-override func touchesBegan(_ touches: Set<UITouch>, with event: UIEvent?) {
- super.touchesBegan(touches, with: event)
-
- let statusBarRect = UIApplication.shared.statusBarFrame
- guard let touchPoint = event?.allTouches?.first?.location(in: self.window) else { return }
-
- if statusBarRect.contains(touchPoint) {
- NotificationCenter.default.post(name: .capacitorStatusBarTapped, object: nil)
- }
-}
可选：从 Info.plist 中移除 NSAppTransportSecurity 条目
NSAppTransportSecurity 仅用于实时重载（live reload），如果你不使用实时重载或使用 Ionic CLI 进行实时重载，就不再需要此条目。
-<key>NSAppTransportSecurity</key>
-<dict>
- <key>NSAllowsArbitraryLoads</key>
- <true/>
-</dict>
Android 升级指南
以下指南描述如何将 Capacitor 3 Android 项目升级至 Capacitor 4。
更新 Android 项目变量
在 variables.gradle 文件中，更新以下值为新的最低要求，并新增 coreSplashScreenVersion 和 androidxWebkitVersion：
minSdkVersion = 22
compileSdkVersion = 32
targetSdkVersion = 32
androidxActivityVersion = '1.4.0'
androidxAppCompatVersion = '1.4.2'
androidxCoordinatorLayoutVersion = '1.2.0'
androidxCoreVersion = '1.8.0'
androidxFragmentVersion = '1.4.1'
coreSplashScreenVersion = '1.0.0-rc01'
androidxWebkitVersion = '1.4.0'
junitVersion = '4.13.2'
androidxJunitVersion = '1.1.3'
androidxEspressoCoreVersion = '3.4.0'
cordovaAndroidVersion = '10.1.1'
在 Android Manifest 中添加 android:exported 标签
在 AndroidManifest.xml 文件中，需要在 <activity> 标签中添加以下行：
android:exported="true"
此标签确保你可以打开应用中的此"Activity"（即屏幕）。想了解更多关于此标签及其他标签的信息，请查看 Android <activity> 参考文档。
默认情况下，AndroidManifest.xml 位于 android/app/src/main/AndroidManifest.xml。
更新 Gradle Google Services 插件
在 android/build.gradle 文件中，将 classpath 'com.google.gms:google-services:4.3.5' 改为 classpath 'com.google.gms:google-services:4.3.13' 以更新 Google Services 插件。
升级至 Gradle 7
在 File > Project Structure > Project 中调整 Gradle 项目设置。Android Gradle 插件版本应为 7.2.1 或更高，Gradle 版本应为 7.4.2 或更高。应用这些更改后，点击 Android Studio 右上角的大象图标执行 Gradle 同步。
Android Studio 可能会提供自动迁移至 Gradle 7 的选项。大胆接受吧！升级时，进入 build.gradle 文件，点击 💡 图标，然后选择 "Upgrade Gradle"。项目迁移完成后，按上述方法执行 Gradle 同步。
另一种选择是使用 Android Gradle 插件升级助手来处理迁移。此工具的步骤可在 Android 文档 中找到。
确保使用 Java 11
Capacitor 3 同时支持 Java 8 和 Java 11。从 Capacitor 4 开始，仅支持 Java 11。你可以通过 Android Studio 的以下菜单修改项目设置：
Preferences > Build, Execution, Deployment > Build Tools > Gradle
在这里，你可以将 "Gradle JDK" 修改为 Java 11。
最新版 Android Studio 自带 Java 11，无需额外下载！
切换至自动 Android 插件加载
这在 Capacitor 3 中是可选更改，但由于 init 方法已被移除，现在升级至 Capacitor 4 时变为强制要求。在 MainActivity.java 中，可以移除 onCreate 方法。通过 npm 安装或移除插件时，你不再需要编辑此文件。
public class MainActivity extends BridgeActivity {
- @Override
- public void onCreate(Bundle savedInstanceState) {
- super.onCreate(savedInstanceState);
-
- // Initializes the Bridge
- this.init(savedInstanceState, new ArrayList<Class<? extends Plugin>>() {{
- // Additional plugins you've installed go here
- add(Plugin1.class);
- add(Plugin2.class);
- }});
- }
}
更改 registerPlugin 顺序
如果你的应用包含专为应用构建的自定义插件，必须在 super.onCreate 之前注册它们：
public class MainActivity extends BridgeActivity {
@Override
public void onCreate(Bundle savedInstanceState) {
+ registerPlugin(PluginInMyApp.class);
super.onCreate(savedInstanceState);
- registerPlugin(PluginInMyApp.class);
}
}
可选：使用新的 Android 12 启动屏 API
为启用新的推荐 Android 12 启动屏 API，需要进行以下更改：
- 在
android/app/src/main/res/values/styles.xml中，将AppTheme.NoActionBarLaunch主题的parent属性从AppTheme.NoActionBar改为Theme.SplashScreen，并根据需要为主题添加选项。
<style name="AppTheme.NoActionBarLaunch" parent="Theme.SplashScreen">
<item name="android:background">@drawable/splash</item>
</style>
不启用 Android 12 启动屏将导致 Android 12+ 设备上出现双启动屏，并在旧设备上使用旧的启动屏。
此更改是可选的，但为防止 Android Studio 在更改后显示 Cannot resolve symbol 'Theme.SplashScreen' 消息，建议进行此更改。
- 在
android/app/build.gradle的 dependencies 部分添加implementation "androidx.core:core-splashscreen:$coreSplashScreenVersion"。
可选：使用 DayNight 主题
要让应用根据用户设备的主题自动切换（深色/浅色主题），在 android/app/src/main/res/values/styles.xml 中将 <style name="AppTheme.NoActionBar" parent="Theme.AppCompat.NoActionBar"> 改为 <style name="AppTheme.NoActionBar" parent="Theme.AppCompat.DayNight.NoActionBar">。
可选：从 Gradle 文件中移除 jcenter()
在之前的 Capacitor 版本中，由于我们的 Cordova 兼容层托管在 Jcenter 上，需要 jcenter()。但现在我们使用的是托管在 Maven Central 的最新版 Cordova Android。因此，你或许可以完全从 build.gradle 文件中移除 jcenter()。如果你使用其他插件或原生依赖项，确保它们没有托管在 Jcenter 上再移除！
插件变更
以下插件功能已被修改或移除。请相应更新你的代码。
存储
@capacitor/storage 插件已更名为 @capacitor/preferences，以更好地反映其用途。API 保持不变。
相机
- 移除了
preserveAspectRatio设置 - 插件不再提醒 iOS 使用说明缺失
androidxMaterialVersion变量更新至1.6.1androidxExifInterfaceVersion变量更新至1.3.3
操作表
ShowActionsOptions.title改为可选androidxMaterialVersion变量更新至1.6.1
仅 iOS
buildActionSheet的标题和消息现在为可选
推送通知
- 为
registrationError事件新增了RegistrationError类型 importance现在为可选，默认为3deleteChannel现在仅接受频道 ID 而非整个对象firebaseMessagingVersion变量更新至23.0.5- Android 现在遵守
presentationOptions配置选项
本地通知
importance现在为可选，默认为3deleteChannel现在仅接受频道 ID 而非整个对象- Android 12+ 需要 权限 来实现精确通知
应用
App.exitApp()现在返回一个 Promise
地理位置
getCurrentPosition()现在忽略超时playServicesLocationVersion更新至20.0.0- 当应用进入后台状态时，插件现在会停止位置更新
- 如果系统定位服务被禁用，插件现在会抛出错误
文件系统
copy现在返回复制文件的路径ReaddirResult现在返回一个FileInfo对象数组，其中包含每个文件的元数据及其 URIStatResult已统一，在所有平台上返回相同格式
设备
model现在在 iOS 上返回精确型号（从 "iPhone" 改为 "iPhone13.4"）getLanguageCode()现在在 Web 上返回短语言代码（与其他平台一致），如需完整代码请使用getLanguageTag()
对话框
title现在为可选
键盘
style配置选项现在使用KeyboardStyle枚举
通知提示
- 在 Android 12 及更高版本上，所有提示都显示在底部
浏览器
androidxBrowserVersion变量更新至1.4.0
启动屏
- 如果切换到新的 Android 12 启动屏 API，大多数配置选项将不适用于初始启动屏，但在调用
show()时仍可用于显示的启动屏。此外，在 Android 12+ 设备上，初始启动屏与show()方法显示的启动屏不同。