Skip to main content

VRC JSON

数据字典和数据列表包含与 JSON 之间进行转换的函数。数据列表相当于 JSON 数组，JSON 对象相当于具有字符串键的数据字典。

有关 JSON 模式本身的更多详细信息，请参阅 JSON 文档。此页面中的所有内容都与此 JSON 模式的特定实现有关。

JSON 函数​

函数输入输出结果
VRCJson.TryDeserializeFromJsonString inputsuccess bool, DataToken result从 JSON 字符串创建 DataList 或 DataDictionary。如果成功，返回 true 且结果令牌将是 DataDictionary 或 DataList。如果不成功，返回 false 并在结果令牌中放入解释问题的错误。
VRCJson.TrySerializeToJsonDataToken input, JsonExportTypesuccess bool, DataToken result尝试将 DataDictionary 或 DataList 转换为 JSON 字符串输出。如果成功，返回 true 且结果令牌将是包含最终 Json 的字符串。如果不成功，返回 false 并在结果令牌中放入解释问题的错误。
  • 注意，在 Udon Graph 中，所有类名开头的"VRC"被移除，因此你需要搜索"Json"来找到这些函数。
  • 在 UdonSharp 中，这些类位于 VRC.SDK3.Data 命名空间中。

支持的类型和值​

JSON 是一个小型、简单且严格的规范。DataList 和 DataDictionary 能够支持更广泛的配置，这意味着从 Data 容器转到 JSON 时可能会面临一些限制。确保你了解这些限制，并在打算使用 JSON 的情况下避免使用这些配置。

JSON 不支持对象引用 Data Token。 如果在尝试序列化为 JSON 时，Data 容器中有任何对象引用，TrySerializeToJson 函数将返回 false，并带有 DataError.TypeUnsupported。

JSON 仅支持字符串键的字典。 如果在尝试序列化为 JSON 时，DataDictionary 中有任何非字符串的键，TrySerializeToJson 函数将返回 false，并带有 DataError.TypeUnsupported。

JSON 不支持 NaN 或 Infinity。 如果有任何包含 NaN 或 Infinity 的 float 或 double，TrySerializeToJson 函数将返回 false，并带有 DataError.ValueUnsupported。

JSON 仅支持 Dictionary 或 List 作为根。 如果你使用没有任何子项的简单值 DataToken，TrySerializeToJson 函数将返回 false，并带有 DataError.TypeUnsupported。

JSON 仅支持一种数字类型。 它不区分所有不同的类型。因此，从 JSON 反序列化将以 Double 格式存储所有数字。如果你的 Data Token 包含其他类型的数字，如 int、byte 或 float，它们可以序列化为 JSON，但如果你将相同的 JSON 反序列化回 Data 容器，你会发现它们现在是 Double。

从 JSON 反序列化​

VRCJson.TryDeserializeFromJson 是当你想要从 Json 转到 Data 容器时应使用的函数。建议将其用作 if 或 branch 的条件，以便你可以选择失败时和成功时的处理方式。

如果 TryDeserializeFromJson 返回 true，则表示已成功将你的 Json 字符串转换为 DataList 或 DataDictionary。然后应对结果进行类型检查，以确定每种情况的处理方式。

如果返回 false，则提供的字符串不是有效的 JSON。你得到的 DataToken 将是一个 DataError，如果在其上运行 DataToken.ToString，它将同时给出错误和更详细解释具体错误的字符串。

出于性能原因，VRCJSON 不会立即解析所有内容。相反，它首先只解析 JSON 的顶层。如果顶层有效，但嵌套结构中存在无效 JSON，初始的 TryDeserializeFromJson 可能返回 true。之后，如果你使用 TryGetValue 从无效的内容中提取值，它将返回 false 并给出 DataError.UnableToParse。

从 JSON 反序列化
if (VRCJson.TryDeserializeFromJson(json, out DataToken result))
{
    // 反序列化成功！让我们看看我们得到了什么。
    if (result.TokenType == TokenType.DataDictionary)
    {
        Debug.Log($"成功反序列化为字典，有 {result.DataDictionary.Count} 个项目。");
    }
    else if (result.TokenType == TokenType.DataList)
    {
        Debug.Log($"成功反序列化为列表，有 {result.DataList.Count} 个项目。");
    }
    else 
    {
        // 这不可能。如果 TryDeserializeFromJson 返回 true，则*必须*是字典或列表。
    }
} else {
    // 反序列化失败。让我们看看错误是什么。
    Debug.Log($"反序列化 json {json} 失败 - {result.ToString()}");
}

序列化为 JSON​

VRCJson.TrySerializeToJson 是当你想要从 Data 容器转到 Json 时应使用的函数。建议将其用作 if 或 branch 的条件，以便你可以选择失败时和成功时的处理方式。

如果 TrySerializeToJson 返回 true，则表示已成功将 DataList 或 DataDictionary 转换为 Json 字符串，你可以安全地从结果令牌中提取字符串。

序列化为 JSON
if (VRCJson.TrySerializeToJson(dictionary, JsonExportType.Beautify, out DataToken json))
{
    // 序列化成功！我们可以立即从令牌中获取字符串并对其进行处理。
    Debug.Log($"成功序列化为 json: {json.String}");
} 
else 
{
    // 由于某种原因序列化失败，对结果运行 ToString 应该告诉我们原因。
    Debug.Log(json.ToString());
}

JsonExportType​

序列化为 JSON 时，你可以选择所需的 JsonExportType。如果你想要人类可读的内容，Beautify 更好。如果你想要紧凑的内容以便通过网络发送，Minify 更好。

  • Beautify：将每个元素展开到新行，每层深度添加一个制表符。
  • Minify：将所有内容保持在一行中，并最小化空白。