소개

introductory post는 주석을 간략히 다룹니다: 하이라이트, 밑줄, 메모, 그리고 스탬프가 Page.AddHighlight(), Page.AddUnderline() 및 유사한 방법으로 추가됩니다. 이는 Page가 실제로 지원하는 기능의 작은 일부에 불과합니다 — 이 라이브러리의 주석 갤러리는 마크업, 자유형 도형, 실제 탐색 및 폼 제출 동작이 있는 링크, 그리고 검색을 포함하며, 모두 Page에서 직접 접근할 수 있습니다.

이 게시물은 해당 표면의 나머지 부분을 살펴봅니다: 형태와 자유형 주석 방법, Link 주석의 동작이 실제로 할 수 있는 일, 그리고 찾고자 하는 텍스트가 주석의 표시 안에 있는지 /Contents 코멘트 안에 있는지에 따라 주석 내용을 검색하는 두 가지 다른 방법.

각 주석 메서드는 방금 만든 주석에 범위가 지정된 타입화된 핸들을 반환하며, 페이지상의 모든 주석은 이후 page.Annotations를 통해 읽을 수 있습니다.

포함 내용

마크업 주석

Page.AddHighlight(), Page.AddUnderline(), Page.AddSquiggly(), 및 Page.AddStrikeOut()은 모두 동일한 형태의 옵션을 사용합니다 — 텍스트 영역을 표시하는 사변점 집합과 선택적 색상 — 그리고 네 개 모두 MarkupAnnotation를 반환합니다. 사변점은 일반적으로 텍스트 검색이나 알려진 텍스트 사각형에서 파생됩니다.

const markup = (body: [number, number, number, number], sample: string,
  add: (quads: number[]) => void): void => {
  const yMid = (body[1] + body[3]) / 2 - 6;
  const textRect: [number, number, number, number] = [body[0] + 4, yMid, body[2] - 4, yMid + 16];
  page.AddText(sample, textRect[0], textRect[1], { fontSize: 12 });
  add(rectToQuads(textRect));
};

markup(cardBody, 'Highlight this phrase', (quads) =>
  page.AddHighlight({ quads, color: [1, 1, 0], contents: 'Yellow highlight' }));
markup(cardBody, 'Underline this phrase', (quads) =>
  page.AddUnderline({ quads, color: [0, 0, 1] }));
markup(cardBody, 'Squiggle this phrase', (quads) =>
  page.AddSquiggly({ quads, color: [1, 0.5, 0] }));
markup(cardBody, 'Strike this phrase out', (quads) =>
  page.AddStrikeOut({ quads, color: [1, 0, 0] }));

노트 및 독립 텍스트

Page.AddTextNote()은(는) 클릭 시 코멘트 팝업을 열어 TextAnnotation을(를) 반환하는 클래식한 메모 아이콘을 추가합니다. Page.AddFreeText()는 대신 텍스트를 경계 상자 안에 직접 페이지에 그리며 자체 폰트 크기, 정렬 및 채우기 색상을 가집니다 — 열지 않아도 보여야 하는 호출문에 유용합니다.

page.AddTextNote({
  rect: [x, y, x + 20, y + 20], icon: 'Note', author: 'Reviewer',
  contents: 'This is a sticky-note annotation.',
});

page.AddFreeText({
  rect: [220, 60, 520, 96],
  contents: 'FreeText sample', fontSize: 10, align: 'center',
  fill: [1, 1, 0.8], width: 1,
});

도형 및 자유형 잉크

Page.AddSquare()와 Page.AddCircle()은 경계가 있는 사각형 또는 타원을 그리며, 각각 선택적으로 내부 채우기를 가질 수 있습니다. Page.AddLine()는 두 점 사이에 직선을 그리며, 각 끝에 독립적으로 선택 가능한 화살촉 스타일(startEnding/endEnding, 예: 'OpenArrow'/'ClosedArrow')을 적용합니다. Page.AddPolygon()와 Page.AddPolyline()은 평면 좌표 목록에서 닫힌 형태와 열린 다중점 형태를 그리며, Page.AddInk()는 하나 이상의 자유형 펜 스트로크를 paths 형태의 점 목록으로 기록합니다.

page.AddSquare({ rect: [50, 400, 130, 435], color: [0.8, 0, 0], fill: [1, 1, 0.5], width: 2 });
page.AddCircle({ rect: [150, 400, 230, 435], color: [0, 0.5, 0], width: 2 });

