주석 및 양식

주석 및 양식

주석 및 양식

Aspose.PDF FOSS for .NET은 PDF 주석 및 대화형 AcroForm 필드에 대한 전체 읽기/쓰기 액세스를 제공합니다. 주석에 대한 기본 진입점은 Page.Annotations (AnnotationCollection)이며, 폼 필드는 Document.Form을 통해 액세스합니다. 두 하위 시스템 모두 완전히 메모리 내에서 작동하며 라이선스 키가 필요하지 않습니다.


주석 추가

AnnotationCollection는 모든 표준
주석 종류에 대한 타입이 지정된 도우미 메서드를 제공합니다.
각 메서드는 Rectangle를 받아 페이지상의 주석
위치를 정의하고 유형별 매개변수를 받습니다.

using var doc = Document.Open(pdfBytes);
var page = doc.Pages[1];

// Text (sticky-note) annotation
page.Annotations.AddTextAnnotation(
    new Rectangle(72, 720, 200, 740),
    contents: "Review this paragraph",
    title: "Editor",
    open: true);

// Highlight annotation
page.Annotations.AddHighlightAnnotation(
    new Rectangle(72, 680, 300, 700),
    quadPoints: null,
    color: new double[] { 1, 1, 0 });

// Free-text annotation (rendered directly on the page)
page.Annotations.AddFreeTextAnnotation(
    new Rectangle(72, 640, 350, 660),
    contents: "Inline note",
    fontName: "Helvetica",
    fontSize: 10,
    color: new double[] { 0, 0, 0 });

using var ms = new MemoryStream();
doc.Save(ms);

링크 주석 및 동작

링크는 클릭 가능한 사각형과 PdfAction을 결합합니다. 라이브러리는
URI, GoTo, JavaScript, Named 및 Launch 동작을 지원합니다.

using var doc = Document.Open(pdfBytes);
var page = doc.Pages[1];

// URI link
var uriAction = PdfAction.CreateUri("https://aspose.com");
page.Annotations.AddLinkAnnotation(
    new Rectangle(50, 700, 200, 720), uriAction);

// GoTo link (jump to page 3)
page.Annotations.AddLinkAnnotation(
    new Rectangle(50, 660, 200, 680),
    destinationPage: 3,
    destRect: new Rectangle(0, 0, 612, 792));

// JavaScript link
var jsAction = PdfAction.CreateJavaScript("app.alert('Hello');");
page.Annotations.AddLinkAnnotation(
    new Rectangle(50, 620, 200, 640), jsAction);

doc.Save("links.pdf");

저장된 PDF를 연 후 링크를 다시 읽으려면, 주석을 LinkAnnotation 로 캐스팅하고 해당 Uri 속성을 검사하거나 PdfAction.Create 를 통해 액션 사전을 해결하십시오.


마크업 및 도형 주석

Markup 주석(하이라이트, 밑줄, 취소선)은 기존 텍스트를 표시합니다. Shape 주석(사각형, 원, 선, 잉크)은 페이지에 기하학을 그립니다.

var page = doc.Pages[1];

// Underline
page.Annotations.AddUnderlineAnnotation(
    new Rectangle(72, 600, 300, 620),
    quadPoints: null,
    color: new double[] { 1, 0, 0 });

// Square
page.Annotations.AddSquareAnnotation(
    new Rectangle(72, 540, 200, 580),
    borderColor: new double[] { 0, 0, 1 },
    fillColor: null,
    lineWidth: 1.5);

// Line
page.Annotations.AddLineAnnotation(
    new Rectangle(72, 500, 300, 520),
    x1: 72, y1: 510, x2: 300, y2: 510,
    color: new double[] { 0, 0.5, 0 },
    lineWidth: 2);

// Ink (freehand)
page.Annotations.AddInkAnnotation(
    new Rectangle(72, 440, 200, 480),
    inkPaths: new[] { new double[] { 80, 450, 120, 470, 160, 450 } },
    color: new double[] { 0.5, 0, 0.5 },
    lineWidth: 1);

스탬프 주석

스탬프 주석은 페이지에 이미지 또는 미리 정의된 아이콘을 오버레이합니다.

var stamp = new StampAnnotation(doc);
// Configure stamp properties, then add to page
page.Annotations.Add(stamp);

주석 평탄화

어떤 주석에든 Flatten()을 호출하여 해당 주석의 시각적 모습을 페이지 콘텐츠 스트림에 굽고, 대화형 주석 목록에서 제거합니다.

foreach (var annot in doc.Pages[1].Annotations)
{
    annot.Flatten();
}

AnnotationSelector와 함께하는 방문자 패턴

AnnotationSelector는 방문자 패턴을 구현하여 수동 캐스팅 없이 유형별로 주석을 필터링할 수 있습니다.

var selector = new AnnotationSelector();
doc.Pages[1].Accept(selector);

// selector.Selected now contains all annotations on page 1
foreach (var annot in selector.Selected)
{
    // Process each annotation by type
}

생성자에 형식이 지정된 주석 인스턴스를 전달하여 해당 유형만 필터링합니다:

var linkFilter = new AnnotationSelector(new LinkAnnotation(page, Rectangle.Empty));
page.Accept(linkFilter);
// linkFilter.Selected contains only LinkAnnotation instances

대화형 양식 필드

Document.Form를 통해 AcroForm 필드에 액세스합니다. Form 클래스는 필드 수준의 읽기/쓰기 작업을 제공하고 JSON 내보내기를 지원합니다.

using var doc = Document.Open(pdfBytes);

// Enumerate all fields
foreach (var field in doc.Form.Fields)
{
    Console.WriteLine($"{field.FullName}: {field.Value}");
}

