概述

dart:convert 是Dart标准库的核心模块之一，提供了JSON编码和解码的完整功能。在Flutter开发中，特别是在鸿蒙平台上进行数据交换时，dart:convert 是处理JSON数据的基础工具。本文将深入探讨 dart:convert 库的核心API、高级用法和性能优化技巧。

1. dart:convert库简介

dart:convert 库提供了多种数据转换功能，其中与JSON相关的主要包括：

• json.encode() / jsonEncode()：将Dart对象编码为JSON字符串
• json.decode() / jsonDecode()：将JSON字符串解码为Dart对象
• JsonEncoder：自定义JSON编码器
• JsonDecoder：自定义JSON解码器
• JsonCodec：JSON编解码器组合

1.1 导入方式

import 'dart:convert';

2. 核心API详解

2.1 jsonDecode() - 解码JSON字符串

String jsonString = '{"city": "北京", "temperature": 28}';
Map<String, dynamic> data = jsonDecode(jsonString);

参数说明：

• source：JSON字符串
• reviver（可选）：转换函数，用于修改解码过程中的值

返回值：

• Map<String, dynamic> 或 List<dynamic>
• 基础类型：String、int、double、bool、null

2.2 jsonEncode() - 编码为JSON字符串

Map<String, dynamic> data = {
  'city': '北京',
  'temperature': 28,
};
String jsonString = jsonEncode(data);

参数说明：

• object：要编码的Dart对象
• toEncodable（可选）：转换函数，处理无法直接编码的对象

2.3 json.decode() 与 jsonDecode() 的区别

两者功能相同，但命名风格不同：

// 旧风格（不推荐）
Map<String, dynamic> data = json.decode(jsonString);

// 新风格（推荐）
Map<String, dynamic> data = jsonDecode(jsonString);

3. 高级用法

3.1 使用JsonEncoder自定义编码

JsonEncoder encoder = JsonEncoder.withIndent('  ');
String prettyJson = encoder.convert({
  'city': '北京',
  'temperature': 28,
});

常用构造函数：

构造函数	说明
JsonEncoder()	默认编码器
JsonEncoder.withIndent(indent)	带缩进的编码器
JsonEncoder(toEncodable)	自定义转换函数

3.2 使用JsonDecoder自定义解码

JsonDecoder decoder = JsonDecoder();
dynamic data = decoder.convert(jsonString);

3.3 使用reviver函数修改解码结果

Map<String, dynamic> data = jsonDecode(
  jsonString,
  (key, value) {
    if (key == 'temperature') {
      return (value as num).toDouble();
    }
    return value;
  },
);

3.4 使用toEncodable处理自定义对象

class Weather {
  final String city;
  final int temperature;
  
  Weather({required this.city, required this.temperature});
}

Weather weather = Weather(city: '北京', temperature: 28);
String jsonString = jsonEncode(
  weather,
  toEncodable: (object) {
    if (object is Weather) {
      return {
        'city': object.city,
        'temperature': object.temperature,
      };
    }
    return object;
  },
);

4. 格式化输出

4.1 美化JSON格式

Map<String, dynamic> data = {
  'weather': {
    'city': '北京',
    'temperature': 28,
    'forecast': [28, 29, 30]
  }
};

// 美化输出
String prettyJson = JsonEncoder.withIndent('  ').convert(data);
print(prettyJson);

输出结果：

{
  "weather": {
    "city": "北京",
    "temperature": 28,
    "forecast": [28, 29, 30]
  }
}

4.2 压缩JSON格式

String compactJson = jsonEncode(data);
print(compactJson);

输出结果：

{"weather":{"city":"北京","temperature":28,"forecast":[28,29,30]}}

5. 编码自定义对象

5.1 实现toJson()方法

class Weather {
  final String city;
  final int temperature;
  
  Weather({required this.city, required this.temperature});
  
  Map<String, dynamic> toJson() {
    return {
      'city': city,
      'temperature': temperature,
    };
  }
}

