跳到主要内容
版本：v5

Capacitor 数据类型

在 Capacitor 中，Web 运行时与原生环境之间传输的数据需要经过序列化和反序列化，以便以各语言的原生形式存储。支持的数据类型是那些可以用 JSON 表示的类型，例如数字、字符串、布尔值、数组和对象（或字典或键值存储）。

iOS​

虽然 Swift 是 iOS 上的首选语言，但它与 Objective-C（系统框架基于此构建）可以互操作，因此该平台支持三种语言的交集。大多数数据类型会按预期转换，但有些情况可能需要特别注意。

空值​

Objective-C 不支持在集合（如数组、字典或集合）中存储空值。相反，它使用一个特殊的占位对象 NSNull 来表示空值。相比之下，Swift 使用 可选类型（Optionals） 来描述可能为 null 的值。Swift 可以处理 NSNull 值，但 Objective-C 无法处理可选类型（尽管在某些情况下，运行时会自动将可选类型映射为基础值或 NSNull）。无论你使用哪种语言，这些 NSNull 对象都可能出现。

例如，考虑以下传递给 Capacitor 插件调用的对象：

{ 'foo': null, 'bar': [1, 2, null, 4]}

字典​

CAPPluginCall 将此数据存储为其 options 属性，但提供了多种方便的操作访问器。这些访问器会将值转换为预期的类型，因此 NSNull 值会被过滤掉。

if let value = call.getString("foo") {
    // 良好：`value` 为 nil，因此此代码块不会执行
}

但是，直接访问存储属性可能会返回一个 NSNull 对象。

if call.options["foo"] != nil {
    // 不佳：该键返回了一个真值 `NSNull` 对象，因此此代码块会执行
}

不建议依赖键的存在来传达含义。始终对相应的值进行类型检查以进行评估。

数组​

由于访问数组通常需要为整个集合指定类型，因此必须考虑它是包含单一类型还是可能是异构的。

if let values = call.getArray("bar") {
    // 中性：数组中的所有对象都是有效的，因此此代码块会执行，但每个值都需要单独指定类型
}
if let values = call.getArray("bar", Int?) {
    // 不佳：数组混合了 `Int` 和 `NSNull`，无法转换为 `Int?`，因此此代码块不会执行
}

为了帮助处理这种行为，Capacitor 包含了一个便利的扩展，可以将包含 NSNull 值的数组映射为可选类型数组。它适用于 JSValue 协议，该协议表示可以在环境之间桥接的所有有效类型，但可以转换为特定的子类型。

if let values = call.getArray("bar").capacitor.replacingNullValues() as? [Int?] {
    // 良好：`values` 现在已转换为 `Int?`，索引 2 处为 `nil`
}

日期​

在大多数情况下，日期应该可以按预期工作。从 JavaScript 发送的任何 Date 对象，或从插件返回的 Date 或 NSDate 对象，都将被序列化为 ISO 8601 字符串。

但是，如果需要，可以更改此行为的一部分。从 Web 运行时传输到原生 iOS 代码的数据与反向传输的数据使用不同的机制。WKWebView 会自动将 JavaScript Date 对象转换为原生 Date 对象。为了与其他平台保持一致并满足开发者的期望，Capacitor 从 3.0 开始会在将这些对象传递给插件之前对它们进行序列化。如果你想选择退出此行为，请在插件上设置 shouldStringifyDatesInCalls 属性。

override func load() {
    shouldStringifyDatesInCalls = false
}

CAPPluginCall 的便利访问器 getDate 将处理这两种数据类型并返回一个 Date 对象。

从原生代码传输到 Web 视图的数据将被序列化为 JSON。由于 JSON 没有正式定义日期，在 3.0 之前，在插件的结果中包含 Date 对象会引发异常。但现在，Capacitor 将自动按照惯例将任何 Date 对象序列化为字符串。如果你的插件需要以不同方式处理日期，请先将它们序列化为其他受支持的 JSON 类型。

Contents

编辑此页