跳到主要内容
版本：v6

将插件升级至Capacitor 3.0

以下是插件升级到Capacitor 3所需的核心变更和建议调整。

核心API规划​

当前核心团队在修改Capacitor内部实现时，可能影响插件功能。由于Capacitor 2中iOS和Android的大部分类与方法都是公开的，我们注意到部分内部API被不当使用。

在Capacitor 3开发过程中，我们将评估这一问题并建立官方公共API，相关文档将发布于此处。

Android平台适配​

使用新版@CapacitorPlugin注解​

@NativePlugin注解已弃用，推荐使用新@CapacitorPlugin注解以支持全新权限API。

主要变更点：

  • name属性保持不变
  • 移除requestCodes和permissionRequestCode属性
  • permissions属性替换为@Permission注解列表（可暂不设置alias）
-@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，移除了手动定义请求码的方式。现在应该使用@ActivityCallback或@PermissionCallback注解声明回调方法。

-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("用户取消操作");
+    } else {
+        Intent data = result.getData();
+        // 处理返回数据
+        call.resolve("操作成功");
+    }
+}

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

Android解析带透明通道的十六进制颜色时为_ARGB_格式，而iOS和Web端使用_RGBA_格式。跨平台共享颜色时请使用新版WebColor工具类。

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

若颜色不包含透明通道，两个方法返回值相同。

调整默认SDK版本​

在android/build.gradle中更新默认值：

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中对象关系调整为弱引用（Swift中表现为可选类型），主要影响：

  • 访问bridge等高层级对象时需使用可选链
  • 所有桥接返回值都变为可选类型

推荐处理方式：

if bridge?.isSimEnvironment == true {
     // 显式比较方式
}

if let isSim = bridge?.isSimEnvironment, isSim {
     // 更安全的可选绑定方式
}

桥接API变更​

桥接接口已正式协议化，多数属性/方法已重命名（旧接口暂时保留但会标记为废弃）。Xcode通常能自动提示新名称：

Xcode自动修正提示

CAPPluginCall参数处理​

参数便捷方法更新要点：

  • 移除get()方法，可直接访问options字典
  • 弃用hasOption，推荐使用类型化访问器
  • 带默认值的访问器现在要求非可选默认值
  • 日期和null值处理行为微调（详见）
  • Objective-C辅助方法需单独导入：#import <Capacitor/CAPBridgedJSTypes.h>

PluginCall & CAPPluginCall变更​

采用resolve()/reject()​

推荐使用resolve()和reject()替代已弃用的success()/error()，更符合Promise规范。

无参resolve()现在返回undefined​

此前返回空对象的行为已调整为与JavaScript的Promise.resolve()一致。

调用保持机制​

弃用save()方法，新增keepAlive属性。详见调用保持规范。

设置iOS最低版本为12.0​

需三处调整：

  1. Xcode项目中设置Deployment Target为iOS 12.0
  2. 更新Podfile：
-platform :ios, '11.0'
+platform :ios, '12.0'
  1. 修改podspec文件：
-s.ios.deployment_target  = '11.0'
+s.ios.deployment_target  = '12.0'

Swift版本升级至5​

  1. Xcode中设置Swift Language Version为Swift 5
  2. 更新podspec：
-s.swift_version = '4.2'
+s.swift_version = '5.1'

Web端调整​

插件注册新规范​

弃用registerWebPlugin(MyPlugin)，推荐使用新版惰性加载方式：

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

设置TypeScript输出目标​

建议在tsconfig.json中将target设为es2017。

错误处理优化​

推荐使用新版错误码：

  • Unavailable：功能当前不可用
  • Unimplemented：功能未实现/不计划实现

各平台错误处理指南：

采用全新权限API​

3.0之前插件通常在使用功能时自动请求权限。Capacitor 3赋予应用开发者更灵活的权限控制能力，建议适配新权限模式：

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

Contents

编辑此页