Unity (U3D) 与 JSON 数据交互完全指南
在 Unity 开发中,数据交互是构建功能丰富的应用的核心环节,JSON(JavaScript Object Notation)以其轻量级、易读、跨语言兼容的特性,成为游戏开发中数据存储(如配置文件、存档)、网络通信(如 API 请求、服务器数据同步)的首选格式,本文将详细介绍 Unity 如何与 JSON 数据进行交互,包括核心方法、实战步骤及常见问题解决,帮助开发者高效处理 JSON 数据。
Unity 中处理 JSON 的核心方式
Unity 提供了多种 JSON 处理方式,主要分为 官方原生方法 和 第三方库 两大类,开发者可根据需求(如数据复杂度、性能要求、项目规模)选择合适的方式。
官方原生方法:JsonUtility
Unity 自带的 JsonUtility 是最轻量级的 JSON 处理工具,支持将 C# 对象序列化为 JSON 字符串,或从 JSON 字符串反序列化为 C# 对象,其优点是无需引入额外库,与 Unity 引擎深度集成;缺点是功能相对基础,不支持复杂类型(如字典、多态对象)。
(1)基本使用:序列化与反序列化
序列化(对象 → JSON):将 C# 对象转换为 JSON 字符串,用于数据存储或网络传输。
using UnityEngine;
using System;
// 定义可序列化的 C# 类(需标记 [Serializable])
[Serializable]
public class PlayerData
{
public string playerName;
public int level;
public float health;
public string[] inventory; // 数组支持
}
public class JsonExample : MonoBehaviour
{
void Start()
{
// 1. 创建对象并赋值
PlayerData player = new PlayerData
{
playerName = "Alice",
level = 10,
health = 85.5f,
inventory = new[] { "Sword", "Potion", "Shield" }
};
// 2. 序列化为 JSON 字符串
string jsonStr = JsonUtility.ToJson(player, prettyPrint: true); // prettyPrint 格式化输出
Debug.Log("序列化结果:\n" + jsonStr);
/* 输出:
{
"playerName": "Alice",
"level": 10,
"health": 85.5,
"inventory": ["Sword", "Potion", "Shield"]
}
*/
}
}
反序列化(JSON → 对象):将 JSON 字符串解析为 C# 对象,用于读取存档或接收服务器数据。
using UnityEngine;
public class JsonDeserializationExample : MonoBehaviour
{
void Start()
{
// 模拟从文件/网络获取的 JSON 数据
string jsonStr = @"
{
""playerName"": ""Bob"",
""level"": 15,
""health"": 100.0,
""inventory"": [""Bow"", ""Arrow""]
}";
// 反序列化为 PlayerData 对象
PlayerData player = JsonUtility.FromJson<PlayerData>(jsonStr);
// 输出解析结果
Debug.Log($"玩家: {player.playerName}, 等级: {player.level}, 生命值: {player.health}");
// 输出:玩家: Bob, 等级: 15, 生命值: 100
}
}
(2)JsonUtility 的注意事项
- 类必须标记
[Serializable]:否则无法序列化/反序列化。 - 不支持字典(
Dictionary):需改用List< KeyValuePair<TKey, TValue>>或第三方库。 - 字段名需与 JSON 键名一致:若需不一致,可通过
[SerializeField] private string _playerName+[JsonProperty("playerName")](需引入Newtonsoft.Json)解决,但JsonUtility原生不支持,需结合第三方库。 - 反序列化时 JSON 需严格匹配结构:多余字段会被忽略,缺少字段则设为默认值(如
int为 0,string为null)。
第三方库:Newtonsoft.Json(推荐处理复杂数据)
Newtonsoft.Json(又称 Json.NET)是功能强大的 JSON 框架,支持复杂类型(字典、多态、嵌套对象)、字段别名、自定义序列化逻辑等,适合大型项目或复杂数据场景,需通过 Unity Package Manager 安装:
Window > Package Manager > "+" > "Add package from git URL",输入 com.unity.newtonsoft-json。
(1)基本使用:序列化与反序列化
序列化:
using UnityEngine;
using Newtonsoft.Json;
[Serializable]
public class EnemyData
{
public string enemyName;
public int attack;
public Dictionary<string, int> resistances; // 支持字典!
}
public class NewtonsoftExample : MonoBehaviour
{
void Start()
{
EnemyData enemy = new EnemyData
{
enemyName = "Dragon",
attack = 50,
resistances = new Dictionary<string, int>
{
{ "Fire", 80 },
{ "Ice", 20 }
}
};
// 序列化为 JSON(自动处理字典)
string jsonStr = JsonConvert.SerializeObject(enemy, Formatting.Indented);
Debug.Log("Newtonsoft 序列化:\n" + jsonStr);
/* 输出:
{
"enemyName": "Dragon",
"attack": 50,
"resistances": {
"Fire": 80,
"Ice": 20
}
}
*/
}
}
反序列化:
using Newtonsoft.Json;
public class NewtonsoftDeserializationExample : MonoBehaviour
{
void Start()
{
string jsonStr = @"
{
""enemyName"": ""Goblin"",
""attack"": 25,
""resistances"": { ""Poison"": 100 }
}";
// 反序列化(自动解析字典)
EnemyData enemy = JsonConvert.DeserializeObject<EnemyData>(jsonStr);
Debug.Log($"敌人: {enemy.enemyName}, 攻击力: {enemy.attack}, 毒抗性: {enemy.resistances["Poison"]}");
// 输出:敌人: Goblin, 攻击力: 25, 毒抗性: 100
}
}
(2)Newtonsoft.Json 的高级特性
-
字段别名:通过
[JsonProperty("json键名")]解决 C# 字段名与 JSON 键名不一致问题。[Serializable] public class Player { [JsonProperty("player_name")] // JSON 中使用 "player_name" public string playerName; } -
多态对象序列化:通过
[JsonConverter]指定子类转换器,实现父类引用子类对象。[JsonConverter(typeof(PolymorphicJsonConverter))] // 需自定义转换器 public abstract class Item { public abstract string GetType(); } public class Sword : Item { public override string GetType() => "Sword"; } -
忽略字段:通过
[JsonIgnore]跳过不需要序列化的字段。[Serializable] public class PlayerData { public string playerName; [JsonIgnore] // 不序列化此字段 private string password; }
其他第三方库:SimpleJSON
SimpleJSON 是轻量级 JSON 解析库,专注于手动解析动态 JSON(如从 API 接收的未知结构数据),无需定义 C# 类,适合处理灵活或非结构化数据,需通过 Unity Package Manager 安装:com.unity.simple.json。
(1)手动解析 JSON 示例
using UnityEngine;
using SimpleJSON;
public class SimpleJSONExample : MonoBehaviour
{
void Start()
{
// 模拟动态 JSON 数据(键名可能变化)
string jsonStr = @"
{
""status"": ""success"",
""data"": {
""items"": [
{ ""id"": 1, ""name"": ""Health Potion"" },
{ ""id"": 2, ""name"": ""Mana Potion"" }
],
""total"": 2
}
}";
// 解析 JSON
JSONNode rootNode = JSON.Parse(jsonStr);
// 提取数据(通过键名逐层访问)
string status = rootNode["status"];
Debug.Log($"状态: {status}"); // 输出:状态: success
// 遍历数组
JSONArray items = rootNode["data"]["items"].AsArray;
foreach (JSONNode item in items)
{
int id = item["id"].AsInt;
string name = item["name"];
Debug.Log($"物品ID: {id}, 名称:


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