使用 Python 在 Excel 中添加和自定义迷你图

一张报表里，如果每个产品的月度数据各占一行，读者需要逐行比较数字才能看出趋势。迷你图（Sparkline）把这一行数据画成一个放在单元格里的小图表：折线或柱形，不占额外位置，却能一眼看出上升、下降和异常值。

Excel 从 2010 版开始支持迷你图，它们不是普通图表对象，而是挂在工作表上的"迷你图组"——一组共享样式的迷你图。用脚本生成报表时，迷你图和单元格格式一样可以批量写入。这篇文章用 Spire.XLS for Python 演示如何创建折线、柱形和盈亏迷你图，并设置颜色、标记点、坐标轴与空单元格处理方式。

环境准备

安装 Spire.XLS 并引入模块：

pip install Spire.XLS

from spire.xls import *
from spire.xls.common import *

迷你图是 Excel 2010 之后的功能，工作簿的版本要显式设置，否则访问 SparklineGroups 会报错。下面的每个示例都先设置 workbook.Version = ExcelVersion.Version2013。

创建迷你图组

迷你图由两层对象组成：先在工作表上创建迷你图组（SparklineGroups.AddGroup），再向组里添加数据区域与显示位置。下面的示例生成一张五行产品数据表，并在 H、I 两列分别放折线和柱形迷你图：

from spire.xls import *
from spire.xls.common import *

workbook = Workbook()
workbook.Version = ExcelVersion.Version2013
workbook.CreateEmptySheets(1)
sheet = workbook.Worksheets[0]

months = ["Jan", "Feb", "Mar", "Apr", "May", "Jun"]
products = {
    "Alpha": [10, 12, 9, 15, 18, 21],
    "Beta": [8, 9, 7, 10, -2, 12],
    "Gamma": [20, 18, 22, 25, 23, 26],
    "Delta": [5, 7, 6, 9, 8, 11],
    "Epsilon": [15, 14, 16, 13, 17, 19],
}

sheet.Range["A1"].Value = "Product"
for i, month in enumerate(months):
    sheet.Range[1, i + 2].Value = month
sheet.Range["H1"].Value = "Trend"
sheet.Range["I1"].Value = "Bars"

for r, (name, values) in enumerate(products.items(), start=2):
    sheet.Range[r, 1].Value = name
    for c, value in enumerate(values):
        sheet.Range[r, c + 2].NumberValue = value

# Line sparklines in column H
line_group = sheet.SparklineGroups.AddGroup(SparklineType.Line)
line_sparklines = line_group.Add()
for r in range(2, 7):
    line_sparklines.Add(sheet.Range[r, 2, r, 7], sheet.Range[r, 8])

# Column sparklines in column I
column_group = sheet.SparklineGroups.AddGroup(SparklineType.Column)
column_sparklines = column_group.Add()
for r in range(2, 7):
    column_sparklines.Add(sheet.Range[r, 2, r, 7], sheet.Range[r, 9])

sheet.SetColumnWidth(8, 14)
sheet.SetColumnWidth(9, 12)

workbook.SaveToFile("SparklineDashboard.xlsx", ExcelVersion.Version2013)
workbook.Dispose()

sheet.Range[r, 2, r, 7] 是第 r 行 B 到 G 列的数据区域，sheet.Range[r, 8] 是迷你图所在的 H 列单元格。group.Add() 创建的是一个迷你图集合，再逐个调用 Add(dataRange, location) 把每一行绑定到对应的单元格。同一个组里的迷你图共享样式，因此"按组设置颜色"比逐个单元格设置更省事。

设置线条颜色与标记点

加载刚才的文件，通过索引取出第一个组（折线组），设置线条颜色、粗细和各标记点颜色：

from spire.xls import *
from spire.xls.common import *

workbook = Workbook()
workbook.LoadFromFile("SparklineDashboard.xlsx")
sheet = workbook.Worksheets[0]

# Style the line sparkline group
group = sheet.SparklineGroups[0]
group.SparklineColor = Color.get_Blue()
group.LineWeight = 1.5
group.ShowMarkers = True
group.MarkersColor = Color.get_Red()
group.ShowHighPoint = True
group.HighPointColor = Color.get_Green()
group.ShowLowPoint = True
group.LowPointColor = Color.get_Red()

workbook.SaveToFile("SparklineStyles.xlsx", ExcelVersion.Version2013)
workbook.Dispose()

几个常用属性的含义：

• SparklineColor 是折线本身或柱形的颜色，LineWeight 控制线宽。
• ShowMarkers 打开折线上的数据点标记，MarkersColor 指定标记颜色。
• ShowHighPoint / ShowLowPoint 分别突出最高点和最低点，对应 HighPointColor 与 LowPointColor。

高点和低点默认不显示，需要显式打开——这正好适合报表场景：数据线保持低调，极值一眼可见。

突出负值、首尾点与坐标轴

第二个组是柱形迷你图。柱形图更容易看出单月增减，负值则会向下绘制，可以单独着色：

from spire.xls import *
from spire.xls.common import *

workbook = Workbook()
workbook.LoadFromFile("SparklineDashboard.xlsx")
sheet = workbook.Worksheets[0]

# Style the column sparkline group
bars = sheet.SparklineGroups[1]
bars.SparklineColor = Color.get_Blue()
bars.ShowNegativePoint = True
bars.NegativePointColor = Color.get_Red()
bars.ShowFirstPoint = True
bars.FirstPointColor = Color.get_Orange()
bars.ShowLastPoint = True
bars.LastPointColor = Color.get_Purple()
bars.ShowHorizontalAxis = True
bars.HorizontalAxisColor = Color.get_Gray()

