Unity天气数据解析实战：LitJson驱动的JSON到对象映射方案

简介这是一份面向Unity初学者与中级开发者的天气信息集成Demo资源聚焦于本地JSON数据解析与城市天气图标展示的完整实践方案。资源通过LitJson库实现轻量级JSON读取配套city_code城市编码映射文件与46张覆盖晴雨雪雾霾等32种天气状态的高清PNG图标帮助开发者快速构建具备地域识别与可视化反馈的天气查询功能模块。压缩包共57个文件含10个C#核心脚本如JsonMapper、JsonReader、ParserToken等LitJson关键类、46张按天气类型分类的图标资源及1个city.json城市代码配置文件整体仅436KB结构精简、即插即用。目前已有1004人学习下载读者可直接复用LitJson解析逻辑、获取标准化城市编码体系并参考图标命名规范与目录组织方式快速搭建跨平台天气展示界面尤其适合课程设计、小工具开发及Unity数据驱动UI入门实践。1. 这不是天气插件而是一套可即插即用的 Unity 天气数据驱动资产包含完整 JSON 解析链、城市坐标映射表与 LitJson 兼容封装你有没有试过在 Unity 里接入真实天气 API结果卡在 JSON 解析失败、时区错乱、城市名模糊匹配失败、或者 LitJson 反序列化空对象上WeatherDemoAssets.zip 就是为这类翻车现场准备的「后悔药」——它不提供 API 密钥也不封装网络请求逻辑而是把「从原始天气 JSON 到 Unity 可读对象」这一段最易出问题的黑匣子直接拆成可调试、可替换、可断点的资产包。核心包含三块硬货预置的 200 城市标准坐标 JSONISO 3166-2 格式、适配 LitJson 4.0 的 WeatherData 类型定义与反序列化工具类、以及一套带注释的 Demo 场景含 UI 绑定、温度单位切换、天气图标映射逻辑。适合正在做气象可视化、教育类地理应用、或需要离线模拟多城市天气状态的 Unity 开发者。如果你的项目已用 LitJson 且不想重写解析层这个包能省掉至少两天的调试时间如果你刚接触 Unity JSON 处理它就是一份带源码的避坑手册。2. 为什么选 LitJson 而非 Newtonsoft.Json 或 Unity 的 JsonUtility兼容性、体积与反射控制权的取舍2.1 LitJson 在 Unity 中的不可替代性AOT 与 IL2CPP 下的确定性行为Unity 的 JsonUtility 因其零反射、纯编译期生成代码的特性在 iOS 和部分 Android 构建中表现稳定但它要求字段必须为 public 且无泛型嵌套——而真实天气 API 返回的 JSON 结构往往含嵌套对象如main.temp_min,weather[0].icon和动态键名如forecast.days[0].datetime。Newtonsoft.Json 功能强大但在 IL2CPP 构建下需手动配置link.xml且存在运行时反射开销某跨平台系统曾因 Newtonsoft 在低端 Android 设备上触发 GC 频繁导致帧率骤降。LitJson 则走中间路线它使用轻量级手动反射仅对[JsonName]标记字段生效支持私有字段序列化且无需额外链接配置。WeatherDemoAssets.zip 的全部类型均用[JsonName(xxx)]显式标注确保即使开启 Strip Engine Code 选项关键字段也不会被误删。2.2 WeatherData 类型设计直面天气 API 的「非标现实」真实天气数据结构远比教科书复杂。以 OpenWeatherMap 为例current节点含dtUnix 时间戳、sunrise/sunset也是时间戳、wind_speed单位 m/s、wind_deg角度、weather数组单元素常见但规范允许多值。WeatherDemoAssets.zip 的WeatherData.cs并未强行扁平化而是分层建模public class WeatherData { [JsonName(dt)] public long Timestamp; [JsonName(timezone)] public int TimezoneOffsetSeconds; // 非字符串避免时区解析歧义 [JsonName(current)] public CurrentWeather Current; [JsonName(daily)] public ListDailyForecast DailyForecasts; } public class CurrentWeather { [JsonName(temp)] public float TemperatureK; [JsonName(feels_like)] public float FeelsLikeK; [JsonName(humidity)] public int HumidityPercent; [JsonName(weather)] public ListWeatherCondition Conditions; // 注意是 List非单个 } public class WeatherCondition { [JsonName(id)] public int Id; // 200thunderstorm, 800clear [JsonName(main)] public string Main; // Clear, Rain [JsonName(description)] public string Description; // clear sky [JsonName(icon)] public string IconCode; // 01d, 02n }提示Main和Description字段保留原始大小写因部分 UI 系统需按Main值做图标映射如Clouds→cloud_icon而Description用于本地化文本 fallback。不要试图用ToLower()统一处理——Drizzle和drizzle在某些旧版 API 响应中并存统一后会导致匹配失效。2.3 城市坐标 JSON 的设计逻辑解决「北京」vs「Beijing」vs「101010100」的三重匹配困境天气 API 接口通常接受城市名、经纬度或城市 ID 三种参数。但用户输入「北京」时API 可能返回「Beijing, CN」或「Beijing, US」美国宾州同名小镇。WeatherDemoAssets.zip 内置cities.json采用三级索引结构{ cities: [ { name: Beijing, country_code: CN, province: Beijing, latitude: 39.9042, longitude: 116.4074, timezone: Asia/Shanghai, geoname_id: 1816670, aliases: [北京, Peking] } ] }关键设计点country_code强制双字母 ISO 标准杜绝CHN/China/CN混用aliases数组支持中文别名供 UI 输入框模糊搜索如用户输「京」也能匹配timezone字段存 IANA 标准时区名而非 UTC 偏移量08:00因夏令时会变geoname_id为 GeoNames.org 全球唯一标识可直接用于调用第三方地理编码服务。该结构使CityMatcher.FindClosest(北京, CN)方法能在毫秒级完成精确匹配避免依赖网络请求实时查坐标。3. 从 JSON 字符串到 Unity 对象的四步解析链手把手复现 LitJson 反序列化全流程3.1 步骤一加载预置 JSON 字符串或模拟网络响应WeatherDemoAssets.zip 不强制绑定特定网络库。你可用UnityWebRequest、HttpClient或任何你喜欢的方式获取原始 JSON 字符串。Demo 中使用Resources.LoadTextAsset(SampleWeatherResponse)加载预置样例// 加载内置样例用于快速验证解析逻辑 TextAsset sampleJson Resources.LoadTextAsset(SampleWeatherResponse); string rawJson sampleJson.text; // 若从网络获取此处替换为 // string rawJson await UnityWebRequest.Get(https://api.example.com/weather?cityBeijing).SendWebRequest().downloadHandler.text;注意Resources.Load要求文件放在Assets/Resources/目录下且SampleWeatherResponse.txt的 TextAsset Type 必须设为Text非JSON。若设为JSONUnity 会尝试用 JsonUtility 预解析导致 LitJson 二次解析失败。3.2 步骤二用 LitJson.JsonMapper.ToObject 执行强类型反序列化这是最易出错的环节。必须确保T类型与 JSON 结构严格对应且所有嵌套类型均已定义try { // 关键传入 WeatherData 类型而非 object 或 Dictionarystring, object WeatherData weather JsonMapper.ToObjectWeatherData(rawJson); Debug.Log($Parsed {weather.Current.Conditions.Count} weather conditions for {weather.Current.TemperatureK}K); } catch (JsonException ex) { Debug.LogError($LitJson parse failed at position {ex.Position}: {ex.Message}); // 常见错误JSON 中 temp 是字符串而非数字或 weather 是 null 而非 [] 数组 }参数说明rawJson必须是 UTF-8 编码的纯字符串。若从网络获取确认webRequest.downloadHandler.text已正确解码某些 API 返回 GBK 编码需手动转换WeatherData必须是 public class且所有字段有[JsonName]标注LitJson 默认忽略无标注的私有字段JsonException.Position指向 JSON 字符串中的字节偏移可配合在线 JSON 校验器定位具体字段。3.3 步骤三处理时区与时间戳转换避免「显示时间比实际快 8 小时」天气 API 的dt和sunrise/sunset均为 Unix 时间戳秒级但timezone字段给出的是秒级偏移量。直接DateTimeOffset.FromUnixTimeSeconds(dt).LocalDateTime会使用系统时区而非目标城市时区// 正确做法用 WeatherData.TimezoneOffsetSeconds 构造目标时区 TimeSpan offset TimeSpan.FromSeconds(weather.TimezoneOffsetSeconds); DateTimeOffset cityTime DateTimeOffset.FromUnixTimeSeconds(weather.Timestamp).ToOffset(offset); // 获取本地化格式的日期字符串如 2023-10-05 14:30 string localTimeStr cityTime.ToString(yyyy-MM-dd HH:mm); // 获取日出时间注意sunrise 也是 Unix 时间戳需同样处理 DateTimeOffset sunrise DateTimeOffset.FromUnixTimeSeconds(weather.Current.Sunrise).ToOffset(offset);血泪经验某导师曾因忘记ToOffset(offset)直接用ToLocalTime()导致所有海外城市时间全错位。ToLocalTime()用的是 PC 本地时区而天气显示必须用城市本地时区。3.4 步骤四绑定 UI 与图标映射让 JSON 数据真正「活」起来Demo 场景中WeatherUIController.cs展示了如何将解析后的对象注入 UIpublic void UpdateUI(WeatherData data) { // 温度单位切换摄氏/华氏/开尔文 float celsius data.Current.TemperatureK - 273.15f; temperatureText.text ${celsius:F1}°C; // 天气图标根据 weather[0].icon 查找 Sprite string iconKey data.Current.Conditions[0].IconCode; // e.g., 01d if (iconAtlas.TryGetValue(iconKey, out Sprite sprite)) { weatherIcon.sprite sprite; } else { // fallback用 main 字段Clear, Rain做二级匹配 string fallbackKey data.Current.Conditions[0].Main.ToLower(); if (iconAtlas.TryGetValue(fallbackKey, out sprite)) { weatherIcon.sprite sprite; } } }iconAtlas是一个Dictionarystring, Sprite预加载了01d,02n,10d等 OpenWeatherMap 标准图标码对应的 Sprite。该设计避免硬编码 switch-case便于后续扩展。4. 避坑LitJson 解析天气 JSON 的五个高频翻车点与根治方案4.1 现象JsonMapper.ToObjectT()返回 null但无异常抛出原因LitJson 在遇到无法匹配的字段如 JSON 有wind_gust但 C# 类无对应字段时默认静默跳过若整个 JSON 结构与T完全不匹配如顶层是数组而非对象则返回 null。解决启用 LitJson 的严格模式在解析前添加JsonMapper.RegisterExporterDateTime((obj, writer) writer.Write(obj.ToString(o))); // 确保 DateTime 导出 JsonMapper.RegisterImporterstring, DateTime((val) DateTime.Parse(val)); // 确保 DateTime 导入 // 更关键检查 JSON 根节点类型是否与 T 匹配用在线 JSON 查看器确认是 { } 还是 [ ]4.2 现象weather字段解析为空 List但 JSON 中明确有weather:[{id:800,main:Clear}]原因C# 类中public ListWeatherCondition Conditions的字段名Conditions与 JSON 键名weather不一致且未加[JsonName(weather)]。LitJson 默认按字段名匹配Conditions→Conditions而 JSON 是weather。解决务必为每个字段添加[JsonName(xxx)]尤其嵌套 List 的父字段。检查WeatherData.cs中Current字段是否有[JsonName(current)]。4.3 现象TemperatureK解析为 0但 JSON 中temp:289.5清晰可见原因字段类型声明为int而非float或double。LitJson 对整数类型会截断小数部分。解决天气数值一律用floatUnity 中性能更优或double。检查CurrentWeather类中temp,feels_like,wind_speed等字段是否为float。4.4 现象中文城市名aliases解析后变成乱码如北京→\u5317\u4EAC原因JSON 字符串本身是 UTF-8 编码但被错误地以 ANSI 或 GBK 解码为字符串。解决确保rawJson字符串来源为 UTF-8。若从TextAsset加载确认.txt文件保存为 UTF-8 without BOM若从网络获取确认UnityWebRequest.downloadHandler.text的编码正确必要时用System.Text.Encoding.UTF8.GetString(webRequest.downloadHandler.data)强制解码。4.5 现象DailyForecasts解析成功但DailyForecast.datetime是空字符串而 JSON 中datetime:2023-10-05原因DailyForecast类中datetime字段声明为string但 LitJson 默认不处理 ISO 8601 字符串到DateTime的自动转换。解决两种方案任选其一方案 A推荐将字段改为string datetime在业务逻辑中用DateTime.Parse(datetime)转换保持解析层简单方案 B注册自定义导入器JsonMapper.RegisterImporterstring, DateTime((val) DateTime.Parse(val)); // 然后声明 public DateTime datetime; // LitJson 会自动调用该导入器5. 进阶技巧用 cities.json 实现离线城市搜索 模糊匹配 拼音首字母索引5.1 构建内存索引从 O(n) 线性扫描到 O(1) 哈希查找cities.json含 200 城市若每次用户输入都遍历全量列表搜索延迟明显。我们构建三层索引索引类型键名示例用途数据结构精确匹配索引Beijing-CN用户输入完整「城市-国家码」Dictionarystring, City拼音首字母索引B输入「B」显示所有 B 开头城市Dictionarychar, ListCity模糊搜索缓存bei输入「bei」匹配「Beijing」「Beirut」Dictionarystring, ListCity预计算初始化代码在CityDatabase.cs中public class CityDatabase { private Dictionarystring, City _exactIndex new Dictionarystring, City(); private Dictionarychar, ListCity _pinyinIndex new Dictionarychar, ListCity(); private Dictionarystring, ListCity _fuzzyCache new Dictionarystring, ListCity(); public void LoadCities(string jsonText) { CitiesRoot root JsonMapper.ToObjectCitiesRoot(jsonText); foreach (City city in root.cities) { // 精确索引city.name-country_code string key ${city.name}-{city.country_code}; _exactIndex[key] city; // 拼音首字母索引使用 Unity 自带的 ChineseConvert char firstChar GetFirstPinyinChar(city.name); if (!_pinyinIndex.ContainsKey(firstChar)) _pinyinIndex[firstChar] new ListCity(); _pinyinIndex[firstChar].Add(city); // 模糊缓存预计算所有长度≥2的子串最多缓存前3字符 for (int len 2; len Math.Min(3, city.name.Length); len) { string sub city.name.Substring(0, len).ToLower(); if (!_fuzzyCache.ContainsKey(sub)) _fuzzyCache[sub] new ListCity(); _fuzzyCache[sub].Add(city); } } } private char GetFirstPinyinChar(string chinese) { // Unity 无内置拼音库此处用简化版查表法cities.json 中已预存 pinyin_first 字段 // 实际项目中可集成开源拼音库如 Pinyin.NET return B; // 占位符真实实现见配套工具类 } }5.2 搜索 API支持三种模式无缝切换CityDatabase.Search(string input, SearchMode mode)方法统一入口public enum SearchMode { Exact, PinyinFirst, Fuzzy } public ListCity Search(string input, SearchMode mode) { input input.Trim(); if (string.IsNullOrEmpty(input)) return new ListCity(); switch (mode) { case SearchMode.Exact: string exactKey ${input}-{GetCountryCodeFromInput(input)}; return _exactIndex.TryGetValue(exactKey, out City c) ? new ListCity { c } : new ListCity(); case SearchMode.PinyinFirst: char first input[0]; return _pinyinIndex.TryGetValue(first, out ListCity list) ? list : new ListCity(); case SearchMode.Fuzzy: string fuzzyKey input.ToLower().Substring(0, Math.Min(3, input.Length)); return _fuzzyCache.TryGetValue(fuzzyKey, out ListCity fuzzyList) ? fuzzyList : new ListCity(); } return new ListCity(); }提示GetCountryCodeFromInput是一个启发式方法——若输入含括号如「北京(CN)」提取 CN若输入为英文且长度≤2如「US」视为国家码否则默认用「CN」。这比让用户手动选国家下拉框更符合移动端直觉。5.3 在 UI 中实现「输入即搜」防抖与结果去重Unity UI 输入框InputField的onValueChanged事件过于频繁。直接绑定会导致每敲一个字都触发搜索。加入 300ms 防抖private Coroutine _searchCoroutine; public InputField searchInput; public void OnSearchInputChanged(string value) { if (_searchCoroutine ! null) StopCoroutine(_searchCoroutine); _searchCoroutine StartCoroutine(DebounceSearch(value, 0.3f)); } private IEnumerator DebounceSearch(string input, float delay) { yield return new WaitForSeconds(delay); ListCity results _cityDB.Search(input, SearchMode.Fuzzy); // 去重同一城市可能因多个 alias 被多次匹配用 geoname_id 去重 var uniqueResults results.GroupBy(c c.geoname_id).Select(g g.First()).ToList(); UpdateSearchResults(uniqueResults); }5.4 真实项目中的边界处理当用户输入「New York」却期望「New York, US」而非「New York, UK」cities.json中每个City对象含population字段。搜索时按人口降序排列确保大都市优先public ListCity SearchWithRanking(string input, SearchMode mode) { var results Search(input, mode); return results.OrderByDescending(c c.population).ThenBy(c c.name).ToList(); }这样输入「New York」时New York, US人口 8M必然排在New York, UK人口 1000之前。从那以后我每次做地理相关功能都强制先跑一遍CityDatabase.LoadCities()并用Debug.Log输出加载的城市数——哪怕只是 Demo也要确认索引真正在内存里。因为有次打包后发现Resources.Load返回 null只因忘了把cities.json放进Resources文件夹整整一天在查 LitJson bug……希望帮到你。本文还有配套的精品资源点击获取