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

بررسی کلی

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_* method یک مستطیل محدود کننده تعریف می‌کند مستطیل در شیت، که بر اساس شاخص‌های صفر-پایه ردیف و ستون اندازه‌گیری می‌شود:

add_bar(top_row, left_col, bottom_row, right_col)
پارامترمعنی
top_rowشاخص صفر-پایه اولین ردیفی که نمودار در آن قرار دارد
left_colشاخص صفر-پایه ستون سمت چپ‌ترین
bottom_rowشاخص صفر-پایه آخرین ردیفی که نمودار در آن قرار دارد
right_colشاخص صفر-پایه ستون سمت راست‌ترین

یک الگوی رایج این است که نمودار را مستقیماً زیر داده‌ها قرار دهید. اگر داده‌های شما در ردیف ۶ اکسل (اندیس ردیف صفر‑پایه ۵) پایان می‌یابد، نمودار را از 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) و عرض حداقل ۶ ستون نقطهٔ شروع معقولی است.


خطاهای رایج

نادرستدرستچرا
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.

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

 فارسی