주석 및 양식
주석 및 양식
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, ChoiceField 및 SignatureField이 포함됩니다.
양식 데이터를 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좌표를 지정하십시오. - 최대 유연성을 위해
AddLinkAnnotation을PdfAction와 함께 사용하십시오 — URI, GoTo, JavaScript 및 Named 액션이 모두 지원됩니다. - 비대화형 뷰어에서도 주석이 표시되도록 하려면 PDF를 배포하기 전에
Flatten()를 호출하십시오. - 페이지 주석을 반복하는 대신
Document.Form.Fields을 통해 양식 필드에 접근하십시오 — 양식 컬렉션은 페이지 간 필드 그룹화를 처리합니다. - 특히 사용자 정의 액션의 경우, 주석 라운드트립 정확성을 확인하기 위해 문서를 저장하고 다시 열어보십시오.
일반적인 문제
| Issue | Cause | Fix |
|---|---|---|
| 저장 후 주석이 보이지 않음 | 사각형의 면적이 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 / Method | Description |
|---|---|
AnnotationCollection | 각 Page에 대한 형식화된 컬렉션; 모든 주석 유형에 대한 Add* 도우미를 제공합니다 |
AnnotationCollection.AddTextAnnotation | 스티키 노트 주석 추가 |
AnnotationCollection.AddLinkAnnotation | URI, 페이지 대상 또는 사용자 지정 동작이 있는 링크 추가 |
AnnotationCollection.AddHighlightAnnotation | 텍스트 강조 주석 추가 |
AnnotationCollection.AddInkAnnotation | 자유형 그리기 주석 추가 |
AnnotationCollection.AddSquareAnnotation | 사각형 모양 주석 추가 |
AnnotationCollection.AddCircleAnnotation | 타원 모양 주석 추가 |
AnnotationCollection.AddLineAnnotation | 선 주석 추가 |
Annotation.Flatten | 주석 외관을 페이지 콘텐츠에 병합 |
Annotation.Accept | 형식화된 AnnotationSelector.Visit 오버로드로 디스패치 |
AnnotationSelector | 유형별로 주석을 수집하는 방문자 |
LinkAnnotation | URI 또는 동작을 포함하는 주석 서브클래스 |
TextAnnotation | 스티키 노트 주석 |
InkAnnotation | 스트로크 경로가 있는 자유형 그리기 주석 |
StampAnnotation | 이미지 또는 아이콘 오버레이 주석 |
WidgetAnnotation.ExportToJson | 폼 필드 데이터를 JSON으로 직렬화 |
Form | AcroForm 파사드; 필드를 열거하고 조작 |
Field | 폼 필드의 기본 클래스 (TextBoxField, CheckboxField 등) |
CheckboxField | 체크박스 폼 필드 |
TextBoxField | 단일/다중 라인 텍스트 입력 필드 |
ComboBoxField | 드롭다운 선택 필드 |
RadioButtonField | 라디오 버튼 그룹 필드 |
AnnotationType | 주석 종류 열거 |
PdfAction.CreateUri | URI 링크 동작을 위한 팩토리 |
PdfAction.CreateJavaScript | JavaScript 동작을 위한 팩토리 |