跳到主要内容
版本：v4

从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并按以下步骤操作：

  1. 在第一行添加：
require_relative '../../node_modules/@capacitor/ios/scripts/pods_helpers'
  1. 将iOS版本更新至13.0：
platform :ios, '13.0'
  1. 在最后一行添加：
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仅用于实时重载功能，如果您不使用实时重载或使用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清单中添加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'。

升级至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插件升级助手自动完成迁移。 :::

确保使用Java 11​

Capacitor 3支持Java 8和Java 11，而Capacitor 4将仅支持Java 11。在Android Studio中通过以下菜单修改配置：

Preferences > Build, Execution, Deployment > Build Tools > Gradle

Gradle偏好设置

在此处将"Gradle JDK"修改为Java 11。

:::提示 Java 11已包含在最新版Android Studio中，无需额外下载！ :::

切换至自动加载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);
-        }});
-    }
 }

调整插件注册顺序​

如果应用包含自定义插件，需在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启动页API，在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而需要此配置。现在我们使用托管在Maven Central的最新版Cordova Android。如果其他插件或原生依赖不再依赖Jcenter，可以完全移除jcenter()配置。

插件变更​

以下插件功能已修改或移除，请相应调整代码。

存储​

@capacitor/storage插件已重命名为@capacitor/preferences以更准确反映用途，API保持不变。

相机​

  • 移除preserveAspectRatio配置项
  • 不再提示iOS使用说明缺失
  • androidxMaterialVersion更新至1.6.1
  • androidxExifInterfaceVersion更新至1.3.3

操作表​

  • ShowActionsOptions.title变为可选
  • androidxMaterialVersion更新至1.6.1

仅iOS​

  • buildActionSheet的标题和消息变为可选

推送通知​

  • 为registrationError事件新增RegistrationError类型
  • importance变为可选，默认为3
  • deleteChannel现在仅接收频道ID而非完整对象
  • firebaseMessagingVersion更新至23.0.5
  • Android现在支持presentationOptions配置项

本地通知​

  • importance变为可选，默认为3
  • deleteChannel现在仅接收频道ID而非完整对象
  • Android 12+需要精确通知权限

应用​

  • App.exitApp()现在返回Promise

地理位置​

  • getCurrentPosition()的超时设置将被忽略
  • playServicesLocationVersion更新至20.0.0
  • 应用进入后台时停止位置更新
  • 系统定位服务禁用时会抛出错误

文件系统​

  • copy现在返回被复制文件的路径
  • ReaddirResult现在返回包含元数据的FileInfo对象数组
  • StatResult在各平台返回统一格式

设备​

  • iOS的model现在返回精确型号（从"iPhone"变为"iPhone13.4"）
  • getLanguageCode()在Web端返回简写语言代码（与其他平台一致），获取完整代码请使用getLanguageTag()

对话框​

  • title变为可选

键盘​

  • style配置项现在使用KeyboardStyle枚举

吐司​

  • Android 12及以上版本所有吐司显示在底部

浏览器​

  • androidxBrowserVersion更新至1.4.0

启动页​

  • 若启用Android 12启动页API，大多数配置项对初始启动页无效（仍适用于show()调用的启动页）。Android 12+设备的初始启动页与show()方法的启动页不同。

Contents

编辑此页