Aspose.Cells FOSS
Python
Guide du développeur
Travailler avec les graphiques

Travailler avec les graphiques

Vue d’ensemble

Aspose.Cells FOSS uses a method-per-chart-type API. Instead of a generic add(ChartType.X, ...) appel, chaque type de graphique possède sa propre méthode dédiée sur de la feuille de calcul charts collection :

MéthodeType de graphique
ws.charts.add_bar(top_row, left_col, bottom_row, right_col)Colonne groupée (diagramme à barres)
ws.charts.add_line(top_row, left_col, bottom_row, right_col)Ligne
ws.charts.add_pie(top_row, left_col, bottom_row, right_col)Camembert
ws.charts.add_area(top_row, left_col, bottom_row, right_col)Aire

Les quatre paramètres positionnels décrivent la zone rectangulaire dans la feuille où le graphique sera intégré. Les indices de ligne et de colonne sont indexé à zéro. Chaque la méthode renvoie un Chart objet que vous configurez davantage avant de l’enregistrer.

Limitation: Seuls les types de graphiques LINE, BAR, PIE, AREA et STOCK peuvent être enregistrés au format XLSX. Appeler wb.save() avec un classeur contenant tout autre type de graphique (e.g., SCATTER, WATERFALL, RADAR, TREEMAP, HISTOGRAM) déclenchera NotImplementedError.

Ajout d’un graphique à colonnes

L’exemple ci‑dessous écrit un petit jeu de données de revenus par produit, puis ajoute un graphique à colonnes placé sous les données.

from aspose.cells_foss import Workbook, Cell

workbook = Workbook()
ws = workbook.worksheets[0]

##--- Data ---
ws.cells["A1"].value = "Product"
ws.cells["B1"].value = "Revenue"

products = ["Widget A", "Widget B", "Widget C", "Widget D", "Widget E"]
revenues = [12_500, 18_200, 9_800, 21_400, 15_600]

for i, (product, revenue) in enumerate(zip(products, revenues), start=2):
    ws.cells[f"A{i}"].value = product
    ws.cells[f"B{i}"].value = revenue

##--- Chart (rows 7–22, columns A–H, all zero-based) ---
##top_row=6, left_col=0, bottom_row=22, right_col=7
chart = ws.charts.add_bar(6, 0, 22, 7)

chart.title = "Revenue by Product"
chart.n_series.add("B2:B6", category_data="A2:A6", name="Revenue (USD)")
chart.show_legend = True
chart.legend_position = "bottom"

workbook.save("column_chart.xlsx")
print("Saved column_chart.xlsx")

Les données occupent les lignes 1–6 (lignes indexées à zéro 0–5), donc top_row=6 place le graphique immédiatement en dessous sans chevaucher les données.

Ajout d’un graphique linéaire

Les graphiques en ligne sont adaptés pour montrer les tendances dans le temps. La signature d’appel est identique à add_bar — seul le nom de la méthode change.

from aspose.cells_foss import Workbook, Cell

workbook = Workbook()
ws = workbook.worksheets[0]

##--- Monthly trend data ---
ws.cells["A1"].value = "Month"
ws.cells["B1"].value = "Page Views"
ws.cells["C1"].value = "Conversions"

months = ["Jan", "Feb", "Mar", "Apr", "May", "Jun"]
page_views   = [4_200, 5_100, 4_800, 6_300, 7_100, 6_800]
conversions  = [  210,   255,   230,   340,   390,   360]

for i, (month, pv, cv) in enumerate(zip(months, page_views, conversions), start=2):
    ws.cells[f"A{i}"].value = month
    ws.cells[f"B{i}"].value = pv
    ws.cells[f"C{i}"].value = cv

##--- Line chart below the data ---
chart = ws.charts.add_line(8, 0, 24, 8)

chart.title = "Monthly Website Metrics"
chart.n_series.add("B2:B7", category_data="A2:A7", name="Page Views")
chart.n_series.add("C2:C7", category_data="A2:A7", name="Conversions")
chart.show_legend = True
chart.legend_position = "bottom"

workbook.save("line_chart.xlsx")
print("Saved line_chart.xlsx")

Titre du graphique et légende

Définissez le titre du graphique en assignant une chaîne simple directement à chart.title. Le propriété accepte une str — n’essayez pas d’accéder à une sous-propriété telle que .title.text, qui n’existe pas dans cette bibliothèque.

##Correct
chart.title = "Quarterly Sales"

##Wrong — raises AttributeError
##chart.title.text = "Quarterly Sales"

La visibilité et la position de la légende sont contrôlées par deux propriétés :

chart.show_legend = True          # display the legend
chart.legend_position = "bottom"  # "bottom", "top", "left", "right"

Pour masquer complètement la légende, définissez chart.show_legend = False. Le legend_position valeur est ignorée lorsque la légende est masquée.

Configuration des séries de données

Utilisez chart.n_series.add() pour attacher des plages de données à un graphique. Passez tous arguments comme arguments nommés pour éviter la confusion liée à l’ordre positionnel :

chart.n_series.add("B2:B6", category_data="A2:A6", name="Revenue")

Vous pouvez ajouter plusieurs séries à un même graphique en appelant n_series.add plus qu’une fois. Chaque appel ajoute une nouvelle série :

