概述

在日常开发中，我们经常需要处理JSON数据。有时候这些数据是紧凑的单行格式，不便于阅读和调试。JSON格式化与美化就是将这些紧凑的JSON字符串转换为易读的多行格式，同时也支持将美化后的JSON压缩回紧凑格式。

本章将深入探讨Flutter在鸿蒙平台上的JSON格式化技术，包括：

• JsonEncoder.withIndent() 的使用
• 自定义缩进配置
• JSON压缩与格式化对比
• 实用的应用场景

---

核心概念

什么是JSON格式化

JSON格式化（JSON Formatting）是指将紧凑的JSON字符串转换为具有适当缩进和换行的可读格式。这在调试、日志记录和数据展示时非常有用。

紧凑格式：

{"name":"张三","age":25,"isStudent":true,"scores":[95,88,92],"address":{"city":"北京","district":"朝阳区"}}

美化格式：

{
  "name": "张三",
  "age": 25,
  "isStudent": true,
  "scores": [95, 88, 92],
  "address": {
    "city": "北京",
    "district": "朝阳区"
  }
}

为什么需要格式化

1. 调试方便：格式化后的JSON更容易阅读和理解结构
2. 日志清晰：在控制台输出时一目了然
3. 数据验证：便于检查JSON结构是否正确
4. 文件存储：美化后的配置文件更易于维护

---

实现方案

使用JsonEncoder.withIndent()

Flutter提供了 dart:convert 库中的 JsonEncoder 类，通过 withIndent() 方法可以轻松实现JSON美化。

import 'dart:convert';

void formatJson() {
  final Map<String, dynamic> data = {
    'name': '张三',
    'age': 25,
    'isStudent': true,
    'scores': [95, 88, 92],
    'address': {
      'city': '北京',
      'district': '朝阳区'
    }
  };

  // 使用2个空格缩进
  final JsonEncoder encoder = JsonEncoder.withIndent('  ');
  final String prettyJson = encoder.convert(data);
  
  print(prettyJson);
}

自定义缩进配置

withIndent() 方法接受一个字符串参数作为缩进符，可以使用空格或制表符。

// 使用4个空格缩进
final JsonEncoder encoder4 = JsonEncoder.withIndent('    ');

// 使用制表符缩进
final JsonEncoder encoderTab = JsonEncoder.withIndent('\t');

// 使用自定义字符缩进
final JsonEncoder encoderCustom = JsonEncoder.withIndent('|-');

压缩JSON

与美化相反，有时我们需要将JSON压缩为紧凑格式以减少传输体积。

import 'dart:convert';

void minifyJson() {
  final Map<String, dynamic> data = {
    'name': '张三',
    'age': 25,
    'isStudent': true
  };

  // 使用json.encode()直接输出紧凑格式
  final String compactJson = json.encode(data);
  // 输出: {"name":"张三","age":25,"isStudent":true}
}

---

实战案例

完整的格式化工具类

import 'dart:convert';

class JsonFormatter {
  static String format(Map<String, dynamic> data, {int indent = 2}) {
    final String indentStr = ' ' * indent;
    return JsonEncoder.withIndent(indentStr).convert(data);
  }

  static String minify(Map<String, dynamic> data) {
    return json.encode(data);
  }

  static String formatString(String jsonString, {int indent = 2}) {
    try {
      final dynamic parsed = json.decode(jsonString);
      final String indentStr = ' ' * indent;
      return JsonEncoder.withIndent(indentStr).convert(parsed);
    } catch (e) {
      return '格式错误: $e';
    }
  }

  static String minifyString(String jsonString) {
    try {
      final dynamic parsed = json.decode(jsonString);
      return json.encode(parsed);
    } catch (e) {
      return '格式错误: $e';
    }
  }

  static int countLines(String formattedJson) {
    return formattedJson.split('\n').length;
  }

  static int countCharacters(String jsonString) {
    return jsonString.length;
  }
}

使用示例

void main() {
  final Map<String, dynamic> config = {
    'appName': 'Flutter HarmonyOS Demo',
    'version': '1.0.0',
    'settings': {
      'notifications': true,
      'autoUpdate': false
    },
    'features': ['weather', 'news']
  };

  // 格式化输出
  final String formatted = JsonFormatter.format(config, indent: 4);
  print('格式化后:');
  print(formatted);
  print('行数: ${JsonFormatter.countLines(formatted)}');

  // 压缩输出
  final String compact = JsonFormatter.minify(config);
  print('\n压缩后:');
  print(compact);
  print('字符数: ${JsonFormatter.countCharacters(compact)}');

  // 字符串格式化
  final String jsonString = '{"name":"张三","age":25}';
  print('\n字符串格式化:');
  print(JsonFormatter.formatString(jsonString));
}

---

方法对比

方法	效果	适用场景
json.encode()	紧凑单行输出	网络传输、存储
JsonEncoder.withIndent()	格式化多行输出	调试、日志
json.decode()	解析为Dart对象	数据处理

---

应用场景

场景一：调试输出

