🗺️ 用 Python 操作 XMind：从读懂到生成的完整入门指南

很多人都会用 XMind 画思维导图，但一旦进入“工程化”阶段，往往会遇到这些问题：

想把 XMind 转成 Markdown / CSV / 测试用例
想根据 Excel、接口数据自动生成一份脑图
想在测试平台或内部工具中实现“一键导出 .xmind 文件”

这篇文章的目标很明确：

讲清楚 XMind 文件是什么、它在程序中长什么样，以及如何用 Python 读取和生成 XMind 文件。

1. XMind 文件是什么

在写任何代码之前，首先要回答一个问题：XMind 文件在技术层面到底是什么？

1.1 `.xmind` 的本质

.xmind 文件本质上是一个 ZIP 压缩包。

你可以直接验证：将 demo.xmind 重命名为 demo.zip 并解压查看内容。

需要特别注意的是，不同版本的 XMind，核心内容文件并不相同：

XMind 8（经典版 / Legacy）：主要内容在 content.xml
XMind Zen / 2024（新版）：主要内容在 content.json

换句话说，真正的思维导图结构，一定存在于 XML 或 JSON 文件中。

2. XMind 的数据结构

理解 XMind 的第二步，是理解它在程序中的数据形态。

2.1 思维导图是一棵树

无论底层是 XML 还是 JSON，XMind 在逻辑上都是一棵树结构（Tree）。

例如，一个简单的脑图：

测试计划
 ├── 功能测试
 │    ├── 登录
 │    └── 注册
 └── 性能测试

在 Python 中，可以用类似下面的结构表示：

{
  "title": "测试计划",
  "topics": [
    {
      "title": "功能测试",
      "topics": [
        {"title": "登录"},
        {"title": "注册"}
      ]
    },
    {"title": "性能测试"}
  ]
}

只要把 XMind 理解为「节点 + 子节点」的树结构，
后续的读取、转换和生成，本质上都是树的遍历和重组。

3. 将 XMind 解析为可编程数据

在理解文件结构之后，下一步是：如何把 XMind 转成程序可以直接处理的数据结构。

3.1 使用 xmindparser

xmindparser 是一个用于解析 .xmind 文件的 Python 开源库，支持旧版和新版 XMind。

pip install xmindparser

3.2 解析为 Python 字典

from xmindparser import xmind_to_dict

# 它会自动识别 XML 或 JSON 格式并返回统一的 Python List/Dict
xmind_data = xmind_to_dict("demo.xmind")

# 返回结果通常是 list，每个元素对应一个画布（sheet）
print(xmind_data[0]["topic"]["title"])

解析完成后，你得到的是标准的 Python dict / list 结构，可以继续用于：

导出 Markdown / CSV
生成测试用例
接入自动化或测试平台系统

4. 使用 Python 生成 XMind

当你可以解析 XMind 之后，反向生成就是一个自然的问题：

如何根据结构化数据，生成一个可以正常打开的 XMind 文件。

4.1 通过 XML 生成 XMind（XMind 8）

下面示例展示的是一个最小可用版本，只保证层级结构正确，不包含样式、图标、备注等高级能力。

import xml.etree.ElementTree as ET
import zipfile
import json


def build_content_xml(tree_data):
    root = ET.Element("xmap-content", {"version": "2.0"})
    sheet = ET.SubElement(root, "sheet", {"id": "sheet-1"})

    root_topic = ET.SubElement(sheet, "topic", {"id": "root"})
    ET.SubElement(root_topic, "title").text = tree_data["title"]

    def add_topics(parent, topics):
        if not topics:
            return
        children = ET.SubElement(parent, "children")
        topics_el = ET.SubElement(children, "topics", {"type": "attached"})
        for i, t in enumerate(topics):
            topic = ET.SubElement(topics_el, "topic", {"id": f"t-{i}"})
            ET.SubElement(topic, "title").text = t["title"]
            add_topics(topic, t.get("topics", []))

    add_topics(root_topic, tree_data.get("topics", []))
    return ET.tostring(root, encoding="utf-8", xml_declaration=True)


def save_as_xmind(filename, xml_content):
    with zipfile.ZipFile(filename, "w", zipfile.ZIP_DEFLATED) as z:
        z.writestr("content.xml", xml_content)
        # 必须包含 manifest.json 声明，否则 XMind 打不开
        z.writestr(
            "manifest.json",
            json.dumps({"file-entries": {"content.xml": {}, "manifest.json": {}}})
        )

4.2 使用 SDK 生成 XMind（新版）

对于 XMind Zen / 2024，更推荐使用官方 SDK。

pip install XMind-SDK-Python

import xmind

workbook = xmind.load("new.xmind")
sheet = workbook.getPrimarySheet()
root_topic = sheet.getRootTopic()
root_topic.setTitle("自动化测试计划")

sub = root_topic.addSubTopic()
sub.setTitle("接口测试")
sub.setMarkerId("priority-1") # 设置优先级图标

xmind.save(workbook, "test_plan.xmind")