将插件中的 Capacitor 更新到 3.0
对于正在更新到 Capacitor 3 的插件，有几个必需的和推荐的更改。
规划核心 API
目前，核心团队很难在不影响插件的情况下更改 Capacitor 的内部结构。因为 Capacitor 2 中的大多数类和方法在 iOS 和 Android 上都是公共的，我们观察到了一些我们认为属于内部的 Capacitor API 的不当使用。
在 Capacitor 3 开发期间，我们将评估此问题并创建插件的官方公共 API，在此处记录。
Android
使用新的 @CapacitorPlugin 注解
@NativePlugin 注解已弃用。我们现在建议使用新的 @CapacitorPlugin 注解，它将允许使用新的 permissions API。
name 属性相同。requestCodes 和 permissionRequestCode 属性已被移除。permissions 属性将需要替换为 @Permission 注解列表，每个注解包含一个清单字符串列表及其对应的 alias，在您的插件中实现新的 permissions API 之前，您可以暂时省略 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 注解提供回调方法，而不是提供请求码并重写 handleOnActivityResult 或 handleRequestPermissionsResult。这些回调可以在启动新 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 中这意味着它们是可选的（optional）。您最可能在访问 bridge 时遇到此更改，但它也适用于其他属性，如 webView。在 bridge 上调用方法相对不变，只是现在需要可选链：
-bridge.presentVC(myViewController, animated: true, completion: nil)
+bridge?.presentVC(myViewController, animated: true, completion: nil)
此更改的最大影响是来自 bridge 的所有返回值也将是 optional。安全地处理和展开 optionals 可能需要额外的步骤。
if bridge?.isSimEnvironment {
// 坏：无法编译。布尔值是 optional（因为 `bridge` 是 optional）
// 必须解包后才能评估。
}
if bridge?.isSimEnvironment == true {
// 中性：与 optional 进行显式比较对于布尔值有效，但
// 可能不适用于所有数据类型。
}
if let isSim = bridge?.isSimEnvironment, isSim {
// 好：使用可选绑定在检查值之前解包 optional。
}
Bridge 更改
除了引用从 strong 变为 weak 之外，bridge 本身的 API 也已更新（现在通过更正式的协议暴露）。许多属性和方法已重命名，但在可能的情况下通过保留和弃用旧接口来向后支持。在大多数情况下，Xcode 将能够自动建议新的替代方案。您应该迁移任何现有代码，以便您的插件可以在没有编译器警告的情况下构建。
CAPPluginCall 参数
Capacitor 在 CAPPluginCall 上包含一组便捷方法（getString、getDate 等）来访问从 JavaScript 传递给插件方法的数据。这些已在 Capacitor 3 中更新。
get()已被移除。如果您想直接访问参数，请读取options字典。hasOption已弃用。请使用类型化的访问器之一来检查值 。- 任何接受默认值的访问器现在需要非 optional 的默认值，但返回非 optional 的结果。这可能会改变局部变量的可选性，但应该减少强制解包的使用，这在 Swift 中是一种反模式。
- 关于日期和空值的行为略有更改，并有了更好的文档说明。在此处查找更多信息。
- Obj-C 便捷访问器已被拆分，以避免与 Swift 实现冲突。如果您在 Obj-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 项目和插件 target 执行以下操作：打开 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 target 中的 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 的错误处理。
采用新的 Permissions API
在 3.0 之前，预期权限会在功能使用前由插件自动请求。例如，Geolocation 插件会在首次请求用户位置时自动请求权限，然后根据权限被授予或拒绝继续适当的操作。
Capacitor 3 的一个目标是让应用开发者能够随时请求或检查权限，并控制如何以及何时向用户显示提示。这通过允许应用以各种方式响应用 户的选择，提供了更大的用户体验灵活性。
继续自动请求权限完全没有问题，但也鼓励您采用新的权限模式，以便给予应用开发者对权限的控制。