使用 Python 管理演示文稿中的图表数据标签
简介
数据标签显示图表系列和单个数据点的信息,帮助读者识别数值并了解图表。本文解释了如何格式化数值、显示百分比、读取标签文本、在轴最大值之外控制标签、调整类别轴标签间距以及定位饼图标签。
计数可见数据标签
使用getCountOfVisibleDataLabels检查在发布演示文稿之前有多少数据标签已启用显示。不同于返回集合中标签总数的getCount,它会考虑系列默认设置和各个标签的设置。
此示例创建一个包含一个系列和三个数据点的柱状图。它通过getLabels访问系列的标签集合,并在设置更改时打印可见计数:0, 3, 2, 3。总计数保持为3。
import jpype
import asposeslides
if not jpype.isJVMStarted():
jpype.startJVM()
from asposeslides.api import ChartType, Presentation
presentation = Presentation()
try:
slide = presentation.getSlides().get_Item(0)
chart = slide.getShapes().addChart(ChartType.ClusteredColumn, 50, 50, 500, 300)
chart.getChartData().getSeries().clear()
chart.getChartData().getCategories().clear()
workbook = chart.getChartData().getChartDataWorkbook()
series_cell = workbook.getCell(0, 0, 1, "Values")
series = chart.getChartData().getSeries().add(series_cell, chart.getType())
for i in range(3):
category_cell = workbook.getCell(0, i + 1, 0, f"Category {i + 1}")
chart.getChartData().getCategories().add(category_cell)
value_cell = workbook.getCell(0, i + 1, 1, jpype.JDouble((i + 1) * 10))
series.getDataPoints().addDataPointForBarSeries(value_cell)
labels = series.getLabels()
print(f"Total: {labels.getCount()}; visible: {labels.getCountOfVisibleDataLabels()}") # 总计: 3; 可见: 0
labels.getDefaultDataLabelFormat().setShowValue(True)
print(f"Visible: {labels.getCountOfVisibleDataLabels()}") # 可见: 3
labels.get_Item(1).getDataLabelFormat().setShowValue(False)
print(f"Visible: {labels.getCountOfVisibleDataLabels()}") # 可见: 2
labels.get_Item(1).getDataLabelFormat().setShowLegendKey(True)
print(f"Visible: {labels.getCountOfVisibleDataLabels()}") # 可见: 3
finally:
presentation.dispose()
系列的getDefaultDataLabelFormat提供默认设置。向setShowValue传入True会为所有三个标签显示数值。通过某个标签的getDataLabelFormat传入False会覆写该标签的设置。向setShowLegendKey传入True会使该标签再次计入可见标签,即使其数值仍被隐藏。
可见计数反映了可见性设置,它并不衡量标签是否重叠、被裁剪或在渲染的图表中是否可读。
在图表数据标签中设置数据精度
使用setNumberFormatOfValues格式化系列数值。此示例创建一个带默认数据的折线图,显示其数据表,并为第一个系列启用数值标签。格式#,##0.00显示千位分隔符和两位小数,而不改变底层数值。
import jpype
import asposeslides
if not jpype.isJVMStarted():
jpype.startJVM()
from asposeslides.api import ChartType, Presentation, SaveFormat
presentation = Presentation()
try:
slide = presentation.getSlides().get_Item(0)
chart = slide.getShapes().addChart(ChartType.Line, 50, 50, 450, 300)
chart.setDataTable(True)
series = chart.getChartData().getSeries().get_Item(0)
series.setNumberFormatOfValues("#,##0.00")
series.getLabels().getDefaultDataLabelFormat().setShowValue(True)
presentation.save("PrecisionOfDatalabels_out.pptx", SaveFormat.Pptx)
finally:
presentation.dispose()
要格式化图表嵌入工作簿中的数字单元格,请参阅Set Custom Number Formats for Workbook Cells。该示例还展示了数值标签遵循其源单元格格式,同时保留存储的数值。
将百分比显示为标签
对于堆积柱形图,将每个数值计算为其类别总和的百分比,并将文本分配给getTextFrameForOverriding返回的文本框。此示例使用默认图表数据,并以8磅字体显示保留两位小数的百分比。总和为零的类别将被跳过,以避免除以零。如果图表数据更改,需要重新计算自定义标签文本。
import jpype
import asposeslides
if not jpype.isJVMStarted():
jpype.startJVM()
from asposeslides.api import ChartType, Portion, Presentation, SaveFormat
presentation = Presentation()
try:
slide = presentation.getSlides().get_Item(0)
chart = slide.getShapes().addChart(ChartType.StackedColumn, 20, 20, 400, 400)
chart_series = chart.getChartData().getSeries()
category_totals = [0.0] * chart.getChartData().getCategories().size()
for category_index in range(len(category_totals)):
for series_index in range(chart_series.size()):
data_point = chart_series.get_Item(series_index).getDataPoints().get_Item(category_index)
category_totals[category_index] += float(data_point.getValue().getData())
for series_index in range(chart_series.size()):
series = chart_series.get_Item(series_index)
series.getLabels().getDefaultDataLabelFormat().setShowLegendKey(False)
for point_index in range(series.getDataPoints().size()):
data_point = series.getDataPoints().get_Item(point_index)
label = data_point.getLabel()
if category_totals[point_index] == 0:
print(f"Cannot calculate a percentage for category {point_index}: the total is zero.")
continue
point_percentage = float(data_point.getValue().getData()) / category_totals[point_index] * 100
portion = Portion()
portion.setText(f"{point_percentage:.2f} %")
portion.getPortionFormat().setFontHeight(8)
label.getTextFrameForOverriding().setText("")
paragraph = label.getTextFrameForOverriding().getParagraphs().get_Item(0)
paragraph.getPortions().add(portion)
label_format = label.getDataLabelFormat()
label_format.setShowValue(True)
label_format.setShowSeriesName(False)
label_format.setShowPercentage(False)
label_format.setShowLegendKey(False)
label_format.setShowCategoryName(False)
label_format.setShowBubbleSize(False)
presentation.save("DisplayPercentageAsLabels_out.pptx", SaveFormat.Pptx)
finally:
presentation.dispose()
使用图表数据标签设置百分号
当数值以分数形式存储时,使用setNumberFormat显示为百分比。向setNumberFormatLinkedToSource传入False可使标签格式独立于源单元格。
此示例创建一个 100% 堆积柱形图,四个类别分别包含红色和蓝色系列。每对数值相加为 1。标签格式0.0%将 0.30 显示为 30.0%,而纵轴使用两位小数。两个系列的标签文字均为白色、10 磅。
import jpype
import asposeslides
if not jpype.isJVMStarted():
jpype.startJVM()
from asposeslides.api import ChartType, FillType, Presentation, SaveFormat
Color = jpype.JClass("java.awt.Color")
presentation = Presentation()
try:
slide = presentation.getSlides().get_Item(0)
chart = slide.getShapes().addChart(ChartType.PercentsStackedColumn, 20, 20, 500, 400)
chart.getAxes().getVerticalAxis().setNumberFormatLinkedToSource(False)
chart.getAxes().getVerticalAxis().setNumberFormat("0.00%")
chart.getChartData().getSeries().clear()
chart.getChartData().getCategories().clear()
workbook = chart.getChartData().getChartDataWorkbook()
worksheet_index = 0
for i in range(4):
category_cell = workbook.getCell(worksheet_index, i + 1, 0, f"Category {i + 1}")
chart.getChartData().getCategories().add(category_cell)
series_names = ["Reds", "Blues"]
series_colors = [Color.RED, Color.BLUE]
values = [[0.30, 0.50, 0.80, 0.65], [0.70, 0.50, 0.20, 0.35]]
for i, series_name in enumerate(series_names):
series_cell = workbook.getCell(worksheet_index, 0, i + 1, series_name)
series = chart.getChartData().getSeries().add(series_cell, chart.getType())
for j, value in enumerate(values[i]):
value_cell = workbook.getCell(worksheet_index, j + 1, i + 1, jpype.JDouble(value))
series.getDataPoints().addDataPointForBarSeries(value_cell)
series.getFormat().getFill().setFillType(FillType.Solid)
series.getFormat().getFill().getSolidFillColor().setColor(series_colors[i])
label_format = series.getLabels().getDefaultDataLabelFormat()
label_format.setShowValue(True)
label_format.setNumberFormatLinkedToSource(False)
label_format.setNumberFormat("0.0%")
portion_format = label_format.getTextFormat().getPortionFormat()
portion_format.setFontHeight(10)
portion_format.getFillFormat().setFillType(FillType.Solid)
portion_format.getFillFormat().getSolidFillColor().setColor(Color.WHITE)
presentation.save("SetDataLabelsPercentageSign_out.pptx", SaveFormat.Pptx)
finally:
presentation.dispose()
读取数据标签的实际文本
使用getActualLabelText检索数据标签设置生成的文本。这在提取报告标签、搜索演示文稿内容或验证生成的图表时非常有用。在下面的示例中,默认的data label format将每个类别名称、系列名称和数值组合在一起。一个点将其数值格式化为百分比,另一个使用来自getTextFrameForOverriding的自定义文本。
import jpype
import asposeslides
if not jpype.isJVMStarted():
jpype.startJVM()
from asposeslides.api import ChartType, Presentation
presentation = Presentation()
try:
slide = presentation.getSlides().get_Item(0)
chart = slide.getShapes().addChart(ChartType.ClusteredColumn, 20, 20, 500, 300)
chart.getChartData().getSeries().clear()
chart.getChartData().getCategories().clear()
workbook = chart.getChartData().getChartDataWorkbook()
first_category_cell = workbook.getCell(0, 1, 0, "Q1")
chart.getChartData().getCategories().add(first_category_cell)
second_category_cell = workbook.getCell(0, 2, 0, "Q2")
chart.getChartData().getCategories().add(second_category_cell)
north_series_cell = workbook.getCell(0, 0, 1, "North")
north = chart.getChartData().getSeries().add(north_series_cell, chart.getType())
north_first_value_cell = workbook.getCell(0, 1, 1, jpype.JDouble(0.25))
north.getDataPoints().addDataPointForBarSeries(north_first_value_cell)
north_second_value_cell = workbook.getCell(0, 2, 1, jpype.JDouble(0.75))
north.getDataPoints().addDataPointForBarSeries(north_second_value_cell)
south_series_cell = workbook.getCell(0, 0, 2, "South")
south = chart.getChartData().getSeries().add(south_series_cell, chart.getType())
south_first_value_cell = workbook.getCell(0, 1, 2, jpype.JDouble(0.40))
south.getDataPoints().addDataPointForBarSeries(south_first_value_cell)
south_second_value_cell = workbook.getCell(0, 2, 2, jpype.JDouble(0.60))
south.getDataPoints().addDataPointForBarSeries(south_second_value_cell)
for series in chart.getChartData().getSeries():
label_format = series.getLabels().getDefaultDataLabelFormat()
label_format.setShowCategoryName(True)
label_format.setShowSeriesName(True)
label_format.setShowValue(True)
north.getLabels().get_Item(1).getDataLabelFormat().setNumberFormatLinkedToSource(False)
north.getLabels().get_Item(1).getDataLabelFormat().setNumberFormat("0%")
south.getLabels().get_Item(0).getTextFrameForOverriding().setText("Reviewed")
for series in chart.getChartData().getSeries():
for point in series.getDataPoints():
label = point.getLabel()
if not label.isVisible():
continue
print(f"Value: {point.getValue().getData()}; label: {label.getActualLabelText()}")
finally:
presentation.dispose()
数据点中存储的数值仍为0.75,即使其标签显示为75%并带有类别和系列名称。自定义文本会替换生成的标签文本。getActualLabelText在两种情况下都会返回最终的标签字符串。若只想提取可见标签,请像上文所示单独检查isVisible。
在轴最大值之外控制数据标签
当手动限制坐标轴范围时,某些数据点可能超过最大值。使用setShowDataLabelsOverMaximum控制是否显示它们的数据标签。此设置仅更改标签可见性,不会改变坐标轴范围或底层数据值。
下面的示例创建一个值为 60 和 120 的二维簇状柱形图。它向setAutomaticMaxValue传入False,并在纵轴上使用setMaxValue将最大值设为 100。第一张幻灯片允许标签超出最大值;该幻灯片的副本则禁用这些标签。两张幻灯片均保存为DataLabelsOverMaximum.pptx。
使用setShowValue启用数值标签。图表级别的设置本身不会启用数值显示,也不会覆盖单个标签已禁用的数值显示。此示例为整个系列启用数值,并使用setPosition将标签放置在每列的外侧端点。
import jpype
import asposeslides
if not jpype.isJVMStarted():
jpype.startJVM()
from asposeslides.api import ChartType, LegendDataLabelPosition, Presentation, SaveFormat
presentation = Presentation()
try:
slide = presentation.getSlides().get_Item(0)
chart = slide.getShapes().addChart(ChartType.ClusteredColumn, 50, 50, 600, 400)
chart.setLegend(False)
chart.getChartData().getSeries().clear()
chart.getChartData().getCategories().clear()
workbook = chart.getChartData().getChartDataWorkbook()
first_category = workbook.getCell(0, 1, 0, "Within range")
second_category = workbook.getCell(0, 2, 0, "Above maximum")
chart.getChartData().getCategories().add(first_category)
chart.getChartData().getCategories().add(second_category)
series_name = workbook.getCell(0, 0, 1, "Values")
series = chart.getChartData().getSeries().add(series_name, chart.getType())
first_value = workbook.getCell(0, 1, 1, jpype.JDouble(60))
second_value = workbook.getCell(0, 2, 1, jpype.JDouble(120))
series.getDataPoints().addDataPointForBarSeries(first_value)
series.getDataPoints().addDataPointForBarSeries(second_value)
series.getLabels().getDefaultDataLabelFormat().setShowValue(True)
series.getLabels().getDefaultDataLabelFormat().setPosition(LegendDataLabelPosition.OutsideEnd)
chart.getAxes().getVerticalAxis().setAutomaticMaxValue(False)
chart.getAxes().getVerticalAxis().setMaxValue(100)
chart.setShowDataLabelsOverMaximum(True)
second_slide = presentation.getSlides().addClone(slide)
second_chart = second_slide.getShapes().get_Item(0)
second_chart.setShowDataLabelsOverMaximum(False)
presentation.save("DataLabelsOverMaximum.pptx", SaveFormat.Pptx)
finally:
presentation.dispose()
下图显示了 Microsoft PowerPoint 渲染的已保存幻灯片。设置为True时,标签120在上边界可见;设置为False时,该标签隐藏。标签60保持可见,坐标轴最大值仍为100,第二个数据点在两种情况下均为120。
| setShowDataLabelsOverMaximum(True) | setShowDataLabelsOverMaximum(False) |
|---|---|
![]() |
![]() |
Chart Type
此示例使用一个带值轴的二维柱形图。没有值轴的图表,例如饼图和环形图,没有可以以这种方式限制的轴最大值。设置标签与坐标轴的距离
使用setLabelOffset控制类别坐标轴标签与坐标轴之间的距离。该值为轴标签最大字体大小的百分比。此示例创建一个簇状柱形图,并将水平轴标签偏移设为 500。此设置影响类别轴标签,而非附加在单个数据点上的标签。
import jpype
import asposeslides
if not jpype.isJVMStarted():
jpype.startJVM()
from asposeslides.api import ChartType, Presentation, SaveFormat
presentation = Presentation()
try:
slide = presentation.getSlides().get_Item(0)
chart = slide.getShapes().addChart(ChartType.ClusteredColumn, 20, 20, 500, 300)
chart.getAxes().getHorizontalAxis().setLabelOffset(500)
presentation.save("SetCategoryAxisLabelDistance_out.pptx", SaveFormat.Pptx)
finally:
presentation.dispose()
调整标签位置
在饼图中,调整数据标签位置以改善间距并为引导线留出空间。
此示例显示第一个数据点的数值,将其标签放置在切片外部,并使用setX和setY调整水平和垂直偏移。这些偏移量分别相对于图表的宽度和高度。
import jpype
import asposeslides
if not jpype.isJVMStarted():
jpype.startJVM()
from asposeslides.api import ChartType, LegendDataLabelPosition, Presentation, SaveFormat
presentation = Presentation()
try:
slide = presentation.getSlides().get_Item(0)
chart = slide.getShapes().addChart(ChartType.Pie, 50, 50, 200, 200)
series = chart.getChartData().getSeries()
label = series.get_Item(0).getLabels().get_Item(0)
label.getDataLabelFormat().setShowValue(True)
label.getDataLabelFormat().setPosition(LegendDataLabelPosition.OutsideEnd)
label.setX(0.71)
label.setY(0.04)
presentation.save("presentation.pptx", SaveFormat.Pptx)
finally:
presentation.dispose()

