在 Python 簡報中管理圖表資料系列
概觀
A chart can store its plotted values in workbook cells or directly as numeric literals. A ChartSeries represents one set of related values, and each ChartDataPoint represents a point in that series. ChartCategory objects provide the labels or grouping values shared by the series. In charts created with default data, series names, categories, and point values use ChartDataCell objects from the chart workbook.
For a typical category chart, the default workbook uses row 0 for series names, column 0 for category names, and the remaining cells for series values. Worksheet, row, and column indexes passed to ChartDataWorkbook.getCell are zero-based. This layout is useful when you create a chart with default data, but do not assume that every existing chart uses it. For a loaded presentation, inspect the cells referenced by the series, categories, and data points before changing workbook values.
Chart settings have three different scopes:
- Series-level settings, such as ChartSeries.getFormat, provide the default appearance for all points in one series.
- Data-point settings, such as ChartDataPoint.getFormat, override the series appearance for one point.
- Group settings apply to compatible series that belong to the same ChartSeriesGroup. Access the group through ChartSeries.getParentSeriesGroup when you need to set options such as overlap or gap width.
When no explicit point or series fill is set, the chart style and theme determine the automatic appearance. When both series and point formatting are present, the point formatting takes precedence for that point.
使用數值文字設定系列值
Use numeric literals when series values come from application data or calculations and do not need worksheet cell references. Call setDataSourceTypeForValues with DataSourceType.DoubleLiterals before assigning each point’s getValue result through setAsLiteralDouble.
The collection setting controls the source type of all point values in that series. Each point value’s getDataSourceType method reports the selected type; change it through the collection setting. With Worksheet, use getAsCell to access the referenced cell. With DoubleLiterals, use getAsLiteralDouble or setAsLiteralDouble to read or write the number directly.
The following example creates a column chart with default series and categories, then assigns calculated values of 10, 20, and so on to the existing points of its first series. It saves the presentation, reopens it, and prints the stored values.
import jpype
import asposeslides
if not jpype.isJVMStarted():
jpype.startJVM()
from asposeslides.api import ChartType, DataSourceType, Presentation, SaveFormat
presentation = Presentation()
try:
slide = presentation.getSlides().get_Item(0)
chart = slide.getShapes().addChart(ChartType.ClusteredColumn, 20, 20, 500, 300)
series = chart.getChartData().getSeries().get_Item(0)
series.getDataPoints().setDataSourceTypeForValues(DataSourceType.DoubleLiterals)
for i in range(series.getDataPoints().size()):
series.getDataPoints().get_Item(i).getValue().setAsLiteralDouble((i + 1) * 10)
presentation.save("numeric_literals.pptx", SaveFormat.Pptx)
finally:
presentation.dispose()
reopened_presentation = Presentation("numeric_literals.pptx")
try:
reopened_slide = reopened_presentation.getSlides().get_Item(0)
reopened_chart = reopened_slide.getShapes().get_Item(0)
reopened_series = reopened_chart.getChartData().getSeries().get_Item(0)
for point in reopened_series.getDataPoints():
print(point.getValue().getAsLiteralDouble())
finally:
reopened_presentation.dispose()
The point value source type is separate from ChartData.getDataSourceType, which identifies the chart’s internal or external workbook configuration. Using numeric literals does not, by itself, remove the embedded workbook. In this example, the workbook remains available for category labels, series names, and the other series. See 圖表工作簿 for workbook management.
For scatter and bubble charts, use setDataSourceTypeForXValues and setDataSourceTypeForYValues to choose the sources for getXValue and getYValue. Bubble charts also use setDataSourceTypeForBubbleSizes for getBubbleSize. Set each applicable source to DoubleLiterals before assigning numbers through that value’s setAsLiteralDouble method.
設定圖表系列的重疊
ChartSeries.getOverlap reports how much bars or columns overlap in a 2D chart, from -100 through 100 percent. It is a read-only projection of the setting on the parent series group. Use ChartSeriesGroup.setOverlap to update every compatible series in that group. This option applies to chart types that display grouped bars or columns; it does not affect unrelated series groups in a combination chart.
The following example sets the overlap for the group that contains the first series:
import jpype
import asposeslides
if not jpype.isJVMStarted():
jpype.startJVM()
from asposeslides.api import ChartType, Presentation, SaveFormat
first_slide_index = 0
first_series_index = 0
overlap_percent = 30
presentation = Presentation()
try:
slide = presentation.getSlides().get_Item(first_slide_index)
# 新圖表包含範例系列、類別和數值。
chart = slide.getShapes().addChart(ChartType.ClusteredColumn, 20, 20, 500, 200)
series = chart.getChartData().getSeries().get_Item(first_series_index)
series.getParentSeriesGroup().setOverlap(overlap_percent)
presentation.save("series_overlap.pptx", SaveFormat.Pptx)
finally:
presentation.dispose()
The result:
變更系列填色
Use ChartSeries.getFormat to set the default fill for an entire series. If a point already has an explicit fill, its ChartDataPoint.getFormat setting overrides the series fill for that point.
The following example applies a solid blue fill to the first series:
import jpype
import asposeslides
if not jpype.isJVMStarted():
jpype.startJVM()
from asposeslides.api import ChartType, FillType, Presentation, SaveFormat
Color = jpype.JClass("java.awt.Color")
first_slide_index = 0
first_series_index = 0
presentation = Presentation()
try:
slide = presentation.getSlides().get_Item(first_slide_index)
chart = slide.getShapes().addChart(ChartType.ClusteredColumn, 20, 20, 500, 200)
series = chart.getChartData().getSeries().get_Item(first_series_index)
series.getFormat().getFill().setFillType(FillType.Solid)
series.getFormat().getFill().getSolidFillColor().setColor(Color.BLUE)
presentation.save("series_color.pptx", SaveFormat.Pptx)
finally:
presentation.dispose()
The result:
變更系列名稱
A series name is stored in the chart data workbook and is normally displayed in the legend. In the default workbook created for a clustered column chart, cell B1 is at row 0, column 1 and contains the name of the first series. The named variables in the following example make that structure explicit:
import jpype
import asposeslides
if not jpype.isJVMStarted():
jpype.startJVM()
from asposeslides.api import ChartType, Presentation, SaveFormat
first_slide_index = 0
worksheet_index = 0
series_name_row_index = 0
first_series_column_index = 1
presentation = Presentation()
try:
slide = presentation.getSlides().get_Item(first_slide_index)
chart = slide.getShapes().addChart(ChartType.ClusteredColumn, 20, 20, 500, 200)
workbook = chart.getChartData().getChartDataWorkbook()
series_name_cell = workbook.getCell(worksheet_index, series_name_row_index, first_series_column_index)
series_name_cell.setValue("Revenue")
presentation.save("series_name.pptx", SaveFormat.Pptx)
finally:
presentation.dispose()
You can also update the cell already referenced by ChartSeries.getName. This approach avoids assuming a particular row and column in an existing chart:
import jpype
import asposeslides
if not jpype.isJVMStarted():
jpype.startJVM()
from asposeslides.api import ChartType, Presentation, SaveFormat
first_slide_index = 0
first_series_index = 0
first_name_cell_index = 0
presentation = Presentation()
try:
slide = presentation.getSlides().get_Item(first_slide_index)
chart = slide.getShapes().addChart(ChartType.ClusteredColumn, 20, 20, 500, 200)
series = chart.getChartData().getSeries().get_Item(first_series_index)
series_name_cell = series.getName().getAsCells().get_Item(first_name_cell_index)
series_name_cell.setValue("Revenue")
presentation.save("series_name.pptx", SaveFormat.Pptx)
finally:
presentation.dispose()
The result:
從多個儲存格建立具有名稱的系列
A composite series name is useful when a product name and a reporting period are stored in separate workbook cells. For example, you can combine Product A in B1 and 2026 in C1 into a single series name while keeping both parts linked to their source cells.
Use ChartDataWorkbook.getCellCollection to retrieve the name range, then pass that collection to ChartSeriesCollection.add. The skipHiddenCells argument controls whether hidden cells are included: True excludes them, while False includes them. This example uses False to include every cell in the name range.
The following example creates a presentation with one series and two data points. Cells B1:C1 supply only the series name; A2:A3 supply the category labels, and B2:B3 supply the numeric values.
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, 50, 50, 620, 180)
chart.getChartData().getSeries().clear()
chart.getChartData().getCategories().clear()
chart.setLegend(True)
workbook = chart.getChartData().getChartDataWorkbook()
workbook.clear(0)
# 這兩個儲存格提供系列名稱。
workbook.getCell(0, 0, 1, "Product A")
workbook.getCell(0, 0, 2, "2026")
name_cells = workbook.getCellCollection("Sheet1!$B$1:$C$1", False)
series = chart.getChartData().getSeries().add(name_cells, ChartType.ClusteredColumn)
# 單獨的儲存格提供類別和數值資料點。
north_category = workbook.getCell(0, 1, 0, "North")
south_category = workbook.getCell(0, 2, 0, "South")
chart.getChartData().getCategories().add(north_category)
chart.getChartData().getCategories().add(south_category)
north_value = workbook.getCell(0, 1, 1, jpype.JInt(120))
south_value = workbook.getCell(0, 2, 1, jpype.JInt(150))
series.getDataPoints().addDataPointForBarSeries(north_value)
series.getDataPoints().addDataPointForBarSeries(south_value)
presentation.save("composite_series_name.pptx", SaveFormat.Pptx)
finally:
presentation.dispose()
The resulting series name is Product A 2026, with a space between the two cell values. The legend displays this as one entry for both columns. The image below illustrates the result:
取得自動系列填色
ChartSeries.getAutomaticSeriesColor returns the color calculated from the series index and the chart style. This is the color used when the series fill has not been explicitly defined. Calling the method reads the calculated color; it does not assign a new fill.
The following example prints the automatic color of each default series:
import jpype
import asposeslides
if not jpype.isJVMStarted():
jpype.startJVM()
from asposeslides.api import ChartType, Presentation
first_slide_index = 0
presentation = Presentation()
try:
slide = presentation.getSlides().get_Item(first_slide_index)
chart = slide.getShapes().addChart(ChartType.ClusteredColumn, 20, 20, 500, 200)
series_count = chart.getChartData().getSeries().size()
for series_index in range(series_count):
series = chart.getChartData().getSeries().get_Item(series_index)
automatic_color = series.getAutomaticSeriesColor()
print(f"Series {series_index}: {automatic_color}")
finally:
presentation.dispose()
Example output for the default chart style:
Series 0: java.awt.Color[r=79,g=129,b=189]
Series 1: java.awt.Color[r=192,g=80,b=77]
Series 2: java.awt.Color[r=155,g=187,b=89]
The exact colors depend on the chart style and theme.
設定圖表系列的反轉填色
For bar, column, and bubble series, ChartSeries.setInvertIfNegative can display negative values with a different fill. Set the regular series fill to solid, enable inversion, and assign the negative-value color through ChartSeries.getInvertedSolidFillColor. Negative numbers remain unchanged in the workbook; only their display color changes.
The following example replaces the default chart data with one series. Worksheet row 0 contains the series name, column 0 contains category names, and column 1 contains the values:
import jpype
import asposeslides
if not jpype.isJVMStarted():
jpype.startJVM()
from asposeslides.api import ChartType, FillType, Presentation, SaveFormat
Color = jpype.JClass("java.awt.Color")
first_slide_index = 0
worksheet_index = 0
header_row_index = 0
category_column_index = 0
first_series_column_index = 1
first_data_row_index = 1
category_names = ["Category 1", "Category 2", "Category 3"]
series_values = [-20, 50, -30]
presentation = Presentation()
try:
slide = presentation.getSlides().get_Item(first_slide_index)
chart = slide.getShapes().addChart(ChartType.ClusteredColumn, 20, 20, 500, 200)
chart_data = chart.getChartData()
workbook = chart_data.getChartDataWorkbook()
chart_data.getSeries().clear()
chart_data.getCategories().clear()
series_name_cell = workbook.getCell(worksheet_index, header_row_index, first_series_column_index, "Series 1")
chart_type = chart.getType()
series = chart_data.getSeries().add(series_name_cell, chart_type)
for category_index in range(len(category_names)):
data_row_index = first_data_row_index + category_index
category_name = category_names[category_index]
series_value = series_values[category_index]
category_cell = workbook.getCell(worksheet_index, data_row_index, category_column_index, category_name)
chart_data.getCategories().add(category_cell)
value_cell = workbook.getCell(worksheet_index, data_row_index, first_series_column_index, series_value)
series.getDataPoints().addDataPointForBarSeries(value_cell)
automatic_series_color = series.getAutomaticSeriesColor()
series.getFormat().getFill().setFillType(FillType.Solid)
series.getFormat().getFill().getSolidFillColor().setColor(automatic_series_color)
series.setInvertIfNegative(True)
series.getInvertedSolidFillColor().setColor(Color.RED)
presentation.save("inverted_solid_fill_color.pptx", SaveFormat.Pptx)
finally:
presentation.dispose()
The result:
You can enable inversion for one point through ChartDataPoint.setInvertIfNegative. In the following example, inversion is disabled for the series and enabled only for the selected point. The point is also assigned a negative value so that the effect is visible:
import jpype
import asposeslides
if not jpype.isJVMStarted():
jpype.startJVM()
from asposeslides.api import ChartType, FillType, Presentation, SaveFormat
Color = jpype.JClass("java.awt.Color")
first_slide_index = 0
first_series_index = 0
target_data_point_index = 2
negative_value = -30
presentation = Presentation()
try:
slide = presentation.getSlides().get_Item(first_slide_index)
chart = slide.getShapes().addChart(ChartType.ClusteredColumn, 20, 20, 500, 200)
series = chart.getChartData().getSeries().get_Item(first_series_index)
automatic_series_color = series.getAutomaticSeriesColor()
series.getFormat().getFill().setFillType(FillType.Solid)
series.getFormat().getFill().getSolidFillColor().setColor(automatic_series_color)
series.getInvertedSolidFillColor().setColor(Color.RED)
series.setInvertIfNegative(False)
data_point = series.getDataPoints().get_Item(target_data_point_index)
data_point.getValue().getAsCell().setValue(negative_value)
data_point.setInvertIfNegative(True)
presentation.save("data_point_invert_color_if_negative.pptx", SaveFormat.Pptx)
finally:
presentation.dispose()
清除特定資料點的值
To make one point empty without removing the other points, set its backing workbook cell to None. For a column chart, the plotted value is available through ChartDataPoint.getValue. The data point stays at the same category position, but the chart treats its value as blank according to the chart’s blank-value settings.
The following example clears only the second point in the first series:
import jpype
import asposeslides
if not jpype.isJVMStarted():
jpype.startJVM()
from asposeslides.api import ChartType, Presentation, SaveFormat
first_slide_index = 0
first_series_index = 0
target_data_point_index = 1
presentation = Presentation()
try:
slide = presentation.getSlides().get_Item(first_slide_index)
chart = slide.getShapes().addChart(ChartType.ClusteredColumn, 20, 20, 500, 200)
series = chart.getChartData().getSeries().get_Item(first_series_index)
data_point = series.getDataPoints().get_Item(target_data_point_index)
data_point.getValue().getAsCell().setValue(None)
presentation.save("clear_data_point_value.pptx", SaveFormat.Pptx)
finally:
presentation.dispose()
Scatter charts use separate X and Y cells, and bubble charts also use a size cell. Clear only the cell that represents the value you intend to remove. Do not call ChartDataPointCollection.clear when you want to keep the other points, because that method removes every data point from the collection.
控制空白儲存格的顯示
Hidden cells that contain values are a separate case from empty cells. To include or exclude data from hidden worksheet rows and columns, see 包含隱藏列與欄位的資料.
An empty workbook cell represents missing data; a cell containing 0 represents a known numeric value. Call ChartDataCell.setValue with None to make a cell empty. A numeric zero remains a zero regardless of the blank-cell setting.
Use Chart.setDisplayBlanksAs to choose how the chart displays empty cells. This setting applies to the whole chart. It changes how blanks are plotted, without filling the empty workbook cell with zero or an interpolated value.
The following self-contained example creates a line chart with one series, clears the value for Day 3, and saves the same chart with each mode. No input file is required. The ChartDataWorkbook uses worksheet 0, column 0 for category labels, and column 1 for values; row 0 holds the series name. The final data is 10, 20, empty, 30, 40.
import jpype
import asposeslides
if not jpype.isJVMStarted():
jpype.startJVM()
from asposeslides.api import ChartType, DisplayBlanksAsType, Presentation, SaveFormat
presentation = Presentation()
try:
slide = presentation.getSlides().get_Item(0)
chart = slide.getShapes().addChart(ChartType.LineWithMarkers, 40, 40, 640, 400)
chart_data = chart.getChartData()
workbook = chart_data.getChartDataWorkbook()
chart_data.getSeries().clear()
chart_data.getCategories().clear()
series_name_cell = workbook.getCell(0, 0, 1, "Measurements")
series = chart_data.getSeries().add(series_name_cell, chart.getType())
values = [10, 20, 25, 30, 40]
for i, value in enumerate(values):
category_cell = workbook.getCell(0, i + 1, 0, f"Day {i + 1}")
chart_data.getCategories().add(category_cell)
value_cell = workbook.getCell(0, i + 1, 1, jpype.JInt(value))
series.getDataPoints().addDataPointForLineSeries(value_cell)
# 將第 3 天真正留空，同時保留其類別和資料點。
workbook.getCell(0, 3, 1).setValue(None)
modes = [DisplayBlanksAsType.Gap, DisplayBlanksAsType.Zero, DisplayBlanksAsType.Span]
mode_names = ["Gap", "Zero", "Span"]
for mode, mode_name in zip(modes, mode_names):
chart.setDisplayBlanksAs(mode)
presentation.save(f"empty_cells_{mode_name}.pptx", SaveFormat.Pptx)
finally:
presentation.dispose()
Each output file stores the mode assigned before saving: empty_cells_Gap.pptx, empty_cells_Zero.pptx, and empty_cells_Span.pptx. To save only one version, assign the desired mode and save the presentation once instead of iterating over the modes.
The comparison below shows the same data in all three files. Day 3 is empty in the workbook in every case:
The visible effect depends on the chart type. A line chart makes all three modes easy to compare. Bar and column charts have no line to connect across a missing category, so Span cannot produce the connecting segment shown above; a missing column and a zero-height column can also look alike. Similarly, a scatter chart with markers only has no connecting line. Do not expect three distinct results for every chart type; check the output for the type you use.
設定系列間距寬度
Gap width is the space between adjacent bar or column clusters, expressed as a percentage of the bar or column width. Like overlap, it belongs to the parent series group rather than to one series. Call ChartSeriesGroup.setGapWidth once for the group. A larger value creates more space between clusters; a smaller value makes them denser.
The following example changes the gap width and saves only the final presentation:
import jpype
import asposeslides
if not jpype.isJVMStarted():
jpype.startJVM()
from asposeslides.api import ChartType, Presentation, SaveFormat
first_slide_index = 0
first_series_index = 0
gap_width_percent = 30
presentation = Presentation()
try:
slide = presentation.getSlides().get_Item(first_slide_index)
chart = slide.getShapes().addChart(ChartType.StackedColumn, 20, 20, 500, 200)
series = chart.getChartData().getSeries().get_Item(first_series_index)
series.getParentSeriesGroup().setGapWidth(gap_width_percent)
presentation.save("gap_width_30.pptx", SaveFormat.Pptx)
finally:
presentation.dispose()
The result:
常見問題
哪些圖表類型支援資料系列？
All chart types represented by the ChartType enumeration use chart data, but their series do not all have the same value structure or settings. For example, category charts use categories and values, scatter charts use X and Y values, and bubble charts add bubble sizes. Use the data-point creation method that matches the series type. Options such as overlap and gap width apply only to compatible bar or column groups.
什麼是圖表系列群組？
A ChartSeriesGroup contains compatible series that share group-level plotting settings. A combination chart can contain more than one group, so changing the group reached through one series does not necessarily change every series in the chart.
新建立的圖表是否包含預設資料？
Yes. By default, ShapeCollection.addChart creates sample series, categories, and values. You can edit those cells or clear both the series and category collections before adding a completely custom data set. An overload can also create a chart without default data.
圖表物件如何與工作簿儲存格相連？
Series names, category labels, and data-point values reference cells in a ChartDataWorkbook. Changing a referenced cell updates the corresponding chart element. When you build custom data, keep category rows and series-value rows aligned so that each point is plotted under the intended category.
如何只清除單一資料點而不是整個系列？
Set the relevant value cell to None to retain the point’s category position as an empty point. Use ChartDataPointCollection.clear only when you intend to remove all points from that series. If you also remove categories, update every series so their values remain aligned with the category collection.
空白點會如何顯示？
The result depends on the chart type and the value configured through Chart.setDisplayBlanksAs. Supported charts can display blanks as gaps, as zero values, or by connecting neighboring points. Choose the setting that matches the meaning of missing data in your presentation. See 控制空白儲存格的顯示 for a complete example and visual comparison.
負值會如何格式化？
For supported bar, column, and bubble series, call ChartSeries.setInvertIfNegative and set the color returned by ChartSeries.getInvertedSolidFillColor. You can override the behavior for an individual point with ChartDataPoint.setInvertIfNegative. These methods affect formatting, not the stored numeric values.
當系列與資料點同時設定格式時，哪個優先？
Explicit data-point formatting takes precedence for that point. Other points continue to use the explicit series format or, when the series format is not defined, the automatic chart style and theme. Group settings such as overlap and gap width control layout and are not point-level formatting overrides.
圖表可以包含多少個系列有上限嗎？
Aspose.Slides does not impose a separate fixed series-count limit. In practice, presentation file constraints, available memory, rendering time, and chart readability determine a useful limit.
當欄位過於靠近或過於分離時，應該調整什麼？
Call ChartSeriesGroup.setGapWidth on the appropriate parent series group. Increase the value to widen the space between clusters, or decrease it to bring the clusters closer together.