Introdução
O post introdutório aborda anotações brevemente: realces, sublinhados, notas adesivas e selos, adicionados através de Page.AddHighlight(), Page.AddUnderline() e métodos semelhantes. Isso é uma pequena parte do que um Page realmente suporta — a galeria de anotações nesta biblioteca cobre markup, formas à mão livre, links com navegação real e ações de envio de formulário, e pesquisa, tudo acessível diretamente de Page.
Este post percorre o restante dessa superfície: os métodos de forma e anotação à mão livre, o que a ação de uma anotação Link pode realmente fazer, e as duas maneiras diferentes de pesquisar o conteúdo da anotação dependendo se o texto que você procura está na aparência da anotação ou em seu comentário /Contents.
Todo método de anotação retorna um manipulador tipado limitado à anotação que acabou de criar, e toda anotação em uma página pode ser lida posteriormente através de page.Annotations.
O que está incluído
Anotações de markup
Page.AddHighlight(), Page.AddUnderline(), Page.AddSquiggly() e Page.AddStrikeOut() aceitam todos o mesmo formato de opções — um conjunto de quad points marcando a região de texto e uma cor opcional — e os quatro retornam um MarkupAnnotation. Os quad points são tipicamente derivados de uma pesquisa de texto ou de um retângulo de texto conhecido.
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] }));
Notas e Texto Autônomo
Page.AddTextNote() adiciona um ícone clássico de nota adesiva que abre um pop-up de comentário ao ser clicado, retornando um TextAnnotation. Page.AddFreeText() em vez disso desenha seu texto diretamente na página dentro de uma caixa com borda, com seu próprio tamanho de fonte, alinhamento e cor de preenchimento — útil para chamadas que devem estar visíveis sem abrir nada.
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,
});
Formas e Tinta à Mão Livre
Page.AddSquare() e Page.AddCircle() desenham um retângulo ou elipse com borda, cada um com preenchimento interior opcional. Page.AddLine() desenha uma linha reta entre dois pontos, com estilos de ponta de seta selecionáveis independentemente (startEnding/endEnding, por exemplo 'OpenArrow'/'ClosedArrow') em cada extremidade. Page.AddPolygon() e Page.AddPolyline() desenham formas multi-ponto fechadas e abertas a partir de uma lista plana de coordenadas, e Page.AddInk() registra um ou mais traços de caneta à mão livre como paths de listas de pontos.
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 });
Links e Suas Ações
Page.AddLink() retorna um LinkAnnotation cujo action decide o que acontece ao clicar: { type: 'uri', uri: '...' } abre uma URL externa, { type: 'goto', page: N } pula para uma página dentro do mesmo documento e { type: 'submit', url: '...', format: 'html' } envia os valores atuais dos campos de formulário para um endpoint. Um número de página goto fora do intervalo ou um objeto de ação malformado é rejeitado no momento da criação, em vez de ser aceito silenciosamente.
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.
Pesquisa de Conteúdo de Anotações
Dois métodos diferentes pesquisam o texto da anotação, e são deliberadamente distintos: Page.SearchAnnotations() pesquisa o texto da própria aparência de uma anotação desenha — o rótulo visível em um FreeText ou carimbo, por exemplo — enquanto Page.SearchAnnotationText() pesquisa o texto carregado na anotação /Contents entrada, como o corpo do comentário de um post-it. Uma correspondência em uma não implica correspondência na outra.
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
Anotações que não são mais necessárias podem ser removidas diretamente com Page.RemoveAnnotation(), passando ou o identificador da anotação ou seu dicionário subjacente.
Início rápido
Instale o pacote, depois adicione um destaque, um link e um post-it a uma página existente:
git clone https://github.com/aspose-pdf-foss/Aspose.PDF-FOSS-for-TypeScript.git
cd Aspose.PDF-FOSS-for-TypeScript
npm install
npm run buildimport { 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');
Formatos suportados
| Formato | Extensão | Ler | Escrever |
|---|---|---|---|
| ✓ | ✓ | ||
| Markdown | md | ✓ | ✓ |
| SVG | svg | ✓ | ✓ |
| TIFF | tiff | ✓ | ✓ |
| DOCX | docx | — | ✓ |
| HTML | html | — | ✓ |
| PNG | png | — | ✓ |
| EPUB | epub | — | ✓ |
Código aberto e Licenciamento
Aspose.PDF FOSS para TypeScript é lançado sob a licença MIT, com o código-fonte publicado em GitHub. Não há marca d’água de avaliação, limite de uso ou arquivo de licença separado para gerenciar, e a biblioteca pode ser usada em produtos comerciais sem royalties.
O pacote está atualmente na versão 0.1.0, refletindo desenvolvimento ativo em estágio inicial. Node.js (>=22) é o único requisito de runtime, e o pacote não tem outras dependências de terceiros.
