العمل مع المخططات
نظرة عامة
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. |
انظر أيضًا
- مرجع API: توثيق كامل للفئات والطرق لـ
aspose.cells_foss - قاعدة المعرفة: أدلة إرشادية موجهة للمهام
- نظرة عامة على المنتج: ملخص الميزات والقدرات
- البدء / التثبيت: pip install والإعداد
- مدونة: Python Excel Chart Tutorial: دليل إنشاء المخطط خطوة بخطوة