在开发过程中，我们经常需要查看API返回的数据结构。格式化后的JSON可以让我们更快地理解数据。

void debugApiResponse(Map<String, dynamic> response) {
  final String formatted = JsonEncoder.withIndent('  ').convert(response);
  debugPrint('API Response:\n$formatted');
}

场景二：日志记录

在生产环境中，格式化的日志更容易被日志分析工具处理和阅读。

void logEvent(String eventName, Map<String, dynamic> data) {
  final String formattedData = JsonEncoder.withIndent('  ').convert(data);
  logger.info('[$eventName]\n$formattedData');
}

场景三：配置文件管理

应用的配置文件通常以JSON格式存储，格式化后的配置文件更易于人工编辑和维护。

Future<void> saveConfig(Map<String, dynamic> config) async {
  final File file = File('config.json');
  final String formatted = JsonEncoder.withIndent('  ').convert(config);
  await file.writeAsString(formatted);
}

场景四：数据交换

在网络传输时使用紧凑格式减少数据量，在展示时使用美化格式提高可读性。

// 传输时使用紧凑格式
final String payload = json.encode(data);
await http.post(uri, body: payload);

// 展示时使用美化格式
final String displayData = JsonEncoder.withIndent('  ').convert(data);

---

性能考虑

格式化的开销

格式化JSON会增加字符串的长度，通常会增加30%-50%的字符数。在需要考虑性能的场景中，应该：

1. 仅在需要时格式化：不要在每次数据处理时都格式化
2. 使用缓存：如果数据不变，缓存格式化结果
3. 选择合适的缩进：使用较少的缩进可以减少额外字符

压缩的优势

压缩后的JSON：

• 减少网络传输时间
• 降低存储占用
• 提高解析速度（减少字符处理）

---

鸿蒙平台注意事项

资源限制

在鸿蒙平台上，特别是在低端设备上，需要注意：

1. 内存使用：格式化大型JSON会创建较大的字符串对象，注意内存占用
2. 性能优化：避免在UI线程进行大量JSON格式化操作
3. 日志限制：鸿蒙系统对日志长度有限制，超长日志可能被截断

平台特定实现

import 'dart:convert';
import 'package:flutter/foundation.dart';

class PlatformJsonFormatter {
  static String format(Map<String, dynamic> data) {
    if (kIsWeb) {
      // Web平台可以使用更多缩进
      return JsonEncoder.withIndent('    ').convert(data);
    } else if (defaultTargetPlatform == TargetPlatform.android) {
      // Android/HarmonyOS使用标准缩进
      return JsonEncoder.withIndent('  ').convert(data);
    } else {
      return JsonEncoder.withIndent('  ').convert(data);
    }
  }
}

---

常见问题

Q1: 格式化后的JSON如何复制到剪贴板？

import 'package:flutter/services.dart';

void copyToClipboard(String text) {
  Clipboard.setData(ClipboardData(text: text));
}

Q2: 如何处理格式化失败的情况？

String formatJson(String input) {
  try {
    final dynamic parsed = json.decode(input);
    return JsonEncoder.withIndent('  ').convert(parsed);
  } on FormatException catch (e) {
    return 'JSON格式错误: $e';
  } catch (e) {
    return '格式化失败: $e';
  }
}

Q3: 是否支持自定义缩进字符？

是的，withIndent() 方法接受任意字符串作为缩进符：

// 使用星号缩进
final encoder = JsonEncoder.withIndent('***');

---

最佳实践

统一缩进风格

在团队项目中，统一缩进风格可以提高代码一致性：

// 在项目中定义常量
const int JSON_INDENT = 2;

// 使用统一的缩进
final encoder = JsonEncoder.withIndent(' ' * JSON_INDENT);

封装工具方法

将格式化逻辑封装为工具方法，便于复用：

class JsonUtils {
  static const int _defaultIndent = 2;

  static String prettyPrint(Object? data, {int indent = _defaultIndent}) {
    if (data == null) return 'null';
    return JsonEncoder.withIndent(' ' * indent).convert(data);
  }

  static String compactPrint(Object? data) {
    if (data == null) return 'null';
    return json.encode(data);
  }
}

结合日志框架使用

与日志框架结合，自动格式化日志输出：

class JsonLogPrinter extends LogPrinter {
  @override
  List<String> log(LogEvent event) {
    final String message = event.message.toString();
    try {
      final dynamic parsed = json.decode(message);
      return [JsonEncoder.withIndent('  ').convert(parsed)];
    } catch (e) {
      return [message];
    }
  }
}

---

总结

JSON格式化与美化是Flutter开发中不可或缺的技能。通过 dart:convert 库提供的 JsonEncoder.withIndent() 方法，我们可以轻松实现JSON的格式化和压缩。

关键要点：

1. 使用 JsonEncoder.withIndent() 进行美化
2. 使用 json.encode() 进行压缩
3. 根据场景选择合适的格式
4. 注意性能和内存使用
5. 在鸿蒙平台上注意资源限制

掌握这些技巧，可以让我们在处理JSON数据时更加高效和便捷。