نمودار آبشاری نشان می‌دهد که چگونه یک مقدار اولیه از طریق یک سری افزایش و کاهش تغییر می‌کند. به عنوان مثال، می‌توانید از آن در یک گزارش مالی استفاده کنید تا نشان دهید فروش، هزینه‌ها و سایر درآمدها چگونه به تراز نهایی کمک می‌کنند.
در این آموزش، شما یک نمودار آبشاری در یک سند Word با استفاده از Python و Aspose.Words for Python via .NET ایجاد خواهید کرد. همچنین یاد خواهید گرفت که چگونه نقاط کل را در نمودار شناسایی کنید و نمودارهای آبشاری را در اسناد موجود بررسی کنید.
کتابخانه پایتون برای ایجاد نمودارهای آبشاری در ورد
Aspose.Words for Python via .NET به شما امکان می‌دهد اسناد Word را در پایتون ایجاد و ویرایش کنید. می‌توانید از آن برای افزودن نمودارها به گزارش‌ها و کار با سری‌های نموداری و نقاط داده استفاده کنید.
کتابخانه را از PyPI نصب کنید:
pip install aspose-words
از Aspose.Words for Python via .NET 26.10 یا بعد برای آموزش کامل استفاده کنید. این نسخه APIهایی را معرفی کرد که برای بررسی اینکه آیا یک نقطه نمودار آبشار مجموع است، استفاده می‌شود.
برای نیازهای پلتفرم و سایر جزئیات نصب، به مستندات نصب مراجعه کنید.
درک نمودار آبشاری نمونه
مثال‌ها از داده‌های زیر برای نشان دادن تغییرات از مانده افتتاحیه به مانده پایانی استفاده می‌کنند:
| دسته‌بندی | مقدار | نوع نقطه |
|---|---|---|
| مانده افتتاحیه | 100 | کل |
| فروش | +40 | افزایش |
| هزینه‌ها | −20 | کاهش |
| جمع جزئی | 120 | کل |
| درآمد دیگر | +10 | افزایش |
| مانده پایانی | 130 | کل |
نقطه‌های فروش، هزینه‌ها و سایر درآمدها نشان‌دهنده تغییرات هستند. مانده افتتاحیه، مجموع جزئی و مانده پایانی نشان‌دهنده مقادیر در مراحل خاص هستند.
برای ایجاد سری‌های نمودار، سه لیست را به همان ترتیب ارائه می‌دهید:
- دسته‌ها: برچسب‌های نقاط نمودار.
- مقدارها: تغییرات و مقادیر کل به‌صورت صریح ارائه‌شده.
- پرچم‌های کل: مقادیر بولی که نقاط مربوطه را به‌عنوان کل تعیین می‌کنند.
پرچم‌ها مجموع امتیازها را شناسایی می‌کنند؛ آنها محاسبه نمی‌کنند. در این مثال، مجموع جزئی به عنوان 120 ارائه شده است و مانده نهایی به عنوان 130 ارائه شده است.
ایجاد نمودار آبشاری در Word با استفاده از Python
برای ایجاد نمودار این مراحل را دنبال کنید:
- یک
Documentو یکDocumentBuilderایجاد کنید. - یک نمودار با استفاده از
ChartType.WATERFALLوارد کنید. - عنوان نمودار را تنظیم کنید و سری پیش‌فرض را پاک کنید.
- دسته‌ها، مقادیر و پرچم‌های مجموع را اضافه کنید.
- سند را به عنوان یک فایل 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.
بررسی اینکه آیا یک نقطه نمودار آبشاری کل است
می‌توانید تعیین هر نقطه را با 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 به کد اجازه می‌دهد قبل از فراخوانی is_total()، بررسی کند که ChartSeriesType.WATERFALL باشد.
دریافت لایسنس رایگان
شما می‌توانید یک مجوز موقت رایگان درخواست کنید تا Aspose.Words for Python via .NET را ارزیابی کنید. قبل از اجرای مثال‌ها، مجوز را در برنامه خود اعمال کنید.
نتیجه‌گیری
می‌توانید با استفاده از Python یک نمودار آبشاری در سند Word ایجاد کنید و نقاط کل آن را به‌صورت برنامه‌نویسی شناسایی کنید.
از همان رویکرد برای افزودن نمودارها به گزارش‌های تولید شده یا بررسی سری‌های آبشاری در اسناد موجود استفاده کنید.
سوالات متداول
چگونه می‌توانم یک نمودار آبشاری در Word با استفاده از Python ایجاد کنم؟
یک نمودار با استفاده از ChartType.WATERFALL درج کنید، یک سری با دسته‌ها، مقادیر و پرچم‌های مجموع اضافه کنید و سند را به عنوان فایل DOCX ذخیره کنید.
چگونه می‌توانم نقاط کل را در نمودار آبشاری مشخص کنم؟
هنگام افزودن سری، یک لیست بولی را از طریق آرگومان is_subtotal عبور دهید. برای هر نقطه‌ای که باید به عنوان مجموع تعیین شود، یک ورودی را به True تنظیم کنید.
چگونه می‌توانم بررسی کنم که آیا یک نقطه در نمودار آبشاری، مجموع کلی است؟
با اندیس صفر‑پایه نقطه، series.is_total(index) را فراخوانی کنید یا ویژگی is_total شیء داده‑نقطه آن را بخوانید.
آیا APIهای is_total مجموع‌ها را تنظیم می‌کنند یا محاسبه می‌نمایند؟
خیر. آنها گزارش می‌دهند که آیا یک نقطه به عنوان مجموع تعیین شده است یا خیر. هنگام ایجاد سری، مقادیر و پرچم‌های مجموع آنها را فراهم کنید.
آیا می‌توانم یک نمودار آبشاری را در یک سند Word موجود بررسی کنم؟
بله. سند را بارگذاری کنید، اشکالی که شامل نمودار هستند را پیدا کنید، و قبل از بررسی نقاط آنها، هر سری را برای ChartSeriesType.WATERFALL بررسی کنید.