Python Spire.XLS生成Excel迷你图并设置空值样式

脚本专家

Excel迷你图从2010版开始支持，它不是普通图表对象，而是挂在工作表上的迷你图组，一组迷你图共享样式。用Python生成报表时，迷你图可以像单元格格式一样批量写入。本文围绕Spire.XLS for Python，梳理折线、柱形和盈亏迷你图的创建、样式设置、空单元格处理与常见注意事项。访问SparklineGroups前必须显式设置workbook.Version = ExcelVersion.Version2013，否则会报错。

环境准备：安装Spire.XLS并导入模块。

2. pip install Spire.XLS
3. from spire.xls import *
4. from spire.xls.common import *

复制代码

创建迷你图组：迷你图由组和成员两层对象组成。先用SparklineGroups.AddGroup(SparklineType.Line)创建组，再用group.Add()得到迷你图集合，最后用Add(dataRange, location)把单行数据区域绑定到单行位置单元格。同一个组里的迷你图共享样式，按组设置颜色比逐格操作更省事。下面的示例在H列放折线迷你图，在I列放柱形迷你图。

2. from spire.xls import *
3. from spire.xls.common import *
5. workbook = Workbook()
6. workbook.Version = ExcelVersion.Version2013
7. workbook.CreateEmptySheets(1)
8. sheet = workbook.Worksheets[0]
10. months = ['Jan', 'Feb', 'Mar', 'Apr', 'May', 'Jun']
11. products = {
12.     'Alpha': [10, 12, 9, 15, 18, 21],
13.     'Beta': [8, 9, 7, 10, -2, 12],
14.     'Gamma': [20, 18, 22, 25, 23, 26],
15.     'Delta': [5, 7, 6, 9, 8, 11],
16.     'Epsilon': [15, 14, 16, 13, 17, 19],
17. }
18. sheet.Range['A1'].Value = 'Product'
19. for i, month in enumerate(months):
20.     sheet.Range[1, i + 2].Value = month
21. sheet.Range['H1'].Value = 'Trend'
22. sheet.Range['I1'].Value = 'Bars'
23. for r, (name, values) in enumerate(products.items(), start=2):
24.     sheet.Range[r, 1].Value = name
25.     for c, value in enumerate(values):
26.         sheet.Range[r, c + 2].NumberValue = value
28. line_group = sheet.SparklineGroups.AddGroup(SparklineType.Line)
29. line_sparklines = line_group.Add()
30. for r in range(2, 7):
31.     line_sparklines.Add(sheet.Range[r, 2, r, 7], sheet.Range[r, 8])
33. column_group = sheet.SparklineGroups.AddGroup(SparklineType.Column)
34. column_sparklines = column_group.Add()
35. for r in range(2, 7):
36.     column_sparklines.Add(sheet.Range[r, 2, r, 7], sheet.Range[r, 9])
38. sheet.SetColumnWidth(8, 14)
39. sheet.SetColumnWidth(9, 12)
40. workbook.SaveToFile('SparklineDashboard.xlsx', ExcelVersion.Version2013)
41. workbook.Dispose()

复制代码

设置线条颜色与标记点：加载文件后通过索引取出组。SparklineColor设置折线或柱形颜色，LineWeight控制线宽；ShowMarkers打开数据点标记，MarkersColor指定标记颜色；ShowHighPoint和ShowLowPoint分别突出最高点和最低点，对应HighPointColor与LowPointColor。高点和低点默认不显示，需要显式打开，适合让数据线保持低调、极值一眼可见。柱形组还可以用ShowNegativePoint和NegativePointColor单独标红负值，用ShowFirstPoint、ShowLastPoint标记起点与最新值，用ShowHorizontalAxis在零值位置画横轴。

2. workbook = Workbook()
3. workbook.LoadFromFile('SparklineDashboard.xlsx')
4. sheet = workbook.Worksheets[0]
6. line_group = sheet.SparklineGroups[0]
7. line_group.SparklineColor = Color.get_Blue()
8. line_group.LineWeight = 1.5
9. line_group.ShowMarkers = True
10. line_group.MarkersColor = Color.get_Red()
11. line_group.ShowHighPoint = True
12. line_group.HighPointColor = Color.get_Green()
13. line_group.ShowLowPoint = True
14. line_group.LowPointColor = Color.get_Red()
16. bars = sheet.SparklineGroups[1]
17. bars.SparklineColor = Color.get_Blue()
18. bars.ShowNegativePoint = True
19. bars.NegativePointColor = Color.get_Red()
20. bars.ShowFirstPoint = True
21. bars.FirstPointColor = Color.get_Orange()
22. bars.ShowLastPoint = True
23. bars.LastPointColor = Color.get_Purple()
24. bars.ShowHorizontalAxis = True
25. bars.HorizontalAxisColor = Color.get_Gray()
27. workbook.SaveToFile('SparklineStyles.xlsx', ExcelVersion.Version2013)
28. workbook.Dispose()

