GroupDocs.Annotation é independente de UI. Ele lê e grava marcações dentro de documentos e não desenha nada na tela. Para uma biblioteca de servidor isso é a divisão correta — e deixa uma pergunta para todos que a adotam: como uma pessoa realmente desenha a anotação?
As respostas habituais são pesadas: incorporar um visualizador comercial, ou adotar a demonstração Angular e então tentar estendê-la. Existe uma mais leve. Imagens de página, um canvas e seis endpoints — sem componente de visualizador, sem framework front-end, sem etapa de build, sem CDN. Também funciona sem nenhum acesso de rede de saída, o que agora importa ainda mais.
O exemplo está no GitHub: browser-annotation-ui-net — dotnet run e arraste uma caixa na página.
A ideia em um parágrafo
Renderize cada página uma vez como PNG sem anotações e armazene em cache. Envie a lista de anotações ao navegador como dados. O canvas desenha a marcação sobre a imagem. Adicionar um comentário então é uma pequena gravação no documento mais um recarregamento da lista — não uma nova renderização da página — e a marcação permanece selecionável, clicável e respondível ao invés de estar incorporada em uma imagem.
Os endpoints
| Método | Rota | Propósito |
|---|---|---|
GET |
/api/documents/{name}/info |
contagem de páginas e o tamanho de cada página, em pontos |
GET |
/api/documents/{name}/pages/{n}/image |
PNG da página n |
GET |
/api/documents/{name}/annotations |
toda anotação como um retângulo em unidades de página |
POST |
/api/documents/{name}/annotations |
adicionar uma |
PUT |
/api/documents/{name}/annotations/{id} |
alterar a mensagem ou acrescentar uma resposta |
DELETE |
/api/documents/{name}/annotations/{id} |
remover uma |
Cada gravação retorna a lista completa, de modo que o navegador nunca precise raciocinar sobre o que o servidor agora contém.
Renderização
PreviewOptions previewOptions = new(page => File.Create(CachePath(name, page)))
{
PreviewFormat = PreviewFormats.PNG,
PageNumbers = new[] { pageNumber }, // 1-based
RenderAnnotations = false, // the canvas draws the markup
Resolution = 144
};
annotator.Document.GeneratePreview(previewOptions);
Compare o timestamp da imagem em cache com o do documento e re-renderize apenas quando o documento realmente mudou.
Pixels de entrada, unidades de página de saída
O canvas mantém seu retângulo em pixels da imagem e envia o tamanho da imagem sobre a qual desenhou — não um fator de escala:
body: JSON.stringify({
page: currentPage,
x, y, width, height,
imageWidth: img.clientWidth,
imageHeight: img.clientHeight,
message: window.prompt('Comment'),
user: 'Reviewer'
})
Essa única decisão é o que mantém a UI correta quando a resolução da pré-visualização muda, quando o CSS escala a imagem, ou quando alguém a abre em um telefone. O servidor faz a aritmética:
double scaleX = page.Width / request.ImageWidth;
double scaleY = page.Height / request.ImageHeight;
annotator.Add(new AreaAnnotation
{
PageNumber = page.PageNumber - 1, // PageInfo is 1-based, annotations are 0-based
Box = new Rectangle(
(float)(request.X * scaleX), (float)(request.Y * scaleY),
(float)(request.Width * scaleX), (float)(request.Height * scaleY)),
BackgroundColor = 0xFFE699,
PenColor = 0xE08C00,
Opacity = 0.35,
Message = request.Message,
User = new User { Id = 1, Name = request.User, Role = Role.Editor }
});
AreaAnnotation.Box é medido a partir do canto superior esquerdo da página — a mesma direção que o navegador usa — então um retângulo desenhado mapeia com escala e sem inversão.
Envie uma forma de retângulo ao navegador
A marcação de texto não compartilha essa origem. HighlightAnnotation.Points e seus relativos são medidos a partir do canto inferior esquerdo. Converta no servidor, para que o front-end veja apenas caixas superiores esquerdas:
x = minX;
y = page.Height - maxY; // flip to top-left
width = maxX - minX;
height = maxY - minY;
Faça isso e um destaque adicionado no Word, no Acrobat ou por uma revisão automatizada aparecerá no lugar correto na sua UI sem que o JavaScript saiba algo sobre a geometria do PDF.
Gravações trocam arquivos
O annotator mantém a fonte aberta e não pode salvar sobre o arquivo que está lendo:
using (Annotator annotator = new Annotator(path))
{
annotator.Add(annotation);
annotator.Save(path + ".tmp");
}
File.Move(path + ".tmp", path, overwrite: true);
InvalidatePreviewCache(name);
Utilize um bloqueio por documento ao redor de toda a sequência. Duas solicitações que leem, alteram e reescrevem o mesmo arquivo simultaneamente perderão uma das alterações.
O que este design não resolve
Vale a pena dizer claramente, pois decide se você pode entregá-lo como está:
- Os IDs de anotação mudam após uma gravação. Eles são atribuídos enquanto o documento é lido, não armazenados nele. Uma UI que recarrega a lista após cada alteração funciona. Um sistema multiusuário deve manter as anotações em sua própria tabela e usar importação e exportação para movê-las para dentro e fora do arquivo — o que também fornece um registro de auditoria e visibilidade por usuário.
- Todo o documento é reescrito a cada alteração. Adequado para um contrato de 30 páginas, inadequado para um arquivo de 2.000 páginas.
- Não há autenticação. Cada chamador no exemplo é “Reviewer”.
Execute
git clone https://github.com/groupdocs-annotation/browser-annotation-ui-net.git
cd browser-annotation-ui-net
dotnet run --project src/AnnotationUi
Ou em um contêiner, com --network none se quiser observar seu funcionamento sem nenhum tráfego de saída:
docker build -t annotation-ui .
docker run --rm -p 8080:8080 annotation-ui
A versão passo a passo está na documentação: Build an annotation UI for your web app. Se você já incorporou um visualizador PDF JavaScript, mantenha-o para exibição e use esses endpoints apenas para armazenamento — nenhuma das regras de geometria muda.