HarmonyOS鸿蒙Next Flutter Tips 在 Flutter 中如何获取本地的 json 文件并解码

HarmonyOS鸿蒙Next Flutter Tips 在 Flutter 中如何获取本地的 json 文件并解码 Flutter 读取本地 JSON 需先在 pubspec.yaml 声明文件资源，再通过 rootBundle 读取文件内容，最后用 json.decode() 解析为 Dart 对象；进阶场景建议结合 json_serializable 生成模型类，简化解析逻辑。

一、前置步骤：配置 JSON 文件资源

1. 创建 JSON 文件

在项目根目录新建 assets 文件夹（若不存在），放入 JSON 文件（如 data.json）：

2. 声明资源（关键！否则读取失败）

在 pubspec.yaml 中添加 JSON 文件的资源声明（注意缩进，和 dependencies 同级）：

添加后执行 flutter pub get 同步配置。

二、基础用法：读取并解码 JSON

1. 核心代码（直接解析为 Map/List）

2. 关键说明

• 1 rootBundle.loadString()：异步读取 assets 目录下的文件，返回字符串；
• 2 json.decode()：将 JSON 字符串转为 Map<String, dynamic>（对象）或 List<dynamic>（数组）；
• 3 异常捕获：必须包裹 try-catch，避免文件路径错误、JSON 格式错误导致崩溃。

三、进阶用法：模型化解析（推荐）

直接用 Map 解析易出错（如字段名拼写错误、类型不匹配），推荐用 json_serializable 生成模型类，实现类型安全的解析。

步骤 1：添加依赖

执行 flutter pub get 安装依赖。

步骤 2：创建模型类（如 app_info.dart）

步骤 4：使用模型类解析 JSON

四、常见场景扩展

1. 读取 JSON 数组文件

若 JSON 文件是数组格式（如 assets/list_data.json）：

2. 读取非 assets 目录的 JSON 文件

若 JSON 文件在设备本地存储（如 Documents 目录），需用 path_provider 插件：

五、常见问题排查

• 1. 读取失败：Unable to load asset→ 检查 pubspec.yaml 中 assets 路径是否正确（缩进、文件名大小写）；→ 执行 flutter pub get 后重启应用（热重载不生效）。
• 2. JSON 解码报错：FormatException→ 检查 JSON 文件格式是否合法（可用在线 JSON 校验工具验证）；→ 避免 JSON 中有注释（JSON 不支持 // 注释）。
• 3. 模型解析报错：Missing required keys→ 检查模型类字段与 JSON 字段名是否一致；→ 若字段可选，用 @JsonKey(defaultValue: '') 或 required 修饰。

总结

1. 读取本地 JSON 核心步骤：声明 assets 资源 → rootBundle.loadString() 读取 → json.decode() 解码；
2. 基础场景用 Map/List 解析，进阶场景用 json_serializable 生成模型类（类型安全、易维护）；
3. 非 assets 目录的 JSON 文件，需用 path_provider 插件获取本地路径，通过 File 类读取。