يوضح مخطط الشلال كيف تتغير القيمة الأولية عبر سلسلة من الزيادات والنقصانات. على سبيل المثال، يمكنك استخدامه في تقرير مالي لتوضيح كيف تساهم المبيعات والمصروفات والدخل الآخر في الرصيد الختامي.

في هذا البرنامج التعليمي، ستقوم بإنشاء مخطط شلال في مستند Word باستخدام Python و Aspose.Words for Python via .NET. ستتعلم أيضًا كيفية تحديد النقاط الإجمالية في المخطط وفحص مخططات الشلال في المستندات الموجودة.

مكتبة بايثون لإنشاء مخططات الشلال في Word

Aspose.Words for Python via .NET يتيح لك إنشاء وتعديل مستندات Word في Python. يمكنك استخدامه لإضافة مخططات إلى التقارير والعمل مع سلاسل المخططات ونقاط البيانات.

قم بتثبيت المكتبة من PyPI:

pip install aspose-words

استخدم Aspose.Words for Python via .NET 26.10 or later للحصول على البرنامج التعليمي الكامل. قدم هذا الإصدار واجهات برمجة التطبيقات المستخدمة للتحقق مما إذا كانت نقطة مخطط الشلال إجمالية.

لمتطلبات النظام الأساسي وغيرها من تفاصيل التثبيت، راجع وثائق التثبيت.

فهم مخطط الشلال النموذجي

تستخدم الأمثلة البيانات التالية لإظهار التغييرات من الرصيد الافتتاحي إلى الرصيد الختامي:

الفئةالقيمةنوع النقطة
الرصيد الافتتاحي100إجمالي
المبيعات+40زيادة
المصروفات−20نقصان
الإجمالي الفرعي120إجمالي
إيرادات أخرى+10زيادة
الرصيد الختامي130إجمالي

تمثل نقاط المبيعات والمصروفات والدخل الآخر التغييرات. تمثل الرصيد الافتتاحي والمجموع الفرعي والرصيد الختامي القيم في مراحل معينة.

لإنشاء سلسلة المخطط، ستقدم ثلاث قوائم بنفس الترتيب:

  • Categories: تسميات نقاط المخطط.
  • Values: التغييرات والقيم الإجمالية الموردة صراحةً.
  • Total flags: القيم المنطقية التي تحدد النقاط المقابلة كإجماليات.

تحدد العلامات إجمالي النقاط؛ فهي لا تحسبها. في هذا المثال، يتم توفير المجموع الفرعي كـ 120، ويتم توفير الرصيد الختامي كـ 130.

إنشاء مخطط شلال في Word باستخدام Python

اتبع الخطوات التالية لإنشاء المخطط:

  1. إنشاء Document و DocumentBuilder.
  2. إدراج مخطط باستخدام ChartType.WATERFALL.
  3. تعيين عنوان المخطط ومسح السلسلة الافتراضية.
  4. إضافة الفئات والقيم وعلامات الإجمالي.
  5. حفظ المستند كملف DOCX.

المثال التالي ينشئ المخطط الكامل:

import aspose.words as aw

# Create a document and document builder.
doc = aw.Document()
builder = aw.DocumentBuilder(doc)

# Insert a waterfall chart.
shape = builder.insert_chart(
    chart_type=aw.drawing.charts.ChartType.WATERFALL,
    width=500,
    height=350
)

chart = shape.chart
chart.title.text = "Balance Changes"

# Remove the default chart series.
chart.series.clear()

# Define categories, values, and total flags.
categories = [
    "Opening balance",
    "Sales",
    "Expenses",
    "Subtotal",
    "Other income",
    "Closing balance"
]

values = [100, 40, -20, 120, 10, 130]

total_flags = [True, False, False, True, False, True]

# Add the waterfall series.
series = chart.series.add(
    series_name="Balance",
    categories=categories,
    values=values,
    is_subtotal=total_flags
)

# Save the Word document.
doc.save("waterfall-chart.docx")

طريقة add() الخاصة بالمخطط الشلالي تقبل اسم السلسلة، الفئات، القيم، وعلميات Boolean. كل عنصر في فهرس معين يصف نفس نقطة المخطط. على الرغم من أن الوسيط Boolean يُسمى is_subtotal، فإن المثال الموثق يستخدمه لتحديد القيمة الابتدائية، ومجموع جزئي متوسط، والقيمة النهائية كإجماليات.

الملف الناتج waterfall-chart.docx يحتوي على مخطط من ست نقاط يُظهر الرصيد الافتتاحي، التغييرات، المجموع الفرعي، والرصيد الختامي.

إنشاء مخططات الشلال في Word باستخدام Python.

إنشاء مخططات الشلال في Word باستخدام Python.

تحقق مما إذا كانت نقطة مخطط الشلال هي إجمالي

يمكنك التحقق من تعيين كل نقطة باستخدام series.is_total(index). أضف الحلقة التالية بعد استدعاء chart.series.add(...) في المثال السابق:

