JSON Сериализация

Используйте JsonUtility класс, чтобы преобразовывать объекты Unity в JSON Например, вы можете использовать JSON Serialization для взаимодействия с веб-сервисами или для легкой упаковки и распаковки данных в текстовом формате.

Сериализация JSON опирается на понятие «структурированного» JSON: вы описываете класс или структуру, задающую, какие переменные нужно хранить в данных JSON. Например:

[Serializable]
public class MyClass
{
    public int level;
    public float timeElapsed;
    public string playerName;
}

This defines a plain C# class containing three variables (Уровень, timeElapsed, и playerName) и обозначает его следующим образом: Serializable атрибут, чтобы работать с сериализатором JSON. Создать экземпляр вашего класса можно примерно так:

MyClass myObject = new MyClass();
myObject.level = 1;
myObject.timeElapsed = 47.5f;
myObject.playerName = "Dr Charles Francis";

Затем используйте методы JsonUtility.ToJson для серийизации (преобразования) в формат JSON:

string json = JsonUtility.ToJson(myObject);
// json now contains: '{"level":1,"timeElapsed":47.5,"playerName":"Dr Charles Francis"}'

Чтобы преобразовать JSON обратно в объект, используйте JsonUtility.FromJson:

myObject = JsonUtility.FromJson<MyClass>(json);

Это создает новый экземпляр MyClass и устанавливает значения на нем, используя данные JSON. Если данные JSON содержат значения, которые не соответствуют полям в MyClass, то сериализатор игнорирует эти значения. Если данные JSON не содержат значений для полей в MyClass, то сериализатор оставляет построенные значения для этих полей в возвращаемом объекте.

Перезапись объектов с JSON

Вы также можете десериализовать данные JSON над существующим объектом, что перезапишет все существующие данные:

JsonUtility.FromJsonOverwrite(json, myObject);

Если данные JSON не содержат значения для поля, сериализатор не изменяет значение этого поля. Этот метод позволяет сократить распределения до минимума, повторно используя ранее созданные объекты. Он также позволяет «патчировать» объекты, намеренно перезаписывая их JSON, который содержит только небольшое подмножество полей.

Предупреждение: Сериализатор JSON API поддерживает подклассы MonoBehaviour и ScriptableObject, а также простые структуры и классы. Однако, при десериализации JSON в подклассы MonoBehaviour или ScriptableObject, вы должны использовать метод FromJsonOverwrite. Если вы попытаетесь использовать метод FromJson, Unity вызовет исключение, так как такое поведение не поддерживается.

Поддерживаемые типы

API JSON Serializer поддерживает любой MonoBehaviour подкласс, ScriptableObject подкласс либо обычный класс или структуру с [Serializable] атрибут. Когда вы передаете объект в стандартный сериализатор Unity для обработки, применяются те же правила и ограничения, что и в Inspector: Unity сериализирует только поля; и типы, такие как Dictionary<> не поддерживаются.

Unity не поддерживает передачу других типов непосредственно в API, таких как примитивные типы или массивы. Если вам нужно их преобразовать, оберните их в class или struct того или иного типа.

Только в Редакторе существует параллельное API, EditorJsonUtility, которое позволяет сериализовать любой объект, полученный из UnityEngine.Object, как в JSON., так и из него. Это создает JSON, который содержит те же данные, что и представление объекта YAML.

JsonUtility и EditorJsonUtility являются полезными классами для сериализации Объектов в и из строкового формата JSON с использованием правил сериализации Unity. В случаях, когда необходимо манипулировать данными JSON с помощью кода, или для сериализации структур данных, которые не поддерживаются сериализацией Unity, вы можете использовать библиотеку общего назначения .NET JSON в качестве компаньона JsonUtility API.

Результаты работы

Эталонные испытания показывают, что JsonUtility заметно быстрее популярных решений JSON для .NET, хотя в ряде случаев этот класс предлагает меньше возможностей.

Использование памяти для сбора мусора (GC) является минимальным:

• ToJson выделяет GC памяти только для возвращаемой строки.
• FromJson выделяет память GC только для возвращаемого объекта, а также для любых необходимых подобъектов (например, если вы десериализируете объект, содержащий массив, то Unity выделяет память GC для массива).
• FromJsonOverwrite выделяет память GC только по мере необходимости для записываемых полей (например, строк и массивов). Это означает, что Unity вообще не выделяет памяти GC, если все поля, перезаписываемые JSON, имеют тип значений.

Вы можете использовать JsonUtility API из фонового потока. Однако, как и в любом многопоточном коде, будьте осторожны, чтобы не получить доступ или не изменить объект в одном потоке, пока другой поток сериализирует или десериялизирует его.

Контроль выхода ToJson()

Метод ToJson поддерживает pretty-printing вывода JSON. По умолчанию это отключено, но вы можете включить его, передавая true в качестве второго параметра.

Вы можете исключить поля из вывода, используя атрибут [NonSerialized].

Использование FromJson() с неизвестными типами

Если вы заранее не знаете тип объекта, десериализуйте JSON в класс или структуру с «общими» полями, а затем по значениям этих полей определите нужный фактический тип. После этого десериализуйте повторно уже в него.