العمل مع المخططات

العمل مع المخططات

نظرة عامة

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.

انظر أيضًا

 العربية