Unity中JSON格式的编写与使用指南
在Unity开发中,JSON(JavaScript Object Notation)作为一种轻量级的数据交换格式,因其易读、易解析且与语言无关的特性,被广泛应用于配置文件、数据存储、网络通信等场景,本文将详细介绍Unity中JSON格式的编写方法、常用工具及实战技巧,帮助开发者高效处理JSON数据。
JSON基础格式结构
JSON格式通过键值对(Key-Value)的方式组织数据,其核心结构包括两种类型:对象(Object)和数组(Array),这两种结构是编写JSON的基础。
对象(Object):无序的键值对集合
对象用花括号 包裹,键(Key)必须是字符串(用双引号 包裹),值(Value)可以是字符串、数字、布尔值、数组、对象或 null,多个键值对之间用逗号 分隔。
示例:
{
"playerName": "Alice",
"level": 10,
"isOnline": true,
"position": {
"x": 3.5,
"y": 1.2,
"z": 0.0
}
}
"playerName": "Alice":键为playerName,值为字符串"Alice";"level": 10:键为level,值为数字10;"isOnline": true:键为isOnline,值为布尔值true;"position": {...}:键为position,值为一个嵌套对象(包含坐标x、y、z)。
数组(Array):有序的值集合
数组用方括号 [] 包裹,值可以是字符串、数字、布尔值、数组、对象或 null,多个值之间用逗号 分隔,数组中的值可以通过索引(从 0 开始)访问。
示例:
{
"inventory": [
{"itemName": "Sword", "quantity": 1},
{"itemName": "Potion", "quantity": 5},
{"itemName": "Shield", "quantity": 1}
],
"questIDs": [101, 102, 105]
}
"inventory": [...]:键为inventory,值为一个对象数组,每个对象代表物品(包含名称和数量);"questIDs": [...]:键为questIDs,值为数字数组,存储任务ID。
数据类型规范
JSON支持以下数据类型,需注意格式要求:
- 字符串:必须用双引号 包裹(单引号非法),如
"Hello Unity"; - 数字:整数(
10)和浮点数(14)均可,无需引号; - 布尔值:
true或false(全小写,首字母不大写); - null:表示空值,小写
null; - 嵌套:对象内可嵌套对象或数组,数组内也可嵌套对象或数组,实现复杂数据结构。
Unity中JSON的编写方法
在Unity中,JSON编写通常分为两类:手动编写字符串(适用于简单配置)和通过代码动态生成(适用于动态数据)。
手动编写JSON字符串
对于固定数据(如游戏初始配置、技能表等),可直接在代码中定义JSON格式字符串。
示例:定义玩家初始配置的JSON字符串
using UnityEngine;
public class PlayerConfig : MonoBehaviour
{
private string playerConfigJson = @"
{
""playerName"": ""NewPlayer"",
""maxHealth"": 100,
""skills"": [
""Fireball"",
""IceShield"",
""Lightning Strike""
],
""initialPosition"": {
""x"": 0.0,
""y"": 0.0,
""z"": 0.0
}
}";
void Start()
{
Debug.Log("Player Config JSON: " + playerConfigJson);
}
}
注意:
- 字符串中使用双引号 时,需转义(如
""playerName""),避免与C#字符串的双引号冲突; - 使用 开头的字符串(C# verbatim string)可避免转义
\,提升可读性。
通过代码动态生成JSON
当数据需要运行时生成(如玩家实时状态、网络数据包),可通过Unity内置的 JsonUtility 或第三方库(如 Newtonsoft.Json)将C#对象序列化为JSON字符串。
(1)使用 JsonUtility(Unity原生工具)
JsonUtility 是Unity提供的轻量级JSON处理工具,支持将C#对象序列化为JSON(ToJson)或从JSON反序列化为对象(FromJson)。
步骤:
- 定义C#类:类的字段需与JSON的键名完全一致(可使用
[SerializeField]让私有字段可序列化); - 序列化:通过
JsonUtility.ToJson(obj)将对象转为JSON字符串; - 反序列化:通过
JsonUtility.FromJson<ClassName>(jsonStr)将JSON字符串转为对象。
示例:
using UnityEngine;
using System.Collections.Generic;
// 定义C#类(与JSON结构对应)
[System.Serializable] // 必须添加此特性才能被序列化
public class PlayerData
{
public string playerName;
public int level;
public bool isOnline;
public Vector3 position; // Unity内置类型(Vector3、Color等可直接序列化)
public List<string> skills; // 列表类型
}
public class JsonExample : MonoBehaviour
{
void Start()
{
// 1. 创建C#对象
PlayerData playerData = new PlayerData
{
playerName = "Bob",
level = 15,
isOnline = true,
position = new Vector3(5.2f, 0.0f, -3.1f),
skills = new List<string> { "Sword", "Shield", "Heal" }
};
// 2. 序列化为JSON字符串
string jsonStr = JsonUtility.ToJson(playerData, prettyPrint: true); // prettyPrint格式化缩进
Debug.Log("Serialized JSON: " + jsonStr);
// 3. 从JSON字符串反序列化为对象
PlayerData deserializedData = JsonUtility.FromJson<PlayerData>(jsonStr);
Debug.Log("Deserialized Player Name: " + deserializedData.playerName);
}
}
输出结果:
{
"playerName": "Bob",
"level": 15,
"isOnline": true,
"position": {
"x": 5.2,
"y": 0.0,
"z": -3.1
},
"skills": [
"Sword",
"Shield",
"Heal"
]
}
注意事项:
JsonUtility仅支持公共字段或[SerializeField]标记的私有字段;- 不支持字典(Dictionary)类型(需转换为
List<KeyValuePair>或使用第三方库); - 默认不格式化JSON(无缩进),
prettyPrint: true可输出易读格式(仅适用于调试,生产环境建议关闭以减少体积)。
(2)使用 Newtonsoft.Json(第三方库,功能更强大)
JsonUtility 功能有限(如不支持复杂嵌套、自定义转换),对于复杂场景(如API交互、深度嵌套数据),推荐使用第三方库 Newtonsoft.Json(需通过Package Manager安装)。
安装步骤:
- 打开Unity的
Package Manager(Window → Package Manager); - 点击 →
Add package from git URL...,输入com.unity.newtonsoft-json,安装最新版本。
示例(处理字典和复杂嵌套):
using UnityEngine;
using Newtonsoft.Json;
using System.Collections.Generic;
[System.Serializable]
public class Item
{
public string name;
public int count;
}
[System.Serializable]
public class PlayerInventory
{
public string playerName;
public Dictionary<string, Item> items; // 支持字典
public List<Item> equippedItems;
}
public class NewtonsoftJsonExample : MonoBehaviour
{
void Start()
{
// 创建对象
PlayerInventory inventory = new PlayerInventory
{
playerName = "Charlie",
items = new Dictionary<string, Item>
{
{ "weapon", new Item { name = "Axe", count = 1 } },
{ "consumable", new Item { name = "Apple", count = 3 } }
},
equippedItems = new List<Item>
{
new Item { name = "Armor", count = 1 }
}


还没有评论,来说两句吧...