格式化引导线
当饼图标签位于切片外侧时,引导线帮助读者将每个数值与对应切片对应。使用对比色和稍粗的线条可以使这些连接更易辨认,而透明度和虚线样式则使线条在视觉上不显突兀。
使用getLeaderLinesFormat在系列数据标签集合层面格式化引导线。series.getLabels().getLeaderLinesFormat().getLine()中的设置适用于整个集合,而非单个标签。
此示例创建一个默认数据的饼图,在切片外显示数值,并启用setShowLeaderLines。它使用setX和setY偏移(以图表宽高的比例表示)将两个标签移动得更远。无需输入演示文稿。
线条的getFillFormat设置为实心蓝色,透明度为 191/255,约 25% 透明度。setWidth将粗细设为 2 磅,setDashStyle将线条设为虚线。
import jpype
import asposeslides
if not jpype.isJVMStarted():
jpype.startJVM()
from asposeslides.api import ChartType, FillType, LegendDataLabelPosition, LineDashStyle, Presentation, SaveFormat
Color = jpype.JClass("java.awt.Color")
presentation = Presentation()
try:
slide = presentation.getSlides().get_Item(0)
chart = slide.getShapes().addChart(ChartType.Pie, 80, 50, 560, 400)
chart.setLegend(False)
series = chart.getChartData().getSeries().get_Item(0)
label_format = series.getLabels().getDefaultDataLabelFormat()
label_format.setShowValue(True)
label_format.setPosition(LegendDataLabelPosition.OutsideEnd)
label_format.setShowLeaderLines(True)
# 将两个标签从切片向外移动更远。
series.getLabels().get_Item(0).setX(0.10)
series.getLabels().get_Item(0).setY(-0.05)
series.getLabels().get_Item(1).setX(-0.10)
series.getLabels().get_Item(1).setY(0.05)
line = series.getLabels().getLeaderLinesFormat().getLine()
line.getFillFormat().setFillType(FillType.Solid)
color = Color(30, 90, 160, 191)
line.getFillFormat().getSolidFillColor().setColor(color)
line.setWidth(2)
line.setDashStyle(LineDashStyle.Dash)
presentation.save("FormattedLeaderLines.pptx", SaveFormat.Pptx)
finally:
presentation.dispose()
启用引导线并不能保证每个标签都有线条。可见性取决于标签位置和图表的布局行为。在本例中,两个被移位的标签显示了引导线;靠近切片的标签则不需要。
下图显示了使用 Aspose.Slides 渲染的已保存 FormattedLeaderLines.pptx:

在柱形图上方添加多行数据标签
此示例创建一个在绘图区上方有两行数据标签的柱形图。系列 A 显示可见的列,而系列 B 和系列 C 提供额外的标签。通过移除填充和轮廓来隐藏它们的列。ChartSeriesGroup.setOverlap方法将三个系列的类别中心对齐。
ChartPlotArea设置为标签行预留空间。在Chart.validateChartLayout计算默认位置后,DataLabel.setX和DataLabel.setY保持水平对齐并应用垂直偏移,以将标签排列成两行。数字仍然是链接到系列数值的数据标签;仅行标题是单独的文本形状。
import jpype
import asposeslides
if not jpype.isJVMStarted():
jpype.startJVM()
from asposeslides.api import ChartType, FillType, LayoutTargetType, LegendDataLabelPosition, Presentation, SaveFormat, ShapeType
Color = jpype.JClass("java.awt.Color")
presentation = Presentation()
try:
slide = presentation.getSlides().get_Item(0)
chart = slide.getShapes().addChart(ChartType.ClusteredColumn, 40, 40, 640, 200)
chart.setTitle(False)
chart.setLegend(False)
chart.getTextFormat().getPortionFormat().setFontHeight(12)
chart.getChartData().getSeries().clear()
chart.getChartData().getCategories().clear()
workbook = chart.getChartData().getChartDataWorkbook()
workbook.clear(0)
categories = ["North", "South", "East", "West"]
series_names = ["Series A", "Series B", "Series C"]
series_values = [[35, 42, 28, 47], [22, 31, 19, 26], [12, 16, 14, 18]]
for category_index, category in enumerate(categories):
category_cell = workbook.getCell(0, category_index + 1, 0, category)
chart.getChartData().getCategories().add(category_cell)
for series_index, series_name in enumerate(series_names):
series_cell = workbook.getCell(0, 0, series_index + 1, series_name)
series = chart.getChartData().getSeries().add(series_cell, ChartType.ClusteredColumn)
for category_index, value in enumerate(series_values[series_index]):
value_cell = workbook.getCell(0, category_index + 1, series_index + 1, jpype.JDouble(value))
series.getDataPoints().addDataPointForBarSeries(value_cell)
if series_index > 0:
# 隐藏 B 和 C 列,但保留它们的数据标签。
series.getFormat().getFill().setFillType(FillType.NoFill)
series.getFormat().getLine().getFillFormat().setFillType(FillType.NoFill)
label_format = series.getLabels().getDefaultDataLabelFormat()
label_format.setShowValue(True)
label_format.getTextFormat().getPortionFormat().setFontHeight(12)
label_fill = label_format.getTextFormat().getPortionFormat().getFillFormat()
label_fill.setFillType(FillType.Solid)
label_fill.getSolidFillColor().setColor(Color.BLACK)
label_format.setPosition(LegendDataLabelPosition.InsideBase)
# 将所有三个系列对齐到相同的类别中心。
chart.getChartData().getSeries().get_Item(0).getParentSeriesGroup().setOverlap(jpype.JByte(100))
# 为此紧凑示例使用更少的网格线。
chart.getAxes().getVerticalAxis().setAutomaticMajorUnit(False)
chart.getAxes().getVerticalAxis().setMajorUnit(10)
# 为两行数据标签在绘图区域上方预留空间。
chart.getPlotArea().setLayoutTargetType(LayoutTargetType.Inner)
chart.getPlotArea().setX(0.15)
chart.getPlotArea().setY(0.32)
chart.getPlotArea().setWidth(0.80)
chart.getPlotArea().setHeight(0.48)
chart.validateChartLayout()
for series_index in range(1, len(series_names)):
series = chart.getChartData().getSeries().get_Item(series_index)
row_top = 0.15 if series_index == 1 else 0.03
for category_index in range(len(categories)):
data_label = series.getDataPoints().get_Item(category_index).getLabel()
# 保持默认的水平位置。Y 是相对于
# 默认标签位置的偏移,以图表高度的比例表示。
data_label.setX(0)
data_label.setY(row_top - data_label.getActualY() / chart.getHeight())
# 仅行标题是单独的文本形状。
heading_y = chart.getY() + row_top * chart.getHeight()
row_heading = slide.getShapes().addAutoShape(ShapeType.Rectangle, chart.getX(), heading_y, 85, 18)
row_heading.getFillFormat().setFillType(FillType.NoFill)
row_heading.getLineFormat().getFillFormat().setFillType(FillType.NoFill)
row_heading.addTextFrame(series_names[series_index])
row_heading.getTextFrame().getTextFrameFormat().setMarginTop(0)
row_heading.getTextFrame().getTextFrameFormat().setMarginBottom(0)
heading_format = row_heading.getTextFrame().getParagraphs().get_Item(0).getPortions().get_Item(0).getPortionFormat()
heading_format.setFontHeight(12)
heading_format.getFillFormat().setFillType(FillType.Solid)
heading_format.getFillFormat().getSolidFillColor().setColor(Color.BLACK)
presentation.save("multiple-rows-of-labels.pptx", SaveFormat.Pptx)
finally:
presentation.dispose()

常见问题
如何防止密集图表中的数据标签重叠?
结合自动标签布局、引导线和减小字体大小;必要时隐藏某些字段(例如类别),或仅对极值或关键点显示标签。
如何仅对零、负数或空值禁用标签?
在启用标签之前过滤数据点,并根据定义的规则关闭对值为 0、负数或缺失值的显示。
如何在导出为 PDF/图片时确保标签样式一致?
明确设置字体族和大小,并确认渲染环境中该字体可用,以避免回退。

