Python 实现 Excel 转 Markdown，支持工作表、单元格区域和批量处理

在一些文档自动化项目中，Excel 和 Markdown 往往会同时出现。Excel 负责整理和维护数据，而 Markdown 则更适合放在 README、项目文档、博客或 Git 仓库中。

如果只是偶尔转换一张表，直接复制内容当然也可以。但当 Excel 文件结构比较复杂，或者需要反复处理多个文件时，手工复制就显得比较麻烦。尤其是表格中的图片、超链接以及格式信息，还需要额外调整。

对于这类需求，可以直接使用 Python 完成转换。本文使用 Spire.XLS for Python 读取 Excel 文件，并将其保存为 Markdown。除了转换整个工作簿，还会介绍如何只处理某个工作表、指定单元格区域，以及如何一次性转换文件夹中的多个 Excel 文件。

环境准备

本文使用 Spire.XLS for Python 处理 Excel 文件。它是一款用于 Python 的 Excel 文档处理库，可以通过 Python 代码完成 Excel 文件的创建、读取、编辑和格式转换等操作，并且不需要本地安装 Microsoft Excel。

你可以通过 pip 安装该库：

pip install spire.xls

如果之前已经安装过，也可以直接升级：

pip install --upgrade spire.xls

该组件还提供免费版，主要用于测试和小型项目。

把整个 Excel 工作簿转换成 Markdown

要将一个 Excel 文件转换为 Markdown，只需要简单两步：使用 Workbook 加载 Excel 文件，然后调用 SaveToMarkdown() 将源文件保存为 Markdown。

下面这段代码展示了这项最基础的转换：

from spire.xls import Workbook

# 创建 Workbook 对象
workbook = Workbook()

# 加载 Excel 文件
workbook.LoadFromFile("示例.xlsx")

# 保存为 Markdown 文件
workbook.SaveToMarkdown("转md.md")

# 释放资源
workbook.Dispose()

如果 Excel 中有多个工作表，那么这种方式会按照工作簿中的内容进行整体转换。因此，它比较适合需要完整保留 Excel 数据的情况。

设置 Markdown 中的图片和链接格式

Excel 文件不一定只有纯文本和数字，实际使用的表格中还可能包含图片和超链接等对象。转换成 Markdown 后，这些内容都需要使用 Markdown 对应的语法表示。

Spire.XLS 提供了 MarkdownOptions，可以在保存时传入这个对象，对图片和超链接的处理方式进行调整。

可以参考下方的代码进行调整：

from spire.xls import Workbook, MarkdownOptions

# 创建 Workbook 对象
workbook = Workbook()

# 加载 Excel 文件
workbook.LoadFromFile("示例.xlsx")

# 创建 MarkdownOptions 对象
markdown_options = MarkdownOptions()

# 使用相对路径保存图片
markdown_options.SavePicInRelativePath = True

# 使用内联链接保存超链接
markdown_options.SaveHyperlinkAsRef = False

# 保存为 Markdown
workbook.SaveToMarkdown("自定义设置.md", markdown_options)

# 释放资源
workbook.Dispose()

在代码中，我们设置了两个选项：

SavePicInRelativePath 控制 Markdown 中图片地址的保存方式。设置为 True 时，图片使用相对路径，例如：

![Image](pic.png)

设置为 False 时，则会使用完整的文件路径。

另一个属性 SaveHyperlinkAsRef 用来决定超链接采用哪种 Markdown 写法。设置为 True 时使用引用式链接，设置为 False 时则直接生成普通的内联链接。

如果 Markdown 文件和图片需要一起放进项目目录，使用相对图片路径通常更方便；如果希望生成的 Markdown 内容直接显示链接，则可以使用内联链接。

只转换 Excel 中的某一个工作表

有时，我们不需要将整个工作簿的内容都进行处理，可能只需要某一个工作表。例如，一个工作簿可能包含销售数据、员工信息、统计结果等多个工作表，而最终文档只需要其中一张。

这时可以先找到目标工作表，再把它复制到一个新的工作簿中，最后转换这个新的工作簿。

完整代码如下：

from spire.xls import Workbook

def convert_specific_sheet(excel_file, sheet_name, output_md):
    """
    将指定工作表转换为 Markdown
    """
    workbook = Workbook()
    new_workbook = None

    try:
        # 加载 Excel 文件
        workbook.LoadFromFile(excel_file)

        # 根据名称查找工作表
        worksheet = None

        for ws in workbook.Worksheets:
            if ws.Name == sheet_name:
                worksheet = ws
                break

        if worksheet is None:
            print(f"未找到工作表 '{sheet_name}'。")
            return

        # 创建仅包含目标工作表的新工作簿
        new_workbook = Workbook()
        new_workbook.Worksheets.Clear()
        new_workbook.Worksheets.AddCopy(worksheet)

        # 保存为 Markdown
        new_workbook.SaveToMarkdown(output_md)

        print(f"工作表 '{sheet_name}' 已成功转换为 {output_md}。")

    finally:
        if new_workbook is not None:
            new_workbook.Dispose()

        workbook.Dispose()


