کار با نمودارها

نمای کلی

Aspose.Cells FOSS از یک API متد‑به‑نوع‑نمودار استفاده می‌کند. به‌جای یک فراخوانی عمومی
add(ChartType.X, ...)، هر نوع نمودار متد اختصاصی خود را در مجموعه
charts برگه کاری دارد:

MethodChart 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)
ParameterMeaning
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) و عرض حداقل ۶ ستون نقطه شروع معقولی است.


خطاهای رایج

WrongRightWhy
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 = Truechart.show_legend = True را ابتدا تنظیم کنیدlegend_position زمانی که show_legend False باشد، هیچ اثری ندارد.

همچنین ببینید

 فارسی