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

Travailler avec les graphiques

Vue d’ensemble

Aspose.Cells FOSS utilise une API méthode‑par‑type‑de‑graphique. Au lieu d’un appel générique add(ChartType.X, ...), chaque type de graphique possède sa propre méthode dédiée dans la collection charts de la feuille de calcul :

MéthodeType de graphique
ws.charts.add_bar(top_row, left_col, bottom_row, right_col)Colonne groupée (graphique à 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)Zone

Tous 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 à base zéro. Chaque méthode renvoie un objet Chart que vous configurez davantage avant l’enregistrement.

Limitation : Seuls les types de graphiques LINE, BAR, PIE, AREA et STOCK peuvent être enregistrés au format XLSX. L’appel de wb.save() avec un classeur contenant tout autre type de graphique (par ex., 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 à partir de zéro 0–5), donc top_row=6 place le graphique immédiatement en dessous sans chevaucher les données.

Ajout d’un graphique en courbes

Les graphiques en ligne fonctionnent bien pour afficher les tendances au fil du 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. La propriété accepte un str — ne tentez 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. La valeur legend_position est ignorée lorsque la légende est masquée.

Configuration de la série de données

Utilisez chart.n_series.add() pour attacher des plages de données à un graphique. Passez tous
les arguments en tant qu’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 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 étiquettes de catégorie peuvent être définies au niveau du graphique ou au niveau de chaque série.

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

chart.category_data = "A2:A5"

Données de catégorie au niveau de la série (via l’argument mot‑clé category_data de 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 temporelles différentes — utilisez l’argument mot‑clé par série
à la place.

Positionnement du graphique

Les quatre paramètres positionnels de chaque méthode add_* définissent un rectangle englobant 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_rowIndice basé sur zéro de la première ligne occupée par le graphique
left_colIndice basé sur zéro de la colonne la plus à gauche
bottom_rowIndice basé sur zéro de la dernière ligne occupée par le graphique
right_colIndice 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 (indice de ligne zéro‑based 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 constitue 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 déclenchera 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 une sous‑propriété .text.
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)Placez 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 = TrueDéfinissez chart.show_legend = True d’abordlegend_position n’a aucun effet lorsque show_legend est False.

Voir aussi

 Français