版本：v4

将应用中的Capacitor升级至2.0

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

更新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
- 统一各平台显示时长：短提示2000毫秒，长提示3500毫秒
地理位置
- 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：

在Xcode中选择编辑 -> 转换 -> 转换为当前Swift语法
选中 App.app 后点击 下一步
系统会提示 无需源代码更改
最后点击更新按钮

Android平台

AndroidX支持库

Capacitor 2遵循Google建议使用AndroidX支持库，因此需要将原生项目也迁移至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 =  '۱.۲.۰'
  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()

使用公共变量

创建变量文件后，更新项目配置以使用这些变量。

在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中打开项目时，会出现 插件更新建议 提示。点击更新后按提示升级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:۴.۲.۰'
+        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的配置变更参数：

         <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添加缓存路径：

 <?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'
     }
 }

更新Capacitor依赖​

不向后兼容的插件变更​

iOS平台​

将原生项目升级至Swift 5​

Android平台​

AndroidX支持库​

创建公共变量配置​

使用公共变量​

建议更新Android Studio插件​

更新Google Services插件​

修改android:configChanges避免应用重启​

在FileProvider中添加缓存目录路径​

移除launch_splash.xml​

移除maven仓库配置​

Contents