for i in range(len(categories)):
    point_type = "Total" if series.is_total(i) else "Not a total"
    print(f"{categories[i]}: {values[i]} — {point_type}")

بالنسبة لبيانات العينة، النتيجة المتوقعة هي:

Opening balance: 100 — Total
Sales: 40 — Not a total
Expenses: -20 — Not a total
Subtotal: 120 — Total
Other income: 10 — Not a total
Closing balance: 130 — Total

طريقة is_total() تأخذ فهرسًا يبدأ من الصفر وتعيد True إذا تم تعيين النقطة كإجمالي. لا تحدد ما إذا كانت النقطة رصيدًا افتتاحيًا أو مجموعًا فرعيًا متوسطًا أو إجماليًا نهائيًا.

تحقق من إجمالي باستخدام ChartDataPoint.is_total

إذا كان لديك بالفعل نقطة بيانات مخطط، يمكنك قراءة خاصية is_total الخاصة بها. المثال التالي يتحقق من المجموع الفرعي عند الفهرس 3:.

is_subtotal = series.data_points[3].is_total
print(f"Subtotal is a total: {is_subtotal}")

Expected output:

Subtotal is a total: True

ChartDataPoint.is_total هي خاصية للقراءة فقط للمخططات الشلالية. مثل series.is_total(index)، تُبلغ عن تعيين النقطة؛ ولا تقوم بتعيين أو حساب الإجمالي.

فحص مخطط الشلال في مستند Word موجود

يمكنك أيضًا تحميل مستند Word موجود والبحث فيه عن سلاسل مخطط الشلال. المثال المستقل التالي يتحقق من كل شكل، يتخطى الأشكال التي لا تحتوي على مخططات، ويفحص كل سلسلة شلال يجدها.

استبدل waterfall-chart.docx بمسار المستند الخاص بك:

import aspose.words as aw

# Load an existing Word document.
doc = aw.Document("waterfall-chart.docx")

found_waterfall_series = False

# Search the document's shapes.
shapes = doc.get_child_nodes(aw.NodeType.SHAPE, True)

for node in shapes:
    shape = node.as_shape()

if not shape.has_chart:
        continue

for series in shape.chart.series:
        if series.series_type != aw.drawing.charts.ChartSeriesType.WATERFALL:
            continue

found_waterfall_series = True
        print(f"Waterfall series: {series.name}")

for i in range(series.y_values.count):
            point_type = "Total" if series.is_total(i) else "Not a total"
            print(f"Point {i}: {point_type}")

if not found_waterfall_series:
    print("No waterfall chart series found.")

يعرض المثال كل نقطة وفقًا لمؤشرها الذي يبدأ من الصفر. يعالج عدة سلاسل شلال إذا كانت موجودة ويطبع رسالة إذا لم يجد أيًا منها. تسمح خاصية series_type للشفرة بالتحقق من ChartSeriesType.WATERFALL قبل استدعاء is_total().

احصل على ترخيص مجاني

يمكنك طلب رخصة مؤقتة مجانية لتقييم Aspose.Words for Python via .NET. قم بتطبيق الرخصة في تطبيقك قبل تشغيل الأمثلة.

الخلاصة

يمكنك إنشاء مخطط شلال في مستند Word باستخدام Python وتحديد نقاطه الإجمالية برمجيًا. استخدم نفس النهج لإضافة المخططات إلى التقارير المُنشأة أو فحص سلسلة الشلال في المستندات الموجودة.

الأسئلة المتكررة

كيف أنشئ مخطط شلال في Word باستخدام Python؟

أدرج مخططًا باستخدام ChartType.WATERFALL، أضف سلسلة تحتوي على الفئات والقيم وعلامات الإجمالي، واحفظ المستند كملف DOCX.

كيف يمكنني تحديد النقاط الإجمالية في مخطط الشلال؟

مرّر قائمة من القيم المنطقية عبر الوسيط is_subtotal عند إضافة السلسلة. عيّن قيمة True لكل نقطة يجب تعيينها كإجمالي.

كيف يمكنني التحقق مما إذا كانت نقطة مخطط الشلال تمثل إجماليًا؟

استدعِ series.is_total(index) مع الفهرس الصفري للنقطة، أو اقرأ خاصية is_total لكائن نقطة البيانات.

هل تقوم واجهات API is_total بتعيين أو حساب الإجماليات؟

لا. إنهم يبلّغون عما إذا كانت النقطة مُحددة كإجمالي. قدّم القيم وعلامات الإجمالي الخاصة بها عند إنشاء السلسلة.

هل يمكنني فحص مخطط الشلال في مستند Word موجود؟

نعم. قم بتحميل المستند، وابحث عن الأشكال التي تحتوي على مخططات، وتحقق من كل سلسلة للعثور على ChartSeriesType.WATERFALL قبل فحص نقاطها.

انظر أيضًا