欢迎加入开源鸿蒙跨平台社区：https://openharmonycrossplatform.csdn.net

前言

在 OpenHarmony 应用中，如果我们需要编写自动化脚本、动态修改应用的本地配置文件，或者开发一个专门管理鸿蒙 oh-package.json5（其结构与 YAML 类似）的工具，你会发现直接使用 jsonEncode 转换后会丢失所有的注释和原有的排版缩进。

yaml_edit 正是为了解决这个问题。它能带上下文地修改 YAML 文档，就像你在记事本里手动更改某一行一样，它能完美保留文件原有的注释、空格和缩进，是工具开发者保持代码“整洁”的必选。

一、核心技术原理

不同于普通的序列化，yaml_edit 维护了一个“编辑操作链”。它会解析 YAML 的源映射（Source Map），精准锁定要修改的节点位置。

二、核心 API 实战

2.1 创建编辑器并修改

import 'package:yaml_edit/yaml_edit.dart';

void basicUsage() {
  final yamlText = """
# 鸿蒙应用配置
name: my_ohos_app
version: 1.0.0 # 💡 当前稳定版
""";

  final editor = YamlEditor(yamlText);
  
  // 💡 修改版本号，保持注释不变
  editor.update(['version'], '2.0.0');
  
  print(editor.toString());
}

2.2 删除指定的键值对

editor.remove(['unused_key']);

2.3 在列表中插入元素

// yaml: abilities: [A, B]
editor.appendToList(['abilities'], 'C');

三、OpenHarmony 平台适配

3.1 跨端脚本编写

💡 技巧：如果你在利用 Flutter 编写专门给鸿蒙开发者使用的 Mac/Windows 端辅助工具（如批量更新多个 HAP 模块的配置），yaml_edit 是最稳健的后端引擎，能确保它修改后的配置文件对鸿蒙主编辑器（DevEco Studio）十分友好。

3.2 鸿蒙沙箱内应用

在真机沙箱环境下，如果需要动态修改配置文件并保存，由于它是纯 Dart 解析，不需要额外的 C++ 编译，非常适合集成在鸿蒙应用的“设置同步”或“热配置更新”功能中。

四、完整实战示例：鸿蒙模块版本同步器

本示例展示如何编写一个脚本，自动读取并安全更新一组鸿蒙配置文件中的作者信息。

import 'package:yaml_edit/yaml_edit.dart';

class OhosYamlManager {
  String _configContent = """
# HarmonyOS Module Configuration
module:
  name: entry_module
  author: "unknown" # 💡 这里的注释必须保留
  dependencies:
    - utils_har
""";

  void updateAuthor(String newAuthor) {
    print('--- 正在更新鸿蒙模块元数据 ---');
    final editor = YamlEditor(_configContent);

    // 1. 精准更新嵌套字段
    editor.update(['module', 'author'], newAuthor);

    // 2. 添加一个新的依赖项
    editor.appendToList(['module', 'dependencies'], 'ui_hsp');

    _configContent = editor.toString();
    print(_configContent);
  }
}

void main() {
  var manager = OhosYamlManager();
  manager.updateAuthor("HarmonyExpert");
}

五、总结

yaml_edit 软件包在“数据持久化”和“自动化工具”领域具有不可替代的地位。它不仅具备读写能力，更具备“尊重原始格式”的高级修养。对于对代码和配置一致性有严格要求的鸿蒙大型工程，它是实现“程序化运维配置”的最佳实践。