Field 하위 클래스에는 TextBoxField, CheckboxField, RadioButtonField, ComboBoxField, ListBoxField, ChoiceFieldSignatureField이 포함됩니다.


양식 데이터를 JSON으로 내보내기

WidgetAnnotation는 필드 데이터를 스트림 또는 파일 경로에 직렬화하기 위한 ExportToJson 오버로드를 제공합니다. 선택적 ExportFieldsToJsonOptions 매개변수는 출력 형식을 제어합니다.

using var doc = Document.Open(pdfBytes);
var widget = (WidgetAnnotation)doc.Pages[1].Annotations[1];

using var jsonStream = new MemoryStream();
widget.ExportToJson(jsonStream);

팁 및 모범 사례

  • PDF 사용자 공간 단위(1/72 인치)에서 항상 명시적인 Rectangle 좌표를 지정하십시오.
  • 최대 유연성을 위해 AddLinkAnnotationPdfAction와 함께 사용하십시오 — URI, GoTo, JavaScript 및 Named 액션이 모두 지원됩니다.
  • 비대화형 뷰어에서도 주석이 표시되도록 하려면 PDF를 배포하기 전에 Flatten()를 호출하십시오.
  • 페이지 주석을 반복하는 대신 Document.Form.Fields을 통해 양식 필드에 접근하십시오 — 양식 컬렉션은 페이지 간 필드 그룹화를 처리합니다.
  • 특히 사용자 정의 액션의 경우, 주석 라운드트립 정확성을 확인하기 위해 문서를 저장하고 다시 열어보십시오.

일반적인 문제

IssueCauseFix
저장 후 주석이 보이지 않음사각형의 면적이 0이거나 페이지 경계 밖에 있음좌표가 페이지 내에 있는지 확인하십시오 MediaBox
LinkAnnotation.Uri returns null링크가 URI 액션이 아니라 GoTo 또는 JavaScript 액션을 사용함PdfAction.Create를 통해 액션 사전을 해결하고 ActionType를 확인하십시오
폼 필드 값이 빈 문자열임필드는 존재하지만 /V 항목이 없음처리하기 전에 field.Value가 null이 아닌지 확인하십시오
Flatten() throws주석에 /P(페이지) 참조가 없음주석이 Page.Annotations를 통해 추가되었는지 확인하십시오

자주 묻는 질문

PDF 페이지에 하이퍼링크를 어떻게 추가합니까?

page.Annotations.AddLinkAnnotation(rect, PdfAction.CreateUri(url))을 사용하여 지정된 사각형에 클릭 가능한 URI 링크를 생성합니다.

기존 PDF에서 양식 필드 값을 읽을 수 있나요?

예. Document.Open을 사용하여 문서를 열고, Document.Form.Fields을 반복한 다음 각 Field에서 Value 속성을 읽으세요.

라이브러리가 지원하는 주석 유형은 무엇입니까?

라이브러리는 텍스트, 프리 텍스트, 링크, 하이라이트, 밑줄, 취소선, 사각형, 원, 선, 잉크, 스탬프, 캐럿, 파일 첨부, 사운드, 다각형, 폴리라인, 위젯, 워터마크 및 3D 주석을 지원합니다. 모든 유형은 AnnotationCollection 헬퍼 메서드 또는 직접 생성으로 사용할 수 있습니다.

주석을 유형별로 어떻게 필터링합니까?

AnnotationSelector를 타입이 지정된 템플릿 주석과 함께 사용하십시오. page.Accept(selector)을 호출하고
selector.Selected를 검사하여 일치하는 주석을 확인하십시오.

특정 주석만 평탄화할 수 있나요?

예. 전체 컬렉션을 반복하는 대신 개별 Annotation 인스턴스에 Flatten()를 호출하십시오.


API 참조 요약

Class / MethodDescription
AnnotationCollectionPage에 대한 형식화된 컬렉션; 모든 주석 유형에 대한 Add* 도우미를 제공합니다
AnnotationCollection.AddTextAnnotation스티키 노트 주석 추가
AnnotationCollection.AddLinkAnnotationURI, 페이지 대상 또는 사용자 지정 동작이 있는 링크 추가
AnnotationCollection.AddHighlightAnnotation텍스트 강조 주석 추가
AnnotationCollection.AddInkAnnotation자유형 그리기 주석 추가
AnnotationCollection.AddSquareAnnotation사각형 모양 주석 추가
AnnotationCollection.AddCircleAnnotation타원 모양 주석 추가
AnnotationCollection.AddLineAnnotation선 주석 추가
Annotation.Flatten주석 외관을 페이지 콘텐츠에 병합
Annotation.Accept형식화된 AnnotationSelector.Visit 오버로드로 디스패치
AnnotationSelector유형별로 주석을 수집하는 방문자
LinkAnnotationURI 또는 동작을 포함하는 주석 서브클래스
TextAnnotation스티키 노트 주석
InkAnnotation스트로크 경로가 있는 자유형 그리기 주석
StampAnnotation이미지 또는 아이콘 오버레이 주석
WidgetAnnotation.ExportToJson폼 필드 데이터를 JSON으로 직렬화
FormAcroForm 파사드; 필드를 열거하고 조작
Field폼 필드의 기본 클래스 (TextBoxField, CheckboxField 등)
CheckboxField체크박스 폼 필드
TextBoxField단일/다중 라인 텍스트 입력 필드
ComboBoxField드롭다운 선택 필드
RadioButtonField라디오 버튼 그룹 필드
AnnotationType주석 종류 열거
PdfAction.CreateUriURI 링크 동작을 위한 팩토리
PdfAction.CreateJavaScriptJavaScript 동작을 위한 팩토리

참고

 한국어