العمل مع المخططات
نظرة عامة
يستخدم Aspose.Cells FOSS واجهة برمجة تطبيقات تعتمد طريقة لكل نوع مخطط. بدلاً من عام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 والإعداد
- مدونة: دليل مخطط Excel بلغة Python: دليل إنشاء المخطط خطوة بخطوة