跳到主要内容
版本：v3

将插件中的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注解列表，每个注解包含manifest字符串数组及对应的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")
+    })
 )

Android请求码处理​

Capacitor 3.0采用AndroidX Activity Result API，移除了手动定义的请求码。插件应使用@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) {
+    // 处理返回结果
+}

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

Android解析带alpha通道的十六进制颜色字符串为_ARGB_格式，而iOS和Web端解析为_RGBA_格式。如需跨平台共享带透明通道的颜色，请使用新的WebColor工具类，其解析规则与Web端一致。

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

调整默认SDK版本​

在android/build.gradle中将compileSdkVersion和targetSdkVersion默认值改为30：

android {
-   compileSdkVersion 29
+   compileSdkVersion 30
    defaultConfig {
        minSdkVersion 21
-       targetSdkVersion 29
+       targetSdkVersion 30
    }
}

iOS平台​

弱引用改造​

Capacitor 3改进了对象关系以修复内存泄漏。现在插件对层级较高对象的引用变为weak（Swift中表现为可选类型），主要影响对bridge的访问：

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

返回值也变为可选类型，需安全解包处理。

桥接接口变更​

除了引用类型变化外，桥接接口也进行了规范化改造（通过协议暴露）。多数属性和方法已重命名，但保留了旧接口的兼容支持。建议迁移代码以消除编译警告。

CAPPluginCall参数访问​

参数访问方法进行了以下改进：

  • 移除get()方法，直接访问options字典
  • 弃用hasOption，推荐使用类型化访问器
  • 带默认值的访问器现在要求非可选默认值
  • 日期和空值处理行为微调
  • Objective-C工具方法需单独导入

PluginCall & CAPPluginCall变更​

使用resolve()和reject()​

推荐使用这两个方法替代已弃用的success()/error()，更符合Promise风格。

无参resolve()返回undefined​

与JavaScript的Promise.resolve()行为一致，3.0版本起空解析将返回undefined而非空对象。

调用保存机制​

弃用save()方法，新增keepAlive属性。详见文档。

设置iOS最低版本为12.0​

需在以下位置更新部署目标：

  1. Xcode项目的Build Settings中设置iOS Deployment Target为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)，推荐使用新的registerPlugin函数实现懒加载：

const MyCoolPlugin = registerPlugin<CoolPlugin>('MyCoolPlugin', {
  web: () => import('./web').then(m => new m.MyCoolPluginWeb()),
  // 可选Electron实现
});

设置TypeScript输出目标​

建议在tsconfig.json中将编译目标设为es2017。

错误处理优化​

推荐使用新的错误类型：

  • Unavailable：功能当前不可用
  • Unimplemented：功能未实现或未来可能实现

各平台错误处理指南：Web、iOS、Android

采用新权限API​

3.0版本前，插件通常在使用功能时自动请求权限。新版本允许应用开发者自主控制权限请求时机，建议适配新权限模式以提升用户体验。

查看权限API实现指南 ›

Contents

编辑此页