将应用中的 Capacitor 升级至 2.0 版本

Capacitor 2 带来了一些工具链更新，包括 iOS 平台采用 Swift 5 以及 Android 平台转向 AndroidX。

阅读 Capacitor 2.0 发布公告 ›

更新 Capacitor 依赖项

首先更新 Capacitor 核心库和 CLI：

npm install @capacitor/cli@2 @capacitor/core@2

接着更新所使用的各个平台模块：

# iOS
npm install @capacitor/ios@2
npx cap sync ios

# Android
npm install @capacitor/android@2
npx cap sync android

# Electron
cd electron
npm install @capacitor/electron@2

插件不兼容变更说明

• 相机插件
  • saveToGallery 在所有平台默认值改为 false
  • 当 allowEditing 为 true 且用户取消编辑时，会返回原始图片
• 推送通知
  • 调用 register() 时不再请求权限，需使用 requestPermission()
  • PushNotificationChannel 更名为 NotificationChannel
• 本地通知
  • 调用 register() 时不再请求权限，需使用 requestPermission()
  • schedule() 现在返回 LocalNotificationScheduleResult 对象
• Toast
  • 统一各平台显示时长：短提示 2000ms，长提示 3500ms
• 地理位置
  • Android 平台使用 Fused Location Provider
  • 移除了 GeolocationOptions 中的 requireAltitude 参数
  • 调整了 iOS 原生定位精度值（详情）
• 文件系统
  • 从 MkdirOptions 移除了 createIntermediateDirectories（改用 recursive）
  • 为 writeFile 添加 recursive 选项，改变了 Android 和 Web 平台行为（详情）
  • 移除了无法正常工作的 Application 目录选项
• 设备信息
  • 从 getInfo() 移除了 batteryLevel 和 isCharging，改用 getBatteryInfo()
• 模态框
  • inputPlaceholder 现在设置占位文本而非默认值，如需预设值请使用 inputText
• 应用
  • AppRestoredResult 变为可选，仅在恢复成功时返回，否则返回错误
• 剪贴板
  • 移除了 ReadOptions 类型

iOS 平台

Capacitor 2 需要 Xcode 11 及以上版本。

将原生项目升级至 Swift 5

Capacitor 2 使用 Swift 5，建议将您的原生项目也升级至 Swift 5。

1. 在 Xcode 中点击 Edit -> Convert -> To Current Swift Syntax
2. 选中 App.app 后点击 Next 按钮
3. 系统会提示 No source changes necessary
4. 最后点击 Update 按钮完成转换

Android 平台

AndroidX 迁移

Capacitor 2 按照 Google 推荐使用 AndroidX 作为 Android 支持库，因此原生项目也需要迁移至 AndroidX。

在 Android Studio 中选择 Refactor -> Migrate to AndroidX，然后点击 Migrate 按钮，最后点击 Do Refactor 完成重构。

如果使用了尚未支持 AndroidX 的 Cordova 或 Capacitor 插件，可以使用 jetifier 工具进行适配：

npm install jetifier
npx jetifier

如需在每次安装包后自动运行，可在 package.json 中添加 "postinstall": "jetifier"。

创建公共变量文件

创建 android/variables.gradle 文件并添加以下内容：

ext {
  minSdkVersion = 21
  compileSdkVersion = 29
  targetSdkVersion = 29
  androidxAppCompatVersion = '1.1.0'
  androidxCoreVersion =  '1.2.0'
  androidxMaterialVersion =  '1.1.0-rc02'
  androidxBrowserVersion =  '1.2.0'
  androidxLocalbroadcastmanagerVersion =  '1.0.0'
  firebaseMessagingVersion =  '20.1.2'
  playServicesLocationVersion =  '17.0.0'
  junitVersion =  '4.12'
  androidxJunitVersion =  '1.1.1'
  androidxEspressoCoreVersion =  '3.2.0'
  cordovaAndroidVersion =  '7.0.0'
}

在 android/build.gradle 文件中添加引用：

         classpath 'com.android.tools.build:gradle:4.1.1'
         classpath 'com.google.gms:google-services:4.3.3'

         // NOTE: Do not place your application dependencies here; they belong
         // in the individual module build.gradle files
     }
 }

