跳到主要内容
版本：v3

在应用中升级 Capacitor 至 2.0

Capacitor 2 进行了一些工具链更新，包括在 iOS 中采用 Swift 5 以及在 Android 中采用 AndroidX。

阅读 Capacitor 2.0 公告 ›

更新 Capacitor 依赖项​

首先，更新 Capacitor Core 和 CLI：

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

接着，更新你使用的每个 Capacitor 平台：

# 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

不向后兼容的插件变更​

  • 相机 (Camera)
    • 所有平台上 saveToGallery 的默认值现在都是 false
    • 如果 allowEditing 为 true 且编辑被取消，将返回原始图像
  • 推送通知 (Push Notifications)
    • 调用 register() 时不再请求权限，请改用 requestPermission()
    • PushNotificationChannel 重命名为 NotificationChannel
  • 本地通知 (Local Notifications)
    • 调用 register() 时不再请求权限，请改用 requestPermission()
    • schedule() 现在返回 LocalNotificationScheduleResult
  • 消息提示 (Toast)
    • 统一各平台时长：短暂 (short) 2000 毫秒，长久 (long) 3500 毫秒
  • 地理位置 (Geolocation)
    • 在 Android 上使用融合定位提供程序 (Fused Location Provider)
    • GeolocationOptions 中移除了 requireAltitude
    • 更改了 iOS 上的原生定位精度值 (更多信息)
  • 文件系统 (Filesystem)
    • MkdirOptions 中移除了 createIntermediateDirectories (请改用 recursive)
    • writeFile 添加了 recursive 选项，这改变了 Android 和 Web 上的行为 (更多信息)
    • 移除了 Application 目录选项，因为它已损坏
  • 设备 (Device)
    • getInfo() 中移除了 batteryLevel 和 isCharging，请改用 getBatteryInfo()
  • 模态框 (Modals)
    • inputPlaceholder 设置占位符而非文本，请改用 inputText
  • 应用 (App)
    • AppRestoredResult 现在可选，仅在成功时返回，否则返回错误
  • 剪贴板 (Clipboard)
    • 移除了 ReadOptions

iOS​

Capacitor 2 需要 Xcode 11 或更高版本。

将原生项目更新至 Swift 5​

Capacitor 2 使用 Swift 5。建议也将你的原生项目更新至 Swift 5。

  1. 在 Xcode 中点击 编辑 -> 转换 -> 转换为当前 Swift 语法。
  2. App.app 将显示为选中状态，点击 下一步 按钮。
  3. 然后会提示 无需更改源代码。
  4. 最后，点击 更新 按钮。

Android​

AndroidX​

Capacitor 2 按照 Google 的建议，使用 AndroidX 作为 Android 支持库依赖项，因此原生项目也需要更新以使用 AndroidX。

在 Android Studio 中执行 重构 -> 迁移到 AndroidX。然后点击 迁移 按钮，最后点击 执行重构。

如果使用了尚未支持 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 文件中，添加 apply from: "variables.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 中打开 Android 项目时，会出现 建议更新插件 的提示。点击 更新。它会提示你更新 Gradle 插件和 Gradle。点击 更新 按钮。

你也可以手动更新 Gradle 插件和 Gradle。

要手动更新 Gradle 插件，在 android/build.gradle 文件中，将 com.android.tool.build:gradle 版本更新至 3.6.1。

要手动更新 Gradle，在 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">

将 caches 文件夹添加到 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 部分移除它：

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

Contents

编辑此页