【教程】Unity 官配 JsonUtility 使用指南

开发平台：Unity 2020
编程平台：Visual Studio 2020
编程语言：CSharp

一、前言

处理 Json 数据，在目前多元化的 Json 处理插件上显得简单易用。而 JsonUtility 作为 Unity 官方坐镇的 Json 数据处理软件。必然有其存在的原因。

二、你需要知道 JsonUtility 支持的可序列化数据类型

支持数字数据类型：int、float、double、decimal、long
包括 uint、float2x4、double2 等数据类型
支持字符数据类型：char、string
【特别】支持 Vector 数据类型
包括 Vetor2、Vector3、Vector2x2 等数据类型
【特别】支持 Quateration 四元数数据类型
【特别】支持 public 访问类型的类、字段
【特别】支持 SerializeField 特性指引的类、字段

三、JsonUtility 类方法说明

toJson(object target, bool prettyPrint)
- object：对象转换为 Json 数据文本
- prettyPrint：决定最终的 Json 数据文本是否是一个格式化后的数据文本。
  即是否使用 Json 文本的 Format 化。
FromJson(string text)
1. 将 Json 数据文本转存至类中 public 或附有 SerializeField 特性的字段上赋值。
2. 使用时无需管理值具体分配。其将基于字段命名自行匹配并赋值。
FromJsonOverwrite(string text, object objectToOverwrite)

四、JsonUtlity 相关特性注意项

特性01：仅支持 MonoBehaviour / ScriptableObject 继承类的序列化

不同于程序界流行的其他 Json 数据处理插件。JsonUitlity 是 Unity 专用于处理 MonoBeheviour / ScriptableObject 的数据处理工具。对于非限定继承对象的数据处理，例如父类继承 MonoBehaviour，子类继承父类，仍然可序列化。

特性02：仅支持 [Serializable] 的普通类与结构体

[Serializable]
public class JsonData
{
    
    
	public string JsonName;
	public List<JsonItem> JsonContent;
	public string ResponseCode;
}

[Serializable]
public struct JsonItem {
    
     public string DataName; public int DataValue; }

特性 02：仅序列化 public 或 [SerializeField] 标签的字段

对于同 public 访问类型的属性，例如 public string Description { get; set; } = "Hello" 无法序列处理为 Json 数据格式。

public class ChararcterInfo : MonoBehaviour
{
    
    
	public string Name = "Json Test";
	public int Age = 18;
	public Vector3 CurrentPosition = Vector3.zero;
	public Vector3 CurrentEnlerAngle = Vector3.zero;
	public Vector3 CurrentSize = Vector3.one;


	public void Start() => Debug.Log(JsonUtlity.toJson(this));
}

解析后

{"Name":"Json Test","Age":18,"Position":{"x":0.0,"y":0.0,"z":0.0},"EulerAngle":{"x":0.0,"y":0.0,"z":0.0},"Size":{"x":1.0,"y":1.0,"z":1.0}}

同理，使用 [NoSerialized] 特性将忽略此字段的 Json 序列化流程。

2023/1/3 存疑点：

属性 public 字段 private 是否会参与 Json 序列过程。仅字段支持
属性 private （+ SerilizeFiled）字段 public 是否会参与 Json 序列过程。参与

特性03：支持 List、Array 数据类型，但不支持 Dictionary、Query、Stack 等集合

public class JsonBaseData : MonoBehaviour
{
    
    
	public int[] DataIntArray;
	public List<int> DataIntList;
	public Dictionary<int, int> DataIntDic;
	public Query<int> DataIntQue;
}

逐一使用上述行进行 JsonUtility.ToJson(this) 转换至 Json 数据格式。可以发现 Dictonary、Query、Stack 均无法被序列化。（尚未对集合内其他数据类型进行测试，预计均无法被序列化）

注意：类型均为常规数据类型或继承有 MonoBehaviour/ScriptableObject 的类与父类。

特性04：支持 Enum 枚举，但默认存储值为数值类型

public class JsonBase : MonoBehaviour
{
    
    
	public TeamType TeamType = TeamType.None;
}

public enum TeamType {
    
     TeamA, TeamB }

{ “TeamType”: 0 }

枚举值的计算按照 2^n 进行区别。有时期望于枚举使用 string 数据类型作为替代。则需要使用第三方 Json 数据工具处理，因为 JsonUtlity 仅针对 MonoBehaviour/ScriptableObject 或 Serializable应用特性的类、结构体下的 public 字段对象。

评估：JsonUtility 的适用环境

JsonUtility 是针对 Unity 场景内挂载脚本对象信息的最佳Json处理类方法，在记录场景对象信息上有着绝对的便利性。例如，适用该类存储某对象的 Component 信息，并创建一个新的对象，为其赋予属性内容。于是对于游戏缓存角色数据方面有着或多少的应用。例如：当前角色的 Transform 信息。