from aspose.cells_foss import Workbook, Cell

workbook = Workbook()
ws = workbook.worksheets[0]

##Headers
ws.cells["A1"].value = "Quarter"
ws.cells["B1"].value = "North"
ws.cells["C1"].value = "South"
ws.cells["D1"].value = "East"

data = [
    ("Q1", 8_400, 6_100, 7_200),
    ("Q2", 9_200, 7_400, 8_100),
    ("Q3", 10_500, 8_900, 9_600),
    ("Q4", 11_800, 9_300, 10_200),
]

for i, row in enumerate(data, start=2):
    ws.cells[f"A{i}"].value = row[0]
    ws.cells[f"B{i}"].value = row[1]
    ws.cells[f"C{i}"].value = row[2]
    ws.cells[f"D{i}"].value = row[3]

chart = ws.charts.add_bar(6, 0, 22, 8)
chart.title = "Regional Sales by Quarter"

chart.n_series.add("B2:B5", category_data="A2:A5", name="North")
chart.n_series.add("C2:C5", category_data="A2:A5", name="South")
chart.n_series.add("D2:D5", category_data="A2:A5", name="East")

chart.show_legend = True
chart.legend_position = "bottom"

workbook.save("multi_series_chart.xlsx")
print("Saved multi_series_chart.xlsx")

Données de catégorie

Les libellés de catégorie peuvent être définis au niveau du graphique ou au niveau de chaque série.

Données de catégorie au niveau du graphique s’applique à toutes les séries par défaut :

chart.category_data = "A2:A5"

Données de catégorie au niveau de la série (via le category_data argument nommé pour n_series.add) remplace le paramètre au niveau du graphique pour cette série spécifique :

chart.n_series.add("B2:B5", category_data="A2:A5", name="Revenue")

Lorsque chaque série partage la même plage de catégories, définir chart.category_data une fois est plus concis. Lorsque les séries ont des plages de catégories différentes — par exemple, deux ensembles de données avec des périodes différentes — utilisez l’argument nommé par série à la place.

Positionnement du graphique

Les quatre paramètres positionnels de chaque add_* méthode définissent un rectangle de délimitation dans la feuille, mesuré en indices de lignes et de colonnes à base zéro :

add_bar(top_row, left_col, bottom_row, right_col)
ParamètreSignification
top_rowIndex basé sur zéro de la première ligne occupée par le graphique
left_colIndex basé sur zéro de la colonne la plus à gauche
bottom_rowIndex basé sur zéro de la dernière ligne occupée par le graphique
right_colIndex basé sur zéro de la colonne la plus à droite

Un schéma courant consiste à placer le graphique directement sous les données. Si vos données se terminent à la ligne 6 d’Excel (index de ligne basé sur zéro 5), commencez le graphique à top_row=6:

from aspose.cells_foss import Workbook, Cell

workbook = Workbook()
ws = workbook.worksheets[0]

##Data in rows 1–5 (zero-based 0–4)
labels = ["Alpha", "Beta", "Gamma", "Delta", "Epsilon"]
values = [30, 45, 28, 60, 52]

ws.cells["A1"].value = "Category"
ws.cells["B1"].value = "Score"

for i, (label, val) in enumerate(zip(labels, values), start=2):
    ws.cells[f"A{i}"].value = label
    ws.cells[f"B{i}"].value = val

##Data ends at zero-based row 5 (Excel row 6).
##Place chart from row 6 to row 22, columns A–H (0–7).
chart = ws.charts.add_bar(6, 0, 22, 7)
chart.title = "Category Scores"
chart.n_series.add("B2:B6", category_data="A2:A6", name="Score")
chart.show_legend = False

workbook.save("positioned_chart.xlsx")
print("Saved positioned_chart.xlsx")

Rendez le graphique suffisamment haut pour être lisible : une hauteur d’au moins 15 lignes (bottom_row - top_row >= 15) et une largeur d’au moins 6 colonnes constituent un point de départ raisonnable.

Erreurs courantes

IncorrectCorrectPourquoi
ws.charts.add(ChartType.COLUMN, ...)ws.charts.add_bar(...)Ne pas appeler ws.charts.add(ChartType.X, ...) directement pour les types non pris en charge — cela lèvera NotImplementedError pour 11 des 16 types de graphiques. Utilisez add_bar(), add_line(), add_pie(), add_area(), ou add_stock() à la place.
chart.title.text = "My Chart"chart.title = "My Chart"chart.title est une propriété de chaîne simple, pas un objet avec un .text sous-propriété.
chart.n_series.add("B2:B5", "A2:A5", "Revenue")chart.n_series.add("B2:B5", category_data="A2:A5", name="Revenue")Les deuxième et troisième paramètres doivent être passés en tant qu’arguments nommés pour éviter toute ambiguïté.
chart = ws.charts.add_bar(0, 0, 15, 7) (chevauche les données)Place top_row sous la dernière ligne de donnéesUn graphique qui chevauche les données masque les valeurs et entraîne des mises en page confuses.
chart.legend_position = "bottom" sans chart.show_legend = TrueEnsemble chart.show_legend = True premierlegend_position n’a aucun effet lorsque show_legend est False.

Voir aussi

 Français