跳到主要内容
版本：v7

从 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 项目执行以下操作：在项目编辑器中选择 项目，然后打开 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 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 首选项

在那里，你可以将 "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);
-        }});
-    }
 }

更改 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"。### 可选：使用日夜主题

若希望根据用户设备主题自动切换深浅主题，请将 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.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 对象数组，其中除了包含每个文件的 URI 外，还包含相关元数据。
  • StatResult 已统一，确保在所有平台上返回相同的结果。

设备​

  • model 现在在 iOS 上返回确切的型号（例如从 "iPhone" 改为 "iPhone13.4"）。
  • getLanguageCode() 现在在 Web 端返回短语言代码（与其他平台一致），如需获取完整代码请使用 getLanguageTag()。

对话框​

  • title 现在是可选的。

键盘​

  • style 配置选项现在使用 KeyboardStyle 枚举来提供选项。

消息提示​

  • 在 Android 12 及更高版本上，所有消息提示都显示在屏幕底部。

浏览器​

  • androidxBrowserVersion 变量已更新至 1.4.0。

启动画面​

  • 如果切换到新的 Android 12 启动画面 API，大多数配置选项将不适用于初始启动画面，但在调用 show() 时显示的启动画面仍会保留这些选项。此外，在 Android 12+ 设备上，初始启动画面与 show() 方法显示的启动画面不同。

Contents

编辑此页