跳到主要内容
版本：v5

在插件中将 Capacitor 升级至 3.0

对于需要升级到 Capacitor 3 的插件，有几项必需及建议的更改。

为核心 API 制定规划​

目前，核心团队很难在不影响插件的情况下对 Capacitor 的内部实现进行调整。因为在 Capacitor 2 中，大部分类和方法在 iOS 和 Android 平台上都是公开的，我们已经观察到一些对 Capacitor API 的不当使用，而这些 API 原本属于内部接口。

在 Capacitor 3 的开发过程中，我们将评估这一问题，并为插件创建官方的公开 API，相关文档将在此处提供。

Android​

使用新的 @CapacitorPlugin 注解​

@NativePlugin 注解已弃用。我们现在推荐使用新的 @CapacitorPlugin 注解，这将支持新的权限 API。

name 属性保持不变。requestCodes 和 permissionRequestCode 属性已被移除。permissions 属性需要替换为 @Permission 注解列表，每个注解包含一组清单字符串及其对应的 alias（在插件中实现新的权限 API 之前，可以暂时省略）。

-@NativePlugin(
+@CapacitorPlugin(
     name = "FooBar",
-    requestCodes = {
-        FooBarPlugin.REQUEST_SOME_METHOD,
-        FooBarPlugin.REQUEST_SOME_OTHER_METHOD
-    },
-    permissionRequestCode = FooBarPlugin.REQUEST_ALL_PERMISSIONS,
-    permissions = { Manifest.permission.FOO, Manifest.permission.BAR }
+    permissions = {
+        @Permission(strings = { Manifest.permission.FOO }, alias = "foo"),
+        @Permission(strings = { Manifest.permission.BAR }, alias = "bar")
+    })
 )
 public class FooBarPlugin extends Plugin {
     static final int REQUEST_SOME_METHOD = 10051;
     static final int REQUEST_SOME_OTHER_METHOD = 10052;

Android 请求码​

Capacitor 3.0 实现了 AndroidX Activity Result API，并移除了手动定义的请求码。插件不应再提供请求码并重写 handleOnActivityResult 或 handleRequestPermissionsResult 方法，而应使用 @ActivityCallback 或 @PermissionCallback 注解来提供回调方法。这些回调可以在启动新的 Activity 或权限请求时被引用。

-static final int IMAGE_REQUEST = 10052;

 @PluginMethod
 public void chooseImage(PluginCall call) {
     Intent intent = new Intent(Intent.ACTION_PICK);
     intent.setType("image/*");
-    startActivityForResult(call, intent, IMAGE_REQUEST);
+    startActivityForResult(call, intent, "chooseImageResult");
 }

+@ActivityCallback
+private void chooseImageResult(PluginCall call, ActivityResult result) {
+    if (result.getResultCode() == Activity.RESULT_CANCELED) {
+        call.reject("Activity canceled");
+    } else {
+        Intent data = result.getData();
+        // 使用结果数据进行处理
+        call.resolve("Success!");
+    }
+}

使用 WebColor.parseColor() 替代 Color.parseColor()​

Android 将带 Alpha 通道的十六进制颜色字符串解析为 ARGB 格式，而在 iOS 和 Web 平台上，它们被解析为 RGBA 格式。如果你需要在跨平台共享带 Alpha 通道的颜色，请务必使用新的 WebColor 工具。WebColor.parseColor() 的功能类似于 Android 原生的 Color.parseColor() 方法，但会以 RGBA 格式解析字符串。

String colorStringWithAlpha = "#FF000088"; // 半透明红色
int color = WebColor.parseColor(colorStringWithAlpha);

如果你的颜色不包含 Alpha 通道，两个函数将返回相同的结果。

将默认的 compileSdkVersion 和 targetSdkVersion 更改为 30​

在 android/build.gradle 文件中，将 compileSdkVersion 和 targetSdkVersion 的默认值更改为 30。

android {
-   compileSdkVersion project.hasProperty('compileSdkVersion') ? rootProject.ext.compileSdkVersion : 29
+   compileSdkVersion project.hasProperty('compileSdkVersion') ? rootProject.ext.compileSdkVersion : 30
    defaultConfig {
        minSdkVersion project.hasProperty('minSdkVersion') ? rootProject.ext.minSdkVersion : 21
-       targetSdkVersion project.hasProperty('targetSdkVersion') ? rootProject.ext.targetSdkVersion : 29
+       targetSdkVersion project.hasProperty('targetSdkVersion') ? rootProject.ext.targetSdkVersion : 30
        ...
    }
    ...
}

iOS​

弱引用​

Capacitor 3 中更新了对象之间的关系，以修复内存泄漏问题。其结果是，插件对层级中更高层对象的引用现在变为 weak，在 Swift 中这意味着它们是可选类型。你很可能在访问 bridge 时遇到这一变化，但它也适用于其他属性，例如 webView。调用 bridge 上的方法相对变化不大，只是现在需要使用可选链：

-bridge.presentVC(myViewController, animated: true, completion: nil)
+bridge?.presentVC(myViewController, animated: true, completion: nil)

这一变化的最大影响是，所有从 bridge 返回的值也将变为可选类型。安全地处理和拆包可选值可能需要额外的步骤。

if bridge?.isSimEnvironment {
     // 错误：无法编译。由于 bridge 是可选类型，布尔值也是可选的，在评估之前必须进行拆包。
}
if bridge?.isSimEnvironment == true {
     // 中性：与可选值进行显式比较适用于布尔类型，但可能不适合所有数据类型。
}
if let isSim = bridge?.isSimEnvironment, isSim {
     // 良好：在检查其值之前，使用可选绑定来拆包可选值。
}

Bridge 变更​

除了引用从 strong 变为 weak 之外，bridge 本身的 API 也已更新（现在通过更正式的协议暴露）。许多属性和方法已重命名，但在可能的情况下，通过保留和弃用旧接口提供了向后支持。在大多数情况下，Xcode 将能够自动建议新的替代方案。你应该迁移所有现有代码，以便你的插件能够在没有编译器警告的情况下构建。

Xcode 自动更正建议

CAPPluginCall 参数​

Capacitor 在 CAPPluginCall 上提供了一系列便捷方法（getString、getDate 等）来访问从 JavaScript 传递给插件方法的数据。这些方法在 Capacitor 3 中已更新。

  • get() 已被移除。如果你想直接访问参数，请读取 options 字典。
  • hasOption 已被弃用。使用类型化的访问器之一来检查值是否存在。
  • 任何接受默认值的访问器现在都需要一个非可选的默认值，但会返回一个非可选的结果。这可能会改变你本地变量的可选性，但应该减少强制拆包的使用，这在 Swift 中是一种反模式。
  • 关于日期和空值的行为已略有改变，并有了更好的文档说明。在此处查看更多信息。
  • Objective-C 的便捷访问器已被拆分出来，以避免与 Swift 实现冲突。如果你在使用 Objective-C，你需要单独导入它们，方法是在你的 .m 文件中添加 #import <Capacitor/CAPBridgedJSTypes.h>。

PluginCall 和 CAPPluginCall 的变更### 使用 resolve() 和 reject()​

我们认为 resolve() 和 reject() 能更好地体现插件方法所期望的类 Promise 流程。即使是在回调风格的插件方法中，也应优先使用它们（而非现已弃用的 success() 和 error()）。

不带参数的 resolve() 现在会解析为 undefined​

此前，不带参数调用 resolve() 会导致向 JavaScript 层发送一个空对象。由于这与 JavaScript 的 Promise.resolve() 行为不符，从 Capacitor 3 开始，将改为发送 undefined。

保存调用​

save() 方法已被弃用，并新增了替代属性 keepAlive。现已记录推荐的保存调用模式，以明确其行为。点击此处了解更多详情

将 iOS 部署目标设置为 12.0​

请对插件的 Xcode 项目和插件目标进行以下操作：打开 Build Settings 标签页。在 Deployment 部分下，将 iOS Deployment Target 改为 iOS 12.0。

接着，打开 ios/Podfile 并将 iOS 版本更新至 12.0：

-platform :ios, '11.0'
+platform :ios, '12.0'
 use_frameworks!

最后，打开 pluginName.podspec 并将 iOS 版本更新至 12.0：

-s.ios.deployment_target  = '11.0'
+s.ios.deployment_target  = '12.0'

将 Swift 版本设置为 5​

在 Xcode 目标中打开 Build Settings 标签页，然后在 Swift Compiler - Language 部分下，将 Swift Language Version 改为 Swift 5。

接着，打开 pluginName.podspec 并将 Swift 版本更新至 5.1：

-s.swift_version = '4.2'
+s.swift_version = '5.1'

Web​

注册插件​

registerWebPlugin(MyPlugin) 函数已被弃用。我们建议使用新的 registerPlugin 函数，并如下所示延迟加载 Web（以及可选的 Electron）插件。

import { registerPlugin } from '@capacitor/core';
import type { CoolPlugin } from './definitions';

const MyCoolPlugin = registerPlugin<CoolPlugin>('MyCoolPlugin', {
  web: () => import('./web').then(m => new m.MyCoolPluginWeb()),
  // electron: () => ("./electron").then(m => new m.MyCoolPluginElectron())
});

export * from './definitions';
export { MyCoolPlugin };

将 TypeScript 输出目标设置为 es2017​

如果你使用 TypeScript 开发 Web 插件，我们建议在 tsconfig.json 中将输出目标设置为 es2017。

评估错误处理​

我们现在建议插件开发者利用 Capacitor 3 中的新错误码：

  • Unavailable：表示当前无法使用该功能
  • Unimplemented：表示该功能无法或不会实现，或可能在未来实现

了解更多关于 Web、iOS 和 Android 错误处理的信息。

采用新的权限 API​

在 3.0 版本之前，通常期望插件在使用功能前自动请求权限。例如，Geolocation 插件会在首次请求用户位置时自动请求权限，然后根据权限授予或拒绝的情况继续执行。

Capacitor 3 的一个目标是让应用开发者能够在任何时候请求或检查权限，并控制用户提示的显示方式和时机。这通过允许应用以多种方式响应用户的选择，为用户体验提供了更大的灵活性。

继续自动请求权限完全没有问题，但也鼓励你采用新的权限模式，以便为应用开发者提供对权限的控制。

了解如何在你的插件中实现权限 API ›

Contents

编辑此页