跳到主要内容
版本：v8

将插件升级至 Capacitor 3.0

针对升级到 Capacitor 3 的插件，我们提供以下必要调整与优化建议。

核心 API 规划​

当前核心团队调整 Capacitor 内部实现时，容易对插件产生连锁影响。由于 Capacitor 2 中 iOS 和 Android 的大部分类与方法都是公开的，我们注意到存在非预期的内部 API 使用情况。

在 Capacitor 3 开发过程中，我们将评估该问题并建立官方公共插件 API。

Android 适配​

使用新版 @CapacitorPlugin 注解​

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

主要变更：

  • 保留 name 属性
  • 移除 requestCodes 和 permissionRequestCode 属性
  • 将 permissions 替换为包含 manifest 字符串列表的 @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，移除了手动定义的请求码。现在应使用注解声明回调方法：

-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 解析带透明通道的十六进制颜色时为 ARGB 格式，而 iOS 和 Web 使用 RGBA 格式。跨平台共享颜色时请使用新版 WebColor 工具类：

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

不含透明通道的颜色两种方法解析结果相同。

更新默认编译配置​

修改 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 优化了对象引用关系以修复内存泄漏，现在插件对上层对象的引用变为 weak（Swift 中表现为可选类型）。最常见的场景是访问 bridge 属性：

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

返回值也变为可选类型，请参考 Swift 官方文档安全解包可选值。

Bridge API 变更​

除了引用类型变更外，Bridge API 也进行了规范化改造（通过协议暴露）。Xcode 通常会自动提示新接口名称：

Xcode 自动修正建议

CAPPluginCall 参数处理​

参数访问方法优化要点：

  • 移除 get() 方法，直接访问 options 字典
  • 弃用 hasOption，改用类型化访问器
  • 带默认值的访问器现在返回非可选类型
  • 日期和空值处理逻辑微调，详见文档
  • Objective-C 便捷方法需要单独导入头文件

PluginCall 变更​

使用 resolve() 和 reject()​

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

无参 resolve() 行为变更​

现在无参数调用会返回 JavaScript 的 undefined（原返回空对象），与 Promise.resolve() 行为一致。

调用保持机制​

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

设置 iOS 最低版本为 12.0​

需修改以下位置：

  1. Xcode 项目设置中的 Deployment Target
  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 编译版本
  2. podspec 文件：
-s.swift_version = '4.2'
+s.swift_version = '5.1'

Web 适配​

插件注册新规范​

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

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())
});

设置 TypeScript 输出目标​

建议在 tsconfig.json 中设置：

{
  "compilerOptions": {
    "target": "es2017"
  }
}

错误处理优化​

推荐使用新的错误类型码：

  • Unavailable：当前功能不可用
  • Unimplemented：功能未实现/不支持

各平台错误处理指南：

采用全新权限API​

3.0 之前插件通常自动请求权限。Capacitor 3 允许应用开发者自主控制权限请求时机，提供更灵活的用户体验。

虽然仍可自动请求权限，但建议适配新权限模式：权限 API 实现指南

Contents

编辑此页