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.