Rect Native bridging 源码分析--Dynamic.h

源码目录：

packages/react-native/ReactCommon/react/bridging/Dynamic.h

源码：

/*
 * Copyright (c) Meta Platforms, Inc. and affiliates.
 *
 * This source code is licensed under the MIT license found in the
 * LICENSE file in the root directory of this source tree.
 */

#pragma once

#include <folly/dynamic.h>
#include <jsi/JSIDynamic.h>

namespace facebook::react {

template <>
struct Bridging<folly::dynamic> {
  static folly::dynamic fromJs(jsi::Runtime &rt, const jsi::Value &value)
  {
    return jsi::dynamicFromValue(rt, value);
  }

  static jsi::Value toJs(jsi::Runtime &rt, const folly::dynamic &value)
  {
    return jsi::valueFromDynamic(rt, value);
  }
};

} // namespace facebook::react

概述

该头文件隶属于 facebook::react 命名空间，是 React Native JSI（JavaScript Interface）桥接体系的重要组成部分，专门提供 C++ folly::dynamic 类型与 JSI 核心类型（jsi::Value） 之间的双向桥接能力。folly::dynamic 是 Folly 库提供的动态类型（类似 JSON 数据结构，支持动态键值对、数组等），该桥接实现打通了 C++ 动态类型与 JS 动态类型的交互通道，支撑 React Native 中复杂动态数据的跨语言传递。

核心命名空间

facebook::react

所有桥接相关结构体与方法均位于该顶层命名空间下，与 React 框架其他桥接组件（如基本类型、集合类型桥接）保持统一命名规范。

核心桥接结构体：Bridging<folly::dynamic> 模板特化

模板定义

template <>
struct Bridging<folly::dynamic>;

• 类型：Bridging 通用模板的显式特化 （针对 folly::dynamic 动态类型）
• 功能：为 C++ folly::dynamic 类型提供专属的 JS 双向转换实现，遵循 React 桥接体系的统一接口规范
• 适用场景：
  1. React Native 中 C++ 层与 JS 层传递复杂动态数据（如不确定结构的配置信息、接口返回数据）
  2. 需要兼容 JSON 格式数据的跨语言交互场景
  3. 替代固定类型集合，处理动态增减字段 / 元素的业务场景

核心静态方法

该结构体提供两个核心静态方法，分别实现 folly::dynamic 与 jsi::Value 的双向转换，方法无额外运行时开销，支持直接调用。

1. fromJs 方法：JS 动态类型 → C++ folly::dynamic 类型

方法签名

static folly::dynamic fromJs(jsi::Runtime &rt, const jsi::Value &value)

功能描述

将 JSI 层封装的 JS 动态值（jsi::Value，可对应 JS 的对象、数组、字符串等所有基本类型）转换为 C++ folly::dynamic 动态类型，实现 JS 动态数据到 C++ 层的无缝迁移。

参数说明

参数名	类型	必选	说明
rt	jsi::Runtime &	是	JSI 运行时环境引用，提供 JS 层执行上下文，是 JSI 类型转换的必备依赖
value	const jsi::Value &	是	常量引用，封装了 JS 层传递的动态数据的 JSI 容器对象，支持 JS 所有原生类型

返回值

• 类型：folly::dynamic
• 说明：返回与 JS 动态数据完全对应的 C++ 动态对象，保留原始数据的结构与值（如 JS 对象 → folly::dynamic 键值对、JS 数组 → folly::dynamic 数组、JS 字符串 → folly::dynamic 字符串等）

实现细节

直接调用 JSI 库的内置工具函数 jsi::dynamicFromValue(rt, value)，该函数已封装了 JS 类型到 folly::dynamic 的完整转换逻辑，无需额外自定义处理，兼顾简洁性与可靠性。

2. toJs 方法：C++ folly::dynamic 类型 → JS 动态类型

方法签名

static jsi::Value toJs(jsi::Runtime &rt, const folly::dynamic &value)

功能描述

将 C++ folly::dynamic 动态对象转换为 JS 层可识别的 jsi::Value 类型，实现 C++ 动态数据到 JS 层的传递，支持 folly::dynamic 所有内置类型的映射。

参数说明

参数名	类型	必选	说明
rt	jsi::Runtime &	是	JSI 运行时环境引用，用于创建 JS 原生对象 / 数组等类型
value	const folly::dynamic &	是	常量引用，待转换的 C++ folly::dynamic 动态对象，支持任意合法结构的 folly::dynamic 数据

返回值

• 类型：jsi::Value
• 说明：返回与 folly::dynamic 完全对应的 JSI 动态值，可在 JS 层直接解析为原生 JS 类型（如 folly::dynamic 键值对 → JS 对象、folly::dynamic 数组 → JS 数组等）

实现细节

直接调用 JSI 库的内置工具函数 jsi::valueFromDynamic(rt, value)，该函数封装了 folly::dynamic 到 JS 类型的完整映射逻辑，无需手动处理类型分支，转换效率高且兼容性强。

核心特性总结

1. 无缝映射 ：实现 folly::dynamic 与 jsi::Value 的完全双向对应，保留所有数据结构与值，无数据丢失或类型歧义（如 JSON 结构数据可在 C++ 与 JS 之间自由传递）。
2. 轻量高效：依赖 JSI 内置工具函数完成转换，无额外内存分配与复杂逻辑，运行时开销趋近于零，满足高性能跨语言交互需求。
3. 接口统一 ：严格遵循 React 桥接体系的 fromJs（JS→C++）/toJs（C++→JS）统一接口规范，与 bool、std::vector 等其他类型的桥接实现保持一致，降低上层使用成本。
4. 动态兼容 ：针对 folly::dynamic 动态类型的特性，无需提前定义数据结构，支持动态增减字段 / 元素，适配不确定数据结构的业务场景。
5. 依赖复用：复用 JSI 与 Folly 库的成熟工具函数，避免重复造轮子，提升代码可靠性与可维护性。

依赖说明

该桥接实现依赖两个核心库，使用时需确保引入对应头文件与链接库：

1. Folly 库 ：依赖 folly/dynamic.h 头文件，提供 folly::dynamic 动态类型定义。
2. JSI 库 ：依赖 jsi/JSIDynamic.h 头文件，提供 jsi::dynamicFromValue 与 jsi::valueFromDynamic 转换工具函数，以及 jsi::Runtime、jsi::Value 核心类型。

注意事项

1. 该实现是 Bridging 模板的显式特化，仅适用于 folly::dynamic 类型，无法复用至其他静态类型或自定义动态类型。
2. 转换过程依赖 JSI 运行时环境（jsi::Runtime &rt），不可省略该参数，否则无法完成跨语言类型映射。
3. 仅支持 folly::dynamic 与 jsi::Value 之间的转换，若需转换为其他 JSI 类型（如 jsi::Object、jsi::Array），可在转换后通过 jsi::Value 的原生方法进一步解析。
4. 需确保 folly::dynamic 对象的合法性，非法结构的 folly::dynamic 可能导致转换失败或运行时异常。