Annotations
주석
이 페이지에서는 PDF 주석을 생성, 읽기, 검색 및 평탄화하는 방법을 다룹니다. Page는 주석 하위 유형당 하나의 Add*() 메서드를 제공하며, 각 메서드는 실시간 Annotation 핸들을 반환합니다; Annotation 기본 클래스와 그 하위 유형들(TextAnnotation, StampAnnotation, MarkupAnnotation 등)은 주석의 속성을 읽고 편집할 수 있도록 제공합니다.
마크업, 메모 및 링크 주석 만들기
네 가지 텍스트 마크업 메서드 — Page.AddHighlight(), Page.AddUnderline(), Page.AddSquiggly(), 및 Page.AddStrikeOut() — 은 quads 배열(/QuadPoints)을 받아 MarkupAnnotation을 반환합니다. Page.AddLink()은 URI 또는 내부 동작이 있는 클릭 가능한 영역을 생성하고, Page.AddTextNote()은 contents 텍스트가 포함된 팝업을 여는 스티키 노트 아이콘을 추가하여 TextAnnotation을 반환합니다.
page.AddHighlight({ quads, color: [1, 1, 0], contents: 'Yellow highlight' });
page.AddUnderline({ quads, color: [0, 0, 1] });
page.AddStrikeOut({ quads, color: [1, 0, 0] });
page.AddLink({
rect: [100, 700, 220, 716],
action: { type: 'uri', uri: 'https://example.com' },
border: 0,
});
page.AddTextNote({
rect: [x, y, x + 20, y + 20], icon: 'Note', author: 'Reviewer',
contents: 'This is a sticky-note annotation.',
});Page는 또한 형태 및 자유형 메서드 — AddSquare(), AddCircle(), AddLine(), AddPolygon(), AddPolyline(), AddInk(), AddFreeText(), AddCaret(), 및 AddStamp() — 를 제공하며, 각 메서드는 해당 하위 유형에 대한 주석 핸들을 반환하고, 그 /AP 외관을 자동으로 생성합니다.
주석 읽기 및 나열
page.Annotations은 페이지의 모든 Annotation의 배열입니다. 하위 유형에 관계없이 모든 주석은 Subtype, Rect, Color, Contents, Name, Layer, ModDate, Flags, Print, Hidden, 및 Opacity를 제공하며; 하위 유형은 StampAnnotation.StampName 또는 MarkupAnnotation.QuadPoints와 같은 자체 필드를 추가합니다.
const freeText = page.Annotations.find((a) => a.Subtype === 'FreeText');
if (freeText) {
freeText.Contents = 'Updated note text';
}주석 텍스트 검색
Page.SearchAnnotationText() and Page.SearchAnnotations() 고의적으로 분리됩니다. SearchAnnotationText() 텍스트 및 주석에서 일치 항목을 찾습니다 carries 그림을 그리는 대신 — 노트의 /Contents, 그 저자 (/T), 혹은 그 주제 (/Subj) — 그리고 반환합니다 AnnotationTextMatch[] ({ annot, key, value, text }). SearchAnnotations() 텍스트 및 주석에서 일치 항목을 찾습니다 draws, 예를 들어 a FreeText’s 가시적인 단어들을 반환하고 AnnotationMatch[] ({ annot, text, quads }).
// A sticky note's /Contents text — found by SearchAnnotationText, not SearchAnnotations.
const textHits = page.SearchAnnotationText('body secret');
console.log(textHits[0].key, textHits[0].value); // 'Contents' 'body secret'
// A FreeText's rendered words — found by SearchAnnotations, not SearchAnnotationText.
const drawnHits = page.SearchAnnotations('bravo');주석 평탄화
Annotation.Flatten()은 주석의 /AP 모습을 페이지의 콘텐츠 스트림에 /Rect에 직접 삽입하고, 이후 /Annots에서 제거합니다. 결과는 영구적이고 정적인 콘텐츠가 되며 — 더 이상 클릭하거나 편집하거나 숨길 수 있는 별개의 주석이 아닙니다.
const note = page.AddTextNote({
rect: [72, 660, 92, 680], icon: 'Comment', contents: 'Reviewed and approved.',
});
note.Flatten();팁 및 모범 사례
Flatten()을(를)Add*()호출이 직접 반환한 객체에 호출하십시오 — 이후에page.Annotations를 다시 읽어 얻은 주석은 다른 객체 참조입니다.SearchAnnotationText()와SearchAnnotations()은 서로 다른 텍스트를 다룹니다: 문구가 노트에 입력되었든 페이지에 그려졌든 상관없이 찾고 싶다면 두 가지 모두 실행하십시오.- 네 가지 마크업 방법(
AddHighlight,AddUnderline,AddSquiggly,AddStrikeOut)은/AP모습을 자동으로 생성합니다 — 수동으로 콘텐츠 스트림을 그릴 필요가 없습니다. - 암호화는 왕복을 견뎌냅니다:
Document.Save()전에encrypt옵션을 사용해 추가된 주석은 문서를 다시 열고 복호화한 후에도 유효합니다.
일반적인 문제
| 문제 | 원인 | 수정 |
|---|---|---|
page.Annotations.find()은(는) 방금 추가한 주석에 대해 undefined을(를) 반환합니다 | 주석이 추가되기 전에 캡처된 오래된 배열을 검색 중 | Add*() 호출 후에 page.Annotations을 다시 읽거나, 호출이 반환한 핸들을 직접 사용하십시오 |
SearchAnnotationText()은 페이지에 보이는 텍스트에 대해 아무 것도 찾지 못합니다 | 텍스트는 주석에 의해 그려집니다(예: FreeText의 본문), /Contents에 포함되지 않습니다. | SearchAnnotations()을(를) 대신 사용하십시오 — 그것은 그려진 텍스트와 일치합니다. |
Flatten() 이후에도 주석이 여전히 편집 가능한 것으로 표시됩니다. | Flatten()가 Add*()이 반환한 핸들이 아니라 복사본에 호출되었습니다. | 생성 메서드가 직접 반환한 객체에 Flatten()를 호출하십시오. |
FAQ
SearchAnnotationText와 SearchAnnotations의 차이점은 무엇인가요?
SearchAnnotationText() 주석의 텍스트와 일치합니다. carries — /Contents, /T (author), 또는 /Subj — 예를 들어 스티키 노트의 본문과 같습니다. SearchAnnotations() 텍스트와 주석을 일치시킵니다 draws 페이지에, 예를 들어 a FreeText’s 가시적인 단어들. 두 개는 서로 겹치지 않습니다: 한쪽에서의 일치는 다른쪽에 나타나지 않습니다.
주석을 영구적이고 비대화형으로 만들려면 어떻게 해야 하나요?
Flatten()를 Add*() 메서드가 반환한 Annotation 핸들에 호출하십시오. 이렇게 하면 해당 주석의 외관이 페이지의 콘텐츠 스트림에 고정되고 /Annots에서 제거됩니다.
지원되는 주석 하위 유형은 무엇입니까?
Page은(는) 텍스트 마크업(AddHighlight, AddUnderline, AddSquiggly, AddStrikeOut), 노트 및 콜아웃(AddTextNote, AddFreeText, AddCaret), 링크(AddLink), 도형(AddSquare, AddCircle, AddLine, AddPolygon, AddPolyline), 자유형 잉크(AddInk), 스탬프(AddStamp), 그리고 파일 첨부(AddFileAttachment)를 만들기 위한 메서드를 노출합니다.
페이지에 이미 있는 모든 주석을 어떻게 나열하나요?
page.Annotations을(를) 읽으세요, Annotation 핸들의 배열입니다. 각각은 Subtype, Rect, Color, Contents 및 기타 공유 속성을 노출하므로 표준 배열 메서드로 필터링하거나 검사할 수 있습니다.
API Reference 요약
| 클래스/메서드 | 설명 |
|---|---|
Annotation | 기본 핸들은 모든 주석 위에 적용됩니다; Subtype, Rect, Color, Contents, Name, Flags, Print, Hidden, Opacity을(를) 노출합니다 |
Annotation.Flatten() | 주석의 외관을 정적 페이지 콘텐츠에 포함시킵니다 |
TextAnnotation | /Text 스티키노트 핸들; Icon, Open, Author를 추가합니다 |
StampAnnotation | /Stamp 고무 도장 핸들; StampName를 추가합니다 |
MarkupAnnotation | 텍스트 마크업 핸들 (Highlight/Underline/StrikeOut/Squiggly); MarkupType, QuadPoints를 추가합니다 |
Page.AddHighlight() / Page.AddUnderline() / Page.AddStrikeOut() / Page.AddSquiggly() | /QuadPoints 위에 텍스트 마크업 주석을 생성합니다 |
Page.AddTextNote() | 스티키 노트 주석 만들기 |
Page.AddLink() | URI 또는 내부 동작이 포함된 클릭 가능한 링크 만들기 |
Page.Annotations | 페이지에 있는 모든 Annotation를 배열로 |
Page.SearchAnnotationText() | 주석이 포함하는 텍스트 찾기 (/Contents, /T, /Subj) |
Page.SearchAnnotations() | 페이지에 주석이 그리는 텍스트 찾기 |