עבודה עם תרשימים

סקירה

Aspose.Cells FOSS uses a method-per-chart-type API. Instead of a generic add(ChartType.X, ...) בקריאה, לכל סוג גרף יש שיטה ייעודית משלו ב של הגיליון charts אוסף:

שיטהסוג גרף
ws.charts.add_bar(top_row, left_col, bottom_row, right_col)עמודה מקובצת (גרף עמודות)
ws.charts.add_line(top_row, left_col, bottom_row, right_col)קו
ws.charts.add_pie(top_row, left_col, bottom_row, right_col)עוגה
ws.charts.add_area(top_row, left_col, bottom_row, right_col)שטח

כל ארבעת הפרמטרים המיקומיים מתארים את האזור המלבני בגיליון שבו הגרף יוטמע. אינדקסי השורה והעמודה הם מתחילים מאפס. כל שיטה מחזירה Chart אובייקט שאתה מגדיר עוד לפני השמירה.

הגבלה: רק סוגי התרשימים LINE, BAR, PIE, AREA ו‑STOCK ניתנים לשמירה בקובץ XLSX. קריאה wb.save() עם חוברת עבודה שמכילה כל סוג תרשים אחר (למשל, SCATTER, WATERFALL, RADAR, TREEMAP, HISTOGRAM) תגרום לחריגה NotImplementedError.


הוספת תרשים עמודות

הדוגמה שלהלן כותבת קבוצת נתונים קטנה של הכנסות לפי מוצר ולאחר מכן מוסיפה תרשים עמודות הממוקם מתחת לנתונים.

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")

הנתונים תופסים שורות 1–6 (שורות מבוססות‑אפס 0–5), ולכן top_row=6 ממקם את תרשים מיד למטה מבלי לחפוף את הנתונים.


הוספת תרשים קו

תרשימי קו עובדים היטב להצגת מגמות לאורך זמן. חתימת הקריאה היא זהה ל add_bar — רק שם המתודה משתנה.

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")

כותרת התרשים והאגדה

הגדר את כותרת התרשים על‑ידי הקצאת מחרוזת פשוטה ישירות ל chart.title. ה המאפיין מקבל str — אל תנסה לגשת למאפיין משנה כגון .title.text, שאינו קיים בספרייה זו.

##Correct
chart.title = "Quarterly Sales"

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

נראות ומיקום האגדה נשלטים על‑ידי שני מאפיינים:

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

כדי להסתיר את האגדה לחלוטין, הגדר chart.show_legend = False. ה legend_position הערך מתעלמים ממנו כאשר האגדה מוסתרת.


תצורת סדרות הנתונים

השתמש chart.n_series.add() כדי לצרף טווחי נתונים לתרשים. העבר את כל הארגומנטים כ ארגומנטים לפי מילות מפתח כדי למנוע בלבול בסדר המיקומים:

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

ניתן להוסיף סדרות מרובות לתרשים יחיד על‑ידי קריאה n_series.add יותר מעל פעם אחת. כל קריאה מוסיפה סדרה חדשה:

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")

נתוני קטגוריה

ניתן להגדיר תוויות קטגוריה ברמת התרשים או ברמת הסדרה הפרטית.

נתוני קטגוריה ברמת התרשים חל על כל הסדרות כברירת מחדל:

chart.category_data = "A2:A5"

נתוני קטגוריה ברמת הסדרה (דרך ה category_data ארגומנט מילה מפתח ל n_series.add) מבטל את ההגדרה ברמת התרשים עבור הסדרה הספציפית הזו:

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

כאשר כל הסדרות חולקות את אותו טווח קטגוריות, הגדרת chart.category_data פעם אחת היא יותר תמציתית. כאשר לסדרות יש טווחי קטגוריות שונים — לדוגמה, שני מערכי נתונים עם תקופות זמן שונות — השתמשו בארגומנט מילה מפתח לכל סדרה במקום זאת.


מיקום התרשים

ארבעת הפרמטרים המיקומיים לכל add_* שיטה מגדירים ריבוע גבול בגיליון, נמדד באינדקסים של שורות ועמודות שמתחילים מאפס:

add_bar(top_row, left_col, bottom_row, right_col)
פרמטרמשמעות
top_rowאינדקס שמתחיל מאפס של השורה הראשונה שתופסת את התרשים
left_colאינדקס מבוסס אפס של העמודה השמאלית ביותר
bottom_rowאינדקס מבוסס אפס של השורה האחרונה שתופסת את התרשים
right_colאינדקס מבוסס אפס של העמודה הימנית ביותר

תבנית נפוצה היא למקם את התרשים ישירות מתחת לנתונים. אם הנתונים שלך מסתיים בשורה 6 של Excel (אינדקס שורה אפס‑מבוסס 5), התחל את התרשים ב 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")

הפוך את התרשים לגובה מספיק כדי שיהיה קריא: גובה של לפחות 15 שורות (bottom_row - top_row >= 15) ורוחב של לפחות 6 עמודות הוא נקודת התחלה סבירה.


טעויות נפוצות

שגוינכוןלמה
ws.charts.add(ChartType.COLUMN, ...)ws.charts.add_bar(...)אל תקרא ws.charts.add(ChartType.X, ...) בצורה ישירה עבור סוגים שאינם נתמכים — זה יגרום לשגיאה NotImplementedError עבור 11 מתוך 16 סוגי תרשימים. השתמש add_bar(), add_line(), add_pie(), add_area(), או add_stock() במקום זאת.
chart.title.text = "My Chart"chart.title = "My Chart"chart.title הוא מאפיין מחרוזת רגילה, לא אובייקט עם .text תת‑מאפיין.
chart.n_series.add("B2:B5", "A2:A5", "Revenue")chart.n_series.add("B2:B5", category_data="A2:A5", name="Revenue")הפרמטרים השני והשלישי חייבים להועבר כארגומנטים בשם כדי למנוע דו‑משמעות.
chart = ws.charts.add_bar(0, 0, 15, 7) (חופף נתונים)מקם top_row מתחת לשורת הנתונים האחרונהתרשים שחופף נתונים מסתיר ערכים וגורם לפריסות מבלבלות.
chart.legend_position = "bottom" ללא chart.show_legend = Trueהגדר chart.show_legend = True ראשוןlegend_position אין לו השפעה כאשר show_legend הוא False.

ראה גם

 עברית