Weather weather = Weather(city: '北京', temperature: 28);
String jsonString = jsonEncode(weather);

5.2 实现fromJson()工厂方法

class Weather {
  final String city;
  final int temperature;
  
  Weather({required this.city, required this.temperature});
  
  factory Weather.fromJson(Map<String, dynamic> json) {
    return Weather(
      city: json['city'] as String,
      temperature: (json['temperature'] as num).toInt(),
    );
  }
}

Map<String, dynamic> data = jsonDecode(jsonString);
Weather weather = Weather.fromJson(data);

6. 处理特殊数据类型

6.1 DateTime类型处理

Map<String, dynamic> data = {
  'city': '北京',
  'updateTime': DateTime.now(),
};

String jsonString = jsonEncode(
  data,
  toEncodable: (object) {
    if (object is DateTime) {
      return object.toIso8601String();
    }
    return object;
  },
);

6.2 枚举类型处理

enum WeatherCondition { sunny, cloudy, rainy }

WeatherCondition condition = WeatherCondition.sunny;

String jsonString = jsonEncode(
  {'condition': condition.name},
);

7. 性能优化

7.1 避免重复编码解码

// 缓存编码结果
Map<String, String> _jsonCache = {};

String getCachedJson(String key, Map<String, dynamic> data) {
  if (!_jsonCache.containsKey(key)) {
    _jsonCache[key] = jsonEncode(data);
  }
  return _jsonCache[key]!;
}

7.2 使用JsonCodec复用编解码器

JsonCodec codec = JsonCodec();
Map<String, dynamic> data = codec.decode(jsonString);
String encoded = codec.encode(data);

8. 鸿蒙平台兼容性

8.1 编码一致性

在鸿蒙平台上，确保使用UTF-8编码：

import 'dart:convert';

// 编码
List<int> bytes = utf8.encode(jsonString);

// 解码
String decoded = utf8.decode(bytes);

8.2 平台特定数据处理

dynamic decodeJson(String jsonString) {
  try {
    return jsonDecode(jsonString);
  } catch (e) {
    print('JSON解析失败: $e');
    return null;
  }
}

9. 完整示例

import 'dart:convert';

void main() {
  // 原始数据
  Map<String, dynamic> weatherData = {
    'city': '北京',
    'temperature': 28,
    'humidity': 65,
    'wind': {
      'direction': '东南风',
      'speed': 3
    },
    'forecast': [28, 29, 30],
    'isRainy': false,
    'updateTime': DateTime.now().toIso8601String(),
  };
  
  // 编码为JSON字符串（压缩格式）
  String compactJson = jsonEncode(weatherData);
  print('压缩格式: $compactJson');
  
  // 编码为JSON字符串（美化格式）
  String prettyJson = JsonEncoder.withIndent('  ').convert(weatherData);
  print('\n美化格式:\n$prettyJson');
  
  // 解码JSON字符串
  Map<String, dynamic> decodedData = jsonDecode(prettyJson);
  
  // 提取数据
  String city = decodedData['city'] as String;
  int temperature = (decodedData['temperature'] as num).toInt();
  
  print('\n解析结果:');
  print('城市: $city');
  print('温度: ${temperature}°C');
}

10. 总结

dart:convert 库提供了完整的JSON编解码功能，是Flutter开发中处理JSON数据的基础工具。通过掌握核心API和高级用法，开发者可以高效地处理各种JSON数据格式。下一章将介绍序列化与反序列化的完整实现。

核心知识点回顾

1. dart:convert 提供 jsonEncode() 和 jsonDecode() 两个核心函数
2. 使用 JsonEncoder.withIndent() 实现美化输出
3. 自定义对象需要实现 toJson() 和 fromJson() 方法
4. 使用 reviver 和 toEncodable 参数处理特殊类型
5. 在鸿蒙平台上确保使用UTF-8编码
6. 推荐使用新命名风格 jsonEncode() / jsonDecode()