workbook.SaveToFile("SparklinePoints.xlsx", ExcelVersion.Version2013)
workbook.Dispose()

ShowNegativePoint 把负值柱单独标红，适合显示退款、亏损或下降月份；ShowFirstPoint 和 ShowLastPoint 用来标记起点与最新值，让读者快速定位"现在在哪里"。ShowHorizontalAxis 在零值位置画一条横轴，负值柱与正值柱的分界会更清楚。

处理空单元格

报表数据难免有缺失月份。迷你图遇到空单元格时可以断开，也可以跨过空白直接连线，两种行为由组的 EmptyCellsType 决定：

from spire.xls import *
from spire.xls.common import *

workbook = Workbook()
workbook.Version = ExcelVersion.Version2013
workbook.CreateEmptySheets(1)
sheet = workbook.Worksheets[0]

sheet.Range["A1"].Value = "Series"
for i, month in enumerate(["Jan", "Feb", "Mar", "Apr", "May", "Jun"]):
    sheet.Range[1, i + 2].Value = month
sheet.Range["H1"].Value = "Gaps"
sheet.Range["I1"].Value = "Line"

# Two rows with missing months
rows = {
    "A": [5, None, 7, None, 9, 11],
    "B": [3, 4, None, 6, 7, 8],
    "C": [10, 9, 8, None, 6, 5],
}
for r, (name, values) in enumerate(rows.items(), start=2):
    sheet.Range[r, 1].Value = name
    for c, value in enumerate(values):
        if value is not None:
            sheet.Range[r, c + 2].NumberValue = value

# Group 1: leave a gap where a cell is empty
gaps = sheet.SparklineGroups.AddGroup(SparklineType.Line)
gaps.EmptyCellsType = SparklineEmptyCells.Gaps
gaps_sl = gaps.Add()
for r in range(2, 5):
    gaps_sl.Add(sheet.Range[r, 2, r, 7], sheet.Range[r, 8])

# Group 2: connect across empty cells
line = sheet.SparklineGroups.AddGroup(SparklineType.Line)
line.EmptyCellsType = SparklineEmptyCells.Line
line_sl = line.Add()
for r in range(2, 5):
    line_sl.Add(sheet.Range[r, 2, r, 7], sheet.Range[r, 9])

workbook.SaveToFile("SparklineEmptyCells.xlsx", ExcelVersion.Version2013)
workbook.Dispose()

SparklineEmptyCells.Gaps 在空缺处留出断口，适合强调数据缺失；SparklineEmptyCells.Line 把空缺两侧的点直接连起来，趋势看起来连续，但也会掩盖缺失。选择哪个取决于报表想传达的信息，写进脚本后两种行为可以并排对比。

盈利与亏损迷你图

SparklineType.Stacked 绘制的是盈亏（win/loss）柱：正值向上、负值向下，适合按月对比输赢或收支。配合 NegativePointColor 可以把亏损月份染成红色：

from spire.xls import *
from spire.xls.common import *

workbook = Workbook()
workbook.Version = ExcelVersion.Version2013
workbook.CreateEmptySheets(1)
sheet = workbook.Worksheets[0]

sheet.Range["A1"].Value = "Team"
for i, month in enumerate(["Jan", "Feb", "Mar", "Apr", "May", "Jun"]):
    sheet.Range[1, i + 2].Value = month
sheet.Range["H1"].Value = "Win/Loss"

results = {
    "North": [2, -1, 3, -2, 4, 1],
    "South": [-3, 2, 1, -1, 2, -4],
    "West": [1, 3, -2, 2, -1, 5],
}
for r, (name, values) in enumerate(results.items(), start=2):
    sheet.Range[r, 1].Value = name
    for c, value in enumerate(values):
        sheet.Range[r, c + 2].NumberValue = value

group = sheet.SparklineGroups.AddGroup(SparklineType.Stacked)
group.SparklineColor = Color.get_Blue()
group.NegativePointColor = Color.get_Red()
sparklines = group.Add()
for r in range(2, 5):
    sparklines.Add(sheet.Range[r, 2, r, 7], sheet.Range[r, 8])

workbook.SaveToFile("SparklineStacked.xlsx", ExcelVersion.Version2013)
workbook.Dispose()

实用技巧

• 先设置工作簿版本：workbook.Version = ExcelVersion.Version2013 必须在访问 SparklineGroups 之前执行。
• 按组设置样式：同一组的迷你图共享颜色和标记设置，一个组一种样式，避免逐格操作。
• 组用索引访问：sheet.SparklineGroups[0]、[1] 按创建顺序取出组。
• 数据区域与位置一一对应：Add(dataRange, location) 中两者都是单行区域，绑定时保持行数一致。
• 空值策略要统一：Gaps 与 Line 只影响显示，不修改单元格内容。
• 负值单独着色：ShowNegativePoint 配合 NegativePointColor 让异常月份自动突出。
• 及时释放资源：每个工作簿用完调用 Dispose()。

结论

这篇文章演示了用 Python 在 Excel 中创建和自定义迷你图：用 SparklineGroups.AddGroup() 按折线、柱形或盈亏类型建组，用 Add(dataRange, location) 把每行数据绑定到单元格；用 SparklineColor、LineWeight、ShowMarkers 与各标记点颜色控制外观；用 ShowNegativePoint、ShowFirstPoint、ShowLastPoint 和 ShowHorizontalAxis 突出关键数据；用 EmptyCellsType 决定缺失值断开还是连线。这些设置都保存在工作簿里，生成报表时一次写入，打开即可阅读。