page.AddLine({
  line: [260, 417, 420, 417],
  color: [0, 0, 0.7], width: 2,
  startEnding: 'OpenArrow', endEnding: 'ClosedArrow',
});

const stroke: number[] = [];
[-8, 6, -4, 10, -2, 8, -6].forEach((dy, i) => stroke.push(440 + i * 12, 417 + dy));
page.AddInk({ paths: [stroke], color: [0.6, 0, 0.6], width: 2 });

링크와 그 동작

Page.AddLink()은(는) action가 클릭 시 동작을 결정하는 LinkAnnotation을 반환합니다: { type: 'uri', uri: '...' }은 외부 URL을 열고, { type: 'goto', page: N }는 동일 문서 내의 페이지로 이동하며, { type: 'submit', url: '...', format: 'html' }는 현재 폼 필드 값을 엔드포인트에 제출합니다. 범위를 벗어난 goto 페이지 번호나 형식이 잘못된 액션 객체는 생성 시 거부되며 조용히 받아들여지지 않습니다.

const uriLink = page.AddLink({
  rect: [10, 10, 100, 30], action: { type: 'uri', uri: 'https://example.com' },
});

const gotoLink = page.AddLink({
  rect: [10, 40, 100, 60], action: { type: 'goto', page: 2 },
});

const submitLink = page.AddLink({
  rect: [10, 70, 100, 90],
  action: { type: 'submit', url: 'https://example.com/post', format: 'html' },
});

// page.AddLink({ rect: [...], action: { type: 'goto', page: 99 } }) throws RangeError
// when 99 is out of range for the document.

주석 내용 검색

두 가지 다른 방법이 주석 텍스트를 검색하며, 이들은 의도적으로 겹치지 않습니다: Page.SearchAnnotations() 주석 자체 외관에 있는 텍스트를 검색합니다 그립니다 — a에 표시되는 보이는 라벨 FreeText 스탬프 등, 예를 들어 — 반면 Page.SearchAnnotationText() 주석에 포함된 텍스트를 검색합니다 /Contents 항목, 예를 들어 포스트잇의 댓글 본문 등. 한쪽에서 일치한다고 해서 다른 쪽에서도 일치한다는 의미는 없습니다.

page.SearchAnnotations('bravo');          // finds it if the annotation's drawn appearance contains it
page.SearchAnnotationText('bravo');       // finds it if the annotation's /Contents comment contains it

더 이상 필요하지 않은 주석은 Page.RemoveAnnotation()을(를) 사용해 직접 제거할 수 있으며, 주석 핸들이나 해당 사전을 전달하면 됩니다.

빠른 시작

패키지를 설치한 후, 기존 페이지에 하이라이트, 링크, 그리고 스티키 노트를 추가합니다:

git clone https://github.com/aspose-pdf-foss/Aspose.PDF-FOSS-for-TypeScript.git
cd Aspose.PDF-FOSS-for-TypeScript
npm install
npm run build
import { Document } from '@asposefoss/pdf';

const doc = Document.OpenFile('input.pdf');
const page = doc.Pages[0];

page.AddHighlight({ quads: [72, 700, 300, 700, 72, 715, 300, 715], color: [1, 1, 0] });

page.AddLink({
  rect: [72, 670, 200, 690], action: { type: 'uri', uri: 'https://example.com' },
});

page.AddTextNote({
  rect: [320, 670, 340, 690], icon: 'Note', author: 'Reviewer',
  contents: 'Please double-check this figure.',
});

doc.WriteTo('annotated.pdf');

지원되는 포맷

형식확장자읽기쓰기
PDFpdf✓✓
Markdownmd✓✓
SVGsvg✓✓
TIFFtiff✓✓
DOCXdocx—✓
HTMLhtml—✓
PNGpng—✓
EPUBepub—✓

오픈 소스 및 라이선스

Aspose.PDF FOSS for TypeScript은(는) MIT 라이선스로 출시되었으며, 소스 코드는 GitHub에 공개됩니다. 평가 워터마크, 사용 제한, 별도의 라이선스 파일 관리가 없으며, 이 라이브러리는 로열티 없이 상용 제품에 사용할 수 있습니다.

이 패키지는 현재 버전 0.1.0이며, 활발한 초기 개발 단계임을 나타냅니다. Node.js (>=22)만이 유일한 런타임 요구 사항이며, 이 패키지는 다른 서드파티 의존성이 없습니다.

시작하기

관련 리소스