حاشیه‌نویسی PDF

حاشیه‌نویسی‌های PDF

Page.annotations یک AnnotationCollection را افشا می‌کند — نمایی قابل تغییر و شبیه به دنباله بر روی تمام حاشیه‌نویسی‌ها در یک صفحه. هر ورودی یک Annotation است (یا زیرکلاس‌های MarkupAnnotation / LinkAnnotation)، و داده‌های مخصوص زیرنوع مانند نقاط چهارگانه، فهرست‌های جوهر یا رنگ‌ها از طریق get_property() / set_property() خوانده و نوشته می‌شوند نه از طریق ویژگی‌های اختصاصی.

افزودن حاشیه‌نویسی‌ها

AnnotationCollection.add(subtype, rect, contents, title, appearance_normal, properties) یک حاشیه‌نویسی جدید ایجاد می‌کند و آن را به صفحه اضافه می‌سد. subtype یک رشته ساده ("Text"، "Square"، "Highlight") یا یک عضو enum AnnotationType را می‌پذیرد.

import aspose_pdf
from aspose_pdf import Document, AnnotationType

doc = Document()
doc.pages.add()
page = doc.pages[0]

# Plain string subtype
page.annotations.add("Text", (100, 100, 200, 200), "Hello")

# AnnotationType enum, with subtype-specific properties
page.annotations.add(
    AnnotationType.POLYGON,
    (0, 0, 10, 10),
    "",
    properties={"Vertices": [0, 0, 10, 0, 5, 10]},
)

خواندن و به‌روزرسانی ویژگی‌ها

get_property(name, default) یک مقدار مخصوص زیرنوع را می‌خواند؛ set_property(name, value) یک مقدار می‌نویسد، و تنظیم یک ویژگی به None آن را از دیکشنری properties حاشیه‌نویسی حذف می‌کند.

doc = Document()
doc.pages.add()
page = doc.pages[0]

ann = page.annotations.add(
    "Square", (0, 0, 50, 50), "x", properties={"C": [1, 0, 0]},
)
ann.set_property("IC", [0, 0, 1])
print(page.annotations[0].get_property("IC"))  # [0, 0, 1]

ann.set_property("C", None)  # removes the "C" entry entirely
print("C" in page.annotations[0].properties)  # False

نام‌گذاری حاشیه‌نویسی‌ها با AnnotationName

نام‌های PDF (به عنوان مثال ورودی Name یک حاشیه‌نویسی Stamp) به‌صورت متمایز از رشته‌های ساده با استفاده از AnnotationName، یک زیرکلاس str از aspose_pdf.engine.cos، علامت‌گذاری می‌شوند. مقداری که به این شکل ذخیره می‌شود همچنان با یک رشته معمولی برابر مقایسه می‌شود.

from aspose_pdf.engine.cos import AnnotationName

doc = Document()
doc.pages.add()
page = doc.pages[0]

page.annotations.add(
    "Stamp", (10, 10, 110, 60), "",
    properties={"Name": AnnotationName("Approved")},
)

درج، حذف و پاک‌سازی

insert(index, subtype, rect, contents, title, appearance_normal, properties) یک حاشیه‌نویسی جدید را در موقعیت مشخصی قرار می‌دهد؛ delete(index) یکی را بر اساس اندیس حذف می‌کند (در صورت اندیس خارج از محدوده، IndexError را برمی‌انگیزد)؛ clear() تمام حاشیه‌نویسی‌های صفحه را حذف می‌کند.

doc = Document()
doc.pages.add()
page = doc.pages[0]

page.annotations.add("Text", (0, 0, 100, 100), "A")
page.annotations.add("Text", (200, 200, 300, 300), "C")
page.annotations.insert(1, "Text", (100, 100, 200, 200), "B")
# order is now: A, B, C

page.annotations.delete(1)   # removes "B"
page.annotations.clear()     # removes everything remaining

تولید ظاهر حاشیه‌نویسی‌ها

Annotation.generate_appearance(force) جریان ظاهر /AP /N را برای یک حاشیه‌نویسی می‌سازد و وقتی یک رندر‌کننده برای آن زیرنوع موجود باشد، True را برمی‌گرداند؛ AnnotationCollection.generate_appearances(force) همین کار را برای تمام حاشیه‌نویسی‌های صفحه در یک فراخوانی انجام می‌دهد و تعداد حاشیه‌نویسی‌هایی که واقعاً تولید شده‌اند را برمی‌گرداند (زیرنوع‌های پشتیبانی‌نشده نادیده گرفته می‌شوند).

doc = Document()
doc.pages.add()
page = doc.pages[0]

page.annotations.add("Square", (0, 0, 50, 50), "")
page.annotations.add("Circle", (60, 0, 110, 50), "")
page.annotations.add("Text", (0, 60, 20, 80), "")  # unsupported subtype -> skipped

generated = page.annotations.generate_appearances()
print(generated)  # 2

زیرنوع‌ها و پرچم‌های حاشیه‌نویسی

AnnotationType نام‌های زیرنوع‌های استاندارد PDF 32000-1:2008 (جدول 169) را فهرست می‌کند: TEXT, LINK, FREE_TEXT, LINE, SQUARE, CIRCLE, POLYGON, POLY_LINE, HIGHLIGHT, UNDERLINE, SQUIGGLY, STRIKE_OUT, STAMP, CARET, INK, POPUP, FILE_ATTACHMENT, SOUND, MOVIE, WIDGET, SCREEN, PRINTER_MARK, TRAP_NET, WATERMARK و REDACT.