+apply from: "variables.gradle"

 allprojects {
     repositories {
         google()
         jcenter()

使用公共变量

如果已创建 variables.gradle 文件，请更新项目以使用这些变量。

在 android/app/build.gradle 文件中进行如下修改：

 android {
-    compileSdkVersion 28
+    compileSdkVersion rootProject.ext.compileSdkVersion
     defaultConfig {
         applicationId "com.example.app"
-        minSdkVersion 21
-        targetSdkVersion 28
+        minSdkVersion rootProject.ext.minSdkVersion
+        targetSdkVersion rootProject.ext.targetSdkVersion
         versionCode 1
         versionName "1.0"
         testInstrumentationRunner "androidx.test.runner.AndroidJUnitRunner"

 dependencies {
     implementation fileTree(include: ['*.jar'], dir: 'libs')
-    implementation 'androidx.appcompat:appcompat:1.0.0'
+    implementation "androidx.appcompat:appcompat:$androidxAppCompatVersion"
     implementation project(':capacitor-android')
-    testImplementation 'junit:junit:4.12'
-    androidTestImplementation 'androidx.test.ext:junit:1.1.1'
-    androidTestImplementation 'androidx.test.espresso:espresso-core:3.1.0'
+    testImplementation "junit:junit:$junitVersion"
+    androidTestImplementation "androidx.test.ext:junit:$androidxJunitVersion"
+    androidTestImplementation "androidx.test.espresso:espresso-core:$androidxEspressoCoreVersion"
     implementation project(':capacitor-cordova-android-plugins')

注意要将单引号改为双引号，双引号是变量插值所必需的

建议更新 Android Studio 插件

当在 Android Studio 中打开项目时，会显示 Plugin Update Recommended 提示。点击 update，系统会建议更新 Gradle 插件和 Gradle 版本，点击 Update 按钮即可。

也可以手动更新 Gradle 插件和 Gradle：

• 在 android/build.gradle 中将 com.android.tool.build:gradle 版本更新至 3.6.1
• 在 android/gradle/wrapper/gradle-wrapper.properties 中将 gradle-4.10.1-all.zip 改为 gradle-5.6.4-all.zip

更新 Google Services 插件

在 android/build.gradle 文件中将 com.google.gms:google-services 依赖版本更新至 4.3.3：

     dependencies {
         classpath 'com.android.tools.build:gradle:4.1.1'
-        classpath 'com.google.gms:google-services:4.2.0'
+        classpath 'com.google.gms:google-services:4.3.3'

         // NOTE: Do not place your application dependencies here; they belong
         // in the individual module build.gradle files
     }

修改 android:configChanges 避免应用重启

在 android/app/src/main/AndroidManifest.xml 中，为 activity 的 android:configChanges 属性添加 |smallestScreenSize|screenLayout|uiMode：

         <activity
-            android:configChanges="orientation|keyboardHidden|keyboard|screenSize|locale"
+            android:configChanges="orientation|keyboardHidden|keyboard|screenSize|locale|smallestScreenSize|screenLayout|uiMode"
             android:name="com.example.app"
             android:label="@string/title_activity_main"
             android:theme="@style/AppTheme.NoActionBarLaunch"
             android:launchMode="singleTask">

在 FileProvider 文件路径中添加缓存目录

为了避免编辑相册图片时出现权限错误，在 android/app/src/main/res/xml/file_paths.xml 中添加 <cache-path name="my_cache_images" path="." />：

 <?xml version="1.0" encoding="utf-8"?>
 <paths xmlns:android="http://schemas.android.com/apk/res/android">
     <external-path name="my_images" path="." />
+    <cache-path name="my_cache_images" path="." />
 </paths>

移除 launch_splash.xml

可以删除 android/app/src/main/res/drawable/launch_splash.xml 文件，因为它已不再使用。

移除 maven 仓库

Capacitor 现在通过 npm 分发，因此可以移除 android/app/build.gradle 中的 maven 仓库配置以避免潜在问题：

 repositories {
-    maven {
-        url "https://dl.bintray.com/ionic-team/capacitor"
-    }
     flatDir {
         dirs '../capacitor-cordova-android-plugins/src/main/libs', 'libs'
     }
 }