کار با نمودارها
نمای کلی
Aspose.Cells FOSS از یک API متد‑به‑نوع‑نمودار استفاده میکند. بهجای یک فراخوانی عمومیadd(ChartType.X, ...)، هر نوع نمودار متد اختصاصی خود را در مجموعهcharts برگه کاری دارد:
| Method | Chart type |
|---|---|
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) | مساحتی |
تمام چهار پارامتر موقعیتی ناحیه مستطیلی در برگهای که نمودار در آن جاسازی میشود را توصیف میکنند. شاخصهای ردیف و ستون zero-based هستند. هر متد یک شیء 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")دادهها ردیفهای ۱–۶ (ردیفهای صفر‑پایه ۰–۵) را اشغال میکنند، بنابراین 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() برای پیوست کردن بازههای داده به یک نمودار استفاده کنید. تمام
آرگومانها را به عنوان keyword arguments برای جلوگیری از سردرگمی ترتیب موقعیتی پاس دهید:
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
یکبار، مختصرتر است. وقتی سریها بازههای دستهبندی متفاوتی دارند — برای مثال،
دو مجموعه داده با دورههای زمانی متفاوت — از آرگومان کلیدواژهٔ per-series استفاده کنید
بهجای آن.
موقعیتگذاری نمودار
چهار پارامتر موقعیتی برای هر روش add_* یک مستطیل محدودکننده در شیت تعریف میکنند که بر اساس شاخصهای ردیف و ستون صفر‑پایه اندازهگیری میشود:
add_bar(top_row, left_col, bottom_row, right_col)| Parameter | Meaning |
|---|---|
top_row | اندیس صفر‑پایهٔ اولین ردیفی که توسط نمودار اشغال شده است |
left_col | اندیس صفر‑پایهٔ ستون سمت چپترین |
bottom_row | اندیس صفر‑پایهٔ آخرین ردیفی که توسط نمودار اشغال شده است |
right_col | اندیس صفر‑پایهٔ ستون سمت راستترین |
یک الگوی رایج این است که نمودار را مستقیماً زیر دادهها قرار دهید. اگر دادههای شما
در ردیف 6 اکسل (شاخص ردیف صفر‑پایه 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")نمودار را به اندازه کافی بلند کنید تا قابل خواندن باشد: ارتفاع حداقل ۱۵ ردیف
(bottom_row - top_row >= 15) و عرض حداقل ۶ ستون نقطه شروع معقولی است.
خطاهای رایج
| Wrong | Right | Why |
|---|---|---|
ws.charts.add(ChartType.COLUMN, ...) | ws.charts.add_bar(...) | برای انواع پشتیبانینشده، ws.charts.add(ChartType.X, ...) را بهصورت مستقیم صدا نزنید — این باعث میشود NotImplementedError برای ۱۱ از ۱۶ نوع نمودار رخ دهد. بهجای آن از 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 باشد، هیچ اثری ندارد. |
همچنین ببینید
- API Reference: مستندات کامل کلاسها و متدها برای
aspose.cells_foss - Knowledge Base: راهنمای گامبهگام مبتنی بر وظیفه
- Product Overview: خلاصه ویژگیها و قابلیتها
- Getting Started / Installation: نصب pip و راهاندازی
- Blog: Python Excel Chart Tutorial: راهنمای گامبهگام ایجاد نمودار