文档

Unity 引擎

Unity 引擎

json Serialization

使用 JsonUtility 类 Unity 对象转换为 json Format或从 JSON 格式转换。
阅读时间6 分钟最后更新于 5 天前

使用 JsonUtility 类可将 Unity 对象转换为 json Format 格式或从该格式转换。例如,您可以使用 json Serialization与 Web Services交互,或轻松地将数据打包和解压缩为基于文本的Format。
json Serialization 使用“结构化”json 的概念:创建类或结构来描述要在 json 数据存储的变量。例如:
[可Serializable化]public class MyClass{ public int level; public float timeElapsed; public string playerName;}
这将定义一个包含三个变量(关卡、timeElapsed 和 playerName)的普通 C# 类,并使用
Serializable
属性对其进行标记,以便与 json 序列化程序配合使用。要创建类的实例,可以使用如下所示的内容:
MyClass myObject = new MyClass();myObject.level = 1;myObject.timeElapsed = 47.5f;myObject.playerName = "Dr Charles Francis";
然后使用 JsonUtility.ToJson 方法将其 Serialize(转换)为 json Format:
string json = JsonUtility.ToJson(myObject);// json now contains: '{"level":1,"timeElapsed":47.5,"playerName":"Dr Charles Francis"}'
要将 json 转换回 Object,请使用 JsonUtility.FromJson:
myObject = JsonUtility.FromJson<MyClass>(json);
这将创建新的
MyClass
实例并使用 json 数据设置其 ON 值。如果 json 数据包含未映射到
MyClass
中的字段的值,则序列化程序会忽略这些值。如果 json 数据缺失
MyClass
中字段的值,则序列化程序会在返回的对象中保留这些字段的构造值。

使用 JSON 覆盖对象

还可以在现有Object上Deserialize json 数据,这会覆盖Any现有数据:
JsonUtility.FromJsonOverwrite(json, myObject);
如果 json 数据不包含某个Field的值,则序列化程序不会更Change该Field的值。此方法允许重用以前创建的对象,从而将分配保持在最低限度。它还允许您通过故意用仅包含一小部分字段的 json 覆盖对象来“修补”对象。
警告
json Serializer API 支持 MonoBehaviour 和 ScriptableObject 子类以及普通 structs 和类。但是,当将 json 反序列化为
MonoBehaviour
或
ScriptableObject
的子类时,必须使用 FromJsonOverwrite 方法。如果尝试使用 FromJson,Unity 会抛出异常,因为不支持此行为。

支持的类型

json Serializer API 支持具有
[Serializable]
属性的任何
MonoBehaviour
子类、
ScriptableObject
子类或普通类或结构。将对Objectject标准 Unity 序列化程序进行处理When,Apply的Rules和限制与在 Inspector 中相同:Unity 仅序列化字段;不支持
Dictionary<>
等类型。
Unity 不Support将Other类型直接传递给 API,例如原始类型或数组。如果需要转换,请将它们换行为某种排序的
class
或
struct
。
仅在 Editor 中,有一个并行 API EditorJsonUtility,允许将派生自 UnityEngine.Object 的任何对象与 json 进行 Serialize。这会产生包含与 Object 的 YAML 表示相同的数据的 json。
JsonUtility 和 EditorJsonUtility 是用于使用 Unity Serialization Rules 将对象序列化到 json 的字符串 Format 或从 json 的字符串格式序列化的 Utility 类。如果需要通过代码操作 json 数据或Serialize Unity 序Serialization不Support的数据结构,可以使用General .NET json 库作为 JsonUtility API 的配套工具。

性能

基准测试表明,JsonUtility 比流行的 .NET json 解决方案快得多,尽管这类在某些情况下提供的功能较少。
垃圾Collection GC 的Memory Usage量至少为:
  • ToJson 仅为返回的字符串分配 GC 内存。
  • FromJson 仅为返回的对象以及所需的 Any 子对象分配 GC 内存(例如,如果 Deserialize 包含 Array 的对象,则 Unity 为 Array 分配 GC 内存)。
  • FromJsonOverwrite 仅在必要时为写入字段(例如,字符串和数组)分配 GC 内存。这意味着,如果 json 覆盖的所有字段都是值类型,Unity 根本不会分配任何 GC 内存。
可从背景线程使用 JsonUtility API。但是,与Any多线程代代码一样,请注意不要ON另一个线程正在序列化或反序列化某个对象时访问或更改该Object。

控制 ToJson() 的输出

ToJson 方法支持漂亮打印 json 输出。默认情况下为 OFF,但您可以通过将
true
作为第二个参数传递来启用它。
可使用
[NonSerialized]
属性从输出中省略字段。

使用类型未知的 FromJson()

如果时间不知道Object的类型,请将 json Deserialize列化为包含“公共”字段的类或结构,然后使用这些字段的值来确定所需的实际类型。然后第二时间Deserialize为该类型。