# 使用示例
convert_specific_sheet("report.xlsx", "Sheet 1", "sheet1.md")

导出指定的单元格区域为 Markdown

除了工作簿、工作表，Spire.XLS 还支持转换指定的单元格区域为 Markdown。例如，一个报表的有效数据可能只位于 A1:C5，其他区域都是辅助计算、备注或其他内容。这时可以直接获取目标范围，将它复制到新的工作表后再转换。

示例代码如下：

from spire.xls import Workbook, CopyRangeOptions

def convert_cell_range_to_markdown(excel_file, sheet_name, cell_range, output_md):
    """
    将指定单元格区域转换为 Markdown

    示例区域："A1:C5"
    """
    workbook = Workbook()
    new_workbook = Workbook()

    try:
        # 加载原始 Excel 文件
        workbook.LoadFromFile(excel_file)

        # 获取目标工作表
        worksheet = workbook.Worksheets[sheet_name]
        if worksheet is None:
            print(f"未找到工作表 '{sheet_name}'。")
            return

        # 获取源区域
        src_range = worksheet.Range[cell_range]

        # 创建空白工作表
        new_workbook.CreateEmptySheets(1)
        new_sheet = new_workbook.Worksheets[0]

        # 创建对应大小的目标区域
        dest_range = new_sheet.Range[
            1, 1, src_range.Rows.Count, src_range.Columns.Count
        ]

        # 复制数据、公式和格式
        src_range.Copy(dest_range, CopyRangeOptions.All)

        # 保存为 Markdown
        new_workbook.SaveToMarkdown(output_md)

        print(
            f"工作表 '{sheet_name}' 中的区域 '{cell_range}' "
            f"已成功转换为 {output_md}。"
        )

    except Exception as e:
        print(f"发生错误：{e}")

    finally:
        new_workbook.Dispose()
        workbook.Dispose()


# 使用示例
convert_cell_range_to_markdown(
    "report.xlsx", "Sheet 1", "A1:C5", "cell_range.md"
)

批量转换文件夹中的多个 Excel 文件

如果需要转换的 Excel 文件比较多，一个个调用函数显然不太方便。Python 的 pathlib 可以用来遍历目录，因此我们可以把 Excel 文件的查找、转换和输出组合起来，形成一个简单的批量文件处理脚本。

下面的代码会自动查找文件夹中的 .xlsx 和 .xls 文件，并将转换结果统一保存到指定目录：

from pathlib import Path
from spire.xls import Workbook

def batch_convert_excel_to_markdown(input_folder, output_folder):
    """
    将文件夹中的所有 Excel 文件转换为 Markdown
    支持格式：.xlsx、.xls
    """
    input_dir = Path(input_folder)
    output_dir = Path(output_folder)

    # 创建输出目录
    output_dir.mkdir(parents=True, exist_ok=True)

    excel_extensions = {".xlsx", ".xls"}
    converted_count = 0

    for input_file in input_dir.iterdir():

        if not input_file.is_file():
            continue

        if input_file.name.startswith("~$"):
            continue

        if input_file.suffix.lower() not in excel_extensions:
            continue

        output_file = output_dir / f"{input_file.stem}.md"

        workbook = Workbook()

        try:
            workbook.LoadFromFile(str(input_file))

            workbook.SaveToMarkdown(str(output_file))

            converted_count += 1
            print(f"已转换：{input_file.name} -> {output_file.name}")

        except Exception as e:
            print(f"转换 {input_file.name} 失败：{e}")

        finally:
            workbook.Dispose()

    print(f"\n批量转换完成。共转换 {converted_count} 个文件。")


# 使用示例
batch_convert_excel_to_markdown("./excel_files", "./markdown_output")

总结

Excel 中的数据如果需要进入 Markdown 文档，不一定要经过手动复制和调整。借助 Spire.XLS for Python，可以直接从 Python 脚本中完成这一转换。对于简单需求，直接调用 SaveToMarkdown() 即可；如果只需要部分内容，可以先筛选工作表或者指定单元格区域；面对大量 Excel 文件时，则可以进一步结合 Python 的文件操作功能进行批量转换。

这样就可以把 Excel 数据处理和 Markdown 文档生成连接起来，更适合用于自动生成项目文档、整理数据资料以及构建自动化发布流程。主页还有更多 Excel 文件的自动化处理教程，欢迎浏览！