AnnotationFlags یک IntFlag است که رفتار نمایش/تعامل حاشیه‌نویسی را پوشش می‌دهد: DEFAULT, INVISIBLE, HIDDEN, PRINT, NO_ZOOM, NO_ROTATE, NO_VIEW, READ_ONLY, LOCKED و TOGGLE_NO_VIEW.

پیش‌انتشار: حاشیه‌نویسی‌های سه‌بعدی

PDF3DAnnotation، PDF3DArtwork، PDF3DContent و PDF3DView مدل آثار هنری سه‌بعدی را که به صفحه پیوست شده‌اند — یک PDF3DAnnotation دارای rect: Rectangle، یک artwork: PDF3DArtwork و یک background_color: Color اختیاری است. PDF3DArtwork.add_view() یک PDF3DView را ثبت می‌کند، که هر کدام یک render_mode (PDF3DRenderMode: SOLID, WIREFRAME, TRANSPARENT) و یک lighting_scheme (PDF3DLightingScheme: HEADLAMP, WHITE, GRAY, DARK, CUSTOM) را در خود دارند. رشته مستندات (docstring) خود کتابخانه PDF3DAnnotation را به عنوان «درپوش حداقل حاشیه‌نویسی برای واردات پیش‌انتشار» علامت‌گذاری می‌کند — این سطح را به‌عنوان مرحله اولیه در نظر بگیرید نه یک API کامل برای نویسندگی سه‌بعدی.

نکات و بهترین شیوه‌ها

• ترجیحاً اعضای enum AnnotationType را به‌جای رشته‌های زیرنوع خام استفاده کنید وقتی که مقدار نیز نیاز به مقایسه یا تصمیم‌گیری در جای دیگری از کد شما دارد.
• برای حذف کامل یک ویژگی، set_property(name, None) را فراخوانی کنید به‌جای اینکه مقدار منقضی‌شده را در محل بگذارید — ورودی به‌طور کامل از properties حذف می‌شود.
• تولید دسته‌ای ظاهر با AnnotationCollection.generate_appearances به‌جای حلقه‌زدن generate_appearance() برای هر حاشیه‌نویسی؛ این تابع تعداد واقعی تولید شده را برمی‌گرداند تا بتوانید زیرنوع‌های رد‌شده/پشتیبانی‌نشده را شناسایی کنید.
• delete() و ایندکس‌گذاری در page.annotations هر دو صفر-مبنا هستند؛ قبل از فراخوانی delete()، ایندکس را اعتبارسنجی کنید اگر از ورودی کاربر آمده باشد، زیرا ایندکس خارج از محدوده باعث رخ دادن IndexError می‌شود.
• مقادیر نام PDF (مانند Name یک Stamp) را در AnnotationName بپیچید تا به‌عنوان نام‌های PDF به‌جای رشته‌های متنی ساده دور بزنند.

مشکلات رایج

FAQ

چگونه یک حاشیه‌نویس متنی ساده اضافه کنم؟

متد page.annotations.add("Text", (x0, y0, x1, y1), "comment text") را فراخوانی کنید. ترکیب چهار عددی، مستطیل حاشیه‌نویس روی صفحه است.

تفاوت Annotation، MarkupAnnotation و LinkAnnotation چیست؟

Annotation نمای زنده‌ای است که برای هر حاشیه‌نویسی روی صفحه بازگردانده می‌شود. MarkupAnnotation پایه‌ای برای زیرنوع‌های سبک نشانه‌گذاری (برجسته‌سازی‌ها، یادداشت‌های متنی، اشکال) است و LinkAnnotation برای حاشیه‌نویسی‌های سبک لینک نگه‌داشته شده است؛ هر دو در حال حاضر همان سطح متد/خاصیت را که Annotation ارائه می‌دهد، نشان می‌دهند.

آیا می‌توانم یک ویژگی را حذف کنم بدون اینکه کل حاشیه‌نویس حذف شود؟

بله — متد annotation.set_property(name, None) را فراخوانی کنید؛ خود حاشیه‌نویس دست نخورده می‌ماند، فقط آن ورودی از properties حذف می‌شود.

آیا AnnotationCollection.generate_appearances در صورتی که یک زیرنوع پشتیبانی نشود، خطا می‌دهد؟

نه. این زیرنوع‌هایی که رندرر ظاهری داخلی ندارند را نادیده می‌گیرد و تعداد حاشیه‌نویسی‌هایی که واقعا ظاهر برایشان تولید شده است را برمی‌گرداند.

آیا کلاس‌های حاشیه‌نویسی 3D برای استفاده در تولید آماده‌اند؟

PDF3DAnnotation و انواع مرتبط به‌عنوان یک بسته‌بندی حداقل برای واردات پیش‌انتشار مستند شده‌اند — پیش از اعتماد به آن‌ها برای محتوای 3D تولیدی، رفتار آن را در نماینده PDF هدف خود تأیید کنید.

API Reference خلاصه

همچنین ببینید:

• Aspose.PDF for Python — Enterprise Documentation