复制代码

处理空单元格：报表数据可能有缺失月份。迷你图遇到空单元格时，可以用组的EmptyCellsType决定断开还是跨过空白连线。SparklineEmptyCells.Gaps在空缺处留出断口，适合强调数据缺失；SparklineEmptyCells.Line把空缺两侧的点直接连起来，趋势看起来连续，但会掩盖缺失。两种设置只影响显示，不修改单元格内容。

2. gaps = sheet.SparklineGroups.AddGroup(SparklineType.Line)
3. gaps.EmptyCellsType = SparklineEmptyCells.Gaps
4. gaps_sl = gaps.Add()
5. for r in range(2, 5):
6.     gaps_sl.Add(sheet.Range[r, 2, r, 7], sheet.Range[r, 8])
8. line = sheet.SparklineGroups.AddGroup(SparklineType.Line)
9. line.EmptyCellsType = SparklineEmptyCells.Line
10. line_sl = line.Add()
11. for r in range(2, 5):
12.     line_sl.Add(sheet.Range[r, 2, r, 7], sheet.Range[r, 9])

复制代码

盈利与亏损迷你图：SparklineType.Stacked绘制盈亏柱，正值向上、负值向下，适合按月对比输赢或收支。配合NegativePointColor可以把亏损月份染成红色。

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

复制代码

实用技巧与排查要点：先设置workbook.Version，必须在访问SparklineGroups之前完成；同一组的迷你图共享颜色和标记设置，建议按组设置样式；组用索引访问，sheet.SparklineGroups[0]、[1]按创建顺序取出；Add(dataRange, location)中数据区域与位置都是单行区域，绑定时保持行数一致；Gaps与Line只影响显示，不修改单元格内容；ShowNegativePoint配合NegativePointColor让异常月份自动突出；每个工作簿用完调用Dispose()释放资源。

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

热心网友2

感谢分享，这篇把迷你图的“组—成员”两层结构讲得很清楚，尤其是同一个组共享样式、按组设置颜色比逐格操作省事这一点，确实是实际写报表时最容易忽略的地方。workbook.Version 必须显式设成 Version2013 那个坑也很关键，不设访问 SparklineGroups 直接报错，新手很容易卡在这里。 不过标题里提到了空值样式，正文到柱形组那段设置（ShowHorizontalAxis 之后就截断在“b”了）似乎还没展开，空单元格的处理方式和相关属性没看到，不知道是不是发帖时被截掉了。这块其实挺实用的，比如数据源里有空白或者零值时，折线是断开、连过去还是当零处理，报表观感差别很大，如果后面能补上就完整了。 另外想请教一下：同时创建折线组和柱形组之后，通过 SparklineGroups[0]、[1] 取组是不是就按创建顺序来的？如果后面再往同一个工作表里加第三组，索引会不会乱，还是说更稳妥的做法是给每个组单独记一下引用？

热心网友2

感谢分享，这篇把迷你图的组和成员两层结构讲得很清楚，尤其是同一个组共享样式、按组设置颜色这点，比自己逐格试省事多了。代码里显式设置 workbook.Version = ExcelVersion.Version2013 这个坑也很关键，之前不设置直接访问 SparklineGroups 确实会报错。 有个小疑问：标题里提到了“设置空值样式”，但正文最后好像截断了，柱形组那段在 ShowHorizontalAxis 之后就结束了，没看到空单元格处理的具体属性和示例。方便的话期待楼主补全这一块，比如空值是按空白显示、还是按零值处理，以及对应的设置方式。另外高点和低点默认不显示、需要显式打开的提醒很实用，正好避免了我之前以为设了颜色就能看到标记的误会。

热心网友2

楼主的思路整理得挺清楚，尤其是先设 workbook.Version = ExcelVersion.Version2013 这一点。我之前没设版本直接访问 SparklineGroups 就踩过坑，报错信息还不太直观，很容易卡住。 另外一个我觉得很实用的点是按组设置样式。迷你图本质上是组级对象，同一组共享颜色和标记设置，所以先 AddGroup 再批量 Add，比一个个单元格去改要省事得多，代码也更好维护。示例里折线组用 ShowHighPoint/ShowLowPoint 突出极值、柱形组用 ShowNegativePoint 标红负值，这两个用法在报表场景里很常见，效果也比单纯一条线明显。 不过正文好像到柱形那段被截断了，标题里提到的空值样式没看到具体写法。想请教一下：空单元格是设置在组上的 DisplayEmptyCellsAs（Gap / Zero 之类）吗？另外线型和标记颜色在保存后再加载还能不能完整保留，楼主有没有遇到过重新打开后样式丢失的情况？