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") 또는 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 이름(예: Stamp 주석의 Name 항목)은 AnnotationName를 사용하여 일반 문자열과 구별되며, 이는 aspose_pdf.engine.cos의 str 하위 클래스입니다. 이렇게 저장된 값은 일반 문자열과 여전히 동등하게 비교됩니다.

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 (Table 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.

프리릴리즈: 3D 주석

PDF3DAnnotation, PDF3DArtwork, PDF3DContent, 및 PDF3DView은 페이지에 첨부된 3D 아트워크를 모델링합니다 — 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)를 포함합니다. 라이브러리 자체 문서 문자열은 PDF3DAnnotation를 “minimal annotation wrapper for prerelease imports"라고 표시합니다 — 이 표면을 완전하게 구현된 3D 저작 API보다 초기 단계로 간주하십시오.

팁 및 모범 사례

• 코드의 다른 부분에서도 값이 비교되거나 분기되어야 할 경우, 원시 서브타입 문자열보다 AnnotationType 열거형 멤버를 선호하십시오.
• set_property(name, None)를 호출하여 속성을 완전히 제거하십시오. 오래된 값을 남겨두지 마세요 — 해당 항목이 properties에서 완전히 사라집니다.
• 주석당 generate_appearance()을 반복하는 대신 AnnotationCollection.generate_appearances으로 배치 외관 생성을 수행하십시오; 실제 생성된 개수를 반환하므로 건너뛰거나 지원되지 않는 서브타입을 감지할 수 있습니다.
• delete()와 page.annotations에 대한 인덱싱은 모두 0부터 시작합니다; 사용자 입력에서 온 경우 delete()를 호출하기 전에 인덱스를 검증하십시오. 범위를 벗어난 인덱스는 IndexError을 발생시킵니다.
• PDF 이름 값(예: Stamp의 Name)을 AnnotationName로 감싸서 일반 텍스트 문자열이 아니라 PDF 이름으로 라운드 트립하도록 하십시오.

일반적인 문제

FAQ

일반 텍스트 주석을 어떻게 추가하나요?

Call 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가 서브타입이 지원되지 않을 경우 실패합니까?

아니요. 내장된 appearance 렌더러가 없는 서브타입은 건너뛰고 실제로 appearance를 생성한 주석의 개수를 반환합니다.

3D 주석 클래스는 프로덕션에 사용할 준비가 되었나요?

PDF3DAnnotation 및 관련 유형은 사전 릴리스 가져오기를 위한 최소 래퍼로 문서화되어 있습니다 — 프로덕션 3D 콘텐츠에 의존하기 전에 대상 PDF 뷰어에서 동작을 확인하십시오.

API Reference 요약

참조

• Aspose.PDF for Python — Enterprise Documentation