Anotações

Adicionar suporte a anotações ao visualizador

As anotações no Doconut funcionam em duas direções: os usuários as desenham no widget do navegador e o servidor as persiste por página, ou seu código as cria programaticamente e as carrega em uma sessão aberta. De qualquer forma, elas são renderizadas nas páginas e podem ser incorporadas em exportações PDF/PNG.

O suporte a anotações é controlado pela capacidade de licença Annotation (concedida automaticamente sob uma licença Temporária ativa).

Habilitar a interface de anotações

Anotação é um módulo do visualizador, não uma barra de ferramentas independente. A página completa deve incluir os recursos do visualizador, a barra de ferramentas do visualizador, a montagem do visualizador e o objViewer inicializado; a Faixa de Anotação é então montada e anexada à mesma instância.

Emita os pacotes de anotações junto com os pacotes do visualizador — eles são controlados por licença, portanto as tags só aparecem quando a capacidade está disponível:

html
@Html.Raw(Viewer.ReferenceCss(new CssConfig
{
    IncludeViewerCss     = true,
    IncludeAnnotationCss = true   // jquery-ui.min.css + annotationBar.css
}))

@Html.Raw(Viewer.ReferenceScripts(new ScriptConfig
{
    IncludeJQuery             = true,
    IncludeViewerScripts      = true,
    IncludeAnnotationScripts  = true, // jquery-ui, raphael.js, annotation.js
    IncludeAnnotationBar      = true  // a faixa de anotação incorporada
}))

Mantenha a composição completa do visualizador visível na marcação:

html
<nav id="toolbar" aria-label="Document viewer controls">
    <!-- Controles do visualizador, incluindo o botão que abre Annotation -->
</nav>
<div id="annBarMount"></div>
<div id="divDocViewer"><div id="div_ctlDoc"></div></div>

O pacote de Anotação gera o DOM da Faixa dentro de annBarMount; você não precisa copiar seus botões ou a marcação de diálogo. Inicialize docViewer primeiro, então crie a Faixa somente quando o servidor confirmar que a Anotação está licenciada:

html
<script>
    let annBar = null;
    let currentToken = '';

    const objViewer = $('#div_ctlDoc').docViewer({
        BasePath: 'doconut',
        ResPath: 'doconut-res/images',
        onAnnLoaded:    () => annBar?.handleAnnLoaded(),
        onAnnSaved:     () => annBar?.handleAnnSaved(),
        onAnnSaveError: () => annBar?.handleAnnSaveError(),
        onAnnClosed:    () => annBar?.handleAnnClosed(),
        onError:        (message) => console.error('Viewer error:', message)
    });

    @if (Viewer.IsAnnotationEnabled)
    {
        <text>
    annBar = $('#annBarMount').doconutAnnotationBar({
        docId: 'ctlDoc',
        getRequestParams: () => ({ token: currentToken }),
        onStatus: (message) => console.log(message),
        onToast: (message, type) => console.log(type, message),
        onLayout: () => requestAnimationFrame(() => objViewer.Refit())
    });
    annBar.attach(objViewer);
        </text>
    }
</script>

Sem a capacidade, ReferenceScripts omite o script da Faixa, de modo que o if do lado do servidor impede que uma chamada doconutAnnotationBar(...) desprotegida quebre a página.

Salvar a partir da Faixa envia dados através do middleware (AnnSave), que os armazena na sessão do documento por página. Carregar (AnnLoad) ocorre automaticamente quando uma página com anotações é renderizada. Os quatro callbacks onAnn* mantêm a Faixa sincronizada com o ciclo de vida do visualizador.

Abra e feche-a a partir de qualquer barra de ferramentas do visualizador controlada pelo host:

javascript
annBar.open();
annBar.close();

A API pública da Faixa é:

MétodoPropósito
attach(objViewer)Conectar a Faixa ao visualizador inicializado; necessário uma vez
open() / close()Entrar ou sair da edição de anotações
reset()Retornar a Faixa ao seu estado fechado, sem edição
isOpen() / annotating()Ler o estado da Faixa / o estado de edição de anotações do visualizador
reopenEditable()Recarregar as anotações da página atual como objetos editáveis
updateActionState()Atualizar a disponibilidade dos controles de salvar/excluir após alterações do host
headerSlot()Obter o slot de extensão de cabeçalho opcional para controles controlados pelo host

onStatus, onToast, onLayout, onEditStart e onEditEnd são callbacks opcionais do host. O objeto endpoints pode ainda fornecer exportPdf, exportPng, imageUpload e imageList; controles sem um endpoint configurado permanecem ocultos.

Para a sequência de inicialização combinada do visualizador, Search e Anotação, veja Início Rápido.

O pacote de anotações adiciona as ferramentas de autoria no navegador, mas os dados ainda pertencem à sessão de documento do lado do servidor identificada pelo token. Reabrir a origem cria uma nova sessão; persista o XML ou o envelope de anotação codificado em sua aplicação se as anotações precisarem sobreviver além da vida útil da sessão.

Dois tipos de callback, conectados de duas maneiras

O código de anotação usa dois estilos de callback, e cada um falha silenciosamente quando conectado da outra forma:

  • onAnnLoaded, onAnnSaved, onAnnSaveError, onAnnClosed são opções de docViewer({...}), como todo callback de visualizador.
  • Created, Changed, Deleted, e Properties são funções globais encontradas por nome: o id do visualizador prefixado ao evento. Para o visualizador em #div_ctlDoc o id é ctlDoc, portanto as funções são ctlDoc_Created, ctlDoc_Changed, ctlDoc_Deleted e ctlDoc_Properties. Uma função com erro de digitação ou renomeada simplesmente nunca é chamada.

SaveAnnotations() não retorna se salvou: o resultado chega através de onAnnSaved ou onAnnSaveError. Código que lê seu valor de retorno nunca limpa sua bandeira de "alterações não salvas".

Criar anotações em C#

Obtenha um gerenciador vinculado à sessão aberta, adicione anotações e carregue-as (com using Doconut.Annotations; para os tipos e using System.Drawing; para Rectangle/Color):

csharp
app.MapPost("/api/annotations/load-sample", (string token, Viewer viewer) =>
{
    // Vinculado às dimensões da página da sessão aberta
    var manager = viewer.GetAnnotationManager(token);
    var pageCount = viewer.GetPageCount(token);

    // Um selo por página
    for (int page = 1; page <= pageCount; page++)
    {
        manager.Add(new StampAnnotation(page, new Rectangle(30, 20, 240, 90),
            $"PAGE {page}", 28, 4, Color.Maroon)
        {
            Opacity = 60,
            Rotate  = -8
        });
    }

    manager.Add(new NoteAnnotation(1, new Rectangle(420, 150, 220, 120),
        "Loaded from C# code.", Color.FromArgb(255, 255, 255, 170), 14));

    // Carregar na sessão — o widget os obtém via AnnLoad e o
    // renderizador os incorpora em exportações de imagem/PDF.
    viewer.LoadAnnotationData(token, manager);
    return Results.Ok();
});

Tipos de anotação

Todos os tipos residem em Doconut.Annotations e herdam de BaseAnnotation (número da página + Rectangle delimitador):

TipoObservações
StampAnnotationCarimbo de texto com tamanho de fonte, borda, cor; suporta Opacity, Rotate
NoteAnnotationNota adesiva com texto, cor de fundo, tamanho de fonte, TitleColor
RectangleAnnotationCores de borda + preenchimento, Title/ShowTitle
CircleAnnotationBorda + preenchimento, ShowBorder
EllipseAnnotationBorda + preenchimento, ShowBorder
TriangleAnnotationCor da borda, BackColor, ShowBorder
LineAnnotationLinha reta com largura e cor
ArrowAnnotationLinha com ponta de seta; Direction configurável (tipo ArrowDirection, pontos cardeais, padrão E)
FreehandAnnotationTraço livre a partir de pontos codificados FreehandData
ImageAnnotationImagem a partir de uma URL. Uma URL relativa é resolvida em relação ao host da requisição quando a anotação é adicionada; o servidor busca a imagem somente no momento da gravação — veja a nota de exportação abaixo

A API do AnnotationManager

MembroPropósito
Add(BaseAnnotation)Enfileirar uma anotação
GetAnnotations() / GetAnnotations(int page)Inspecionar o que o gerenciador contém
ClearAnnotations() / ClearAnnotations(int page)Remover tudo / por página
GetAnnotationData() / GetAnnotationData(int page)String codificada de dados de anotação — um envelope Base64 (o que o widget consome)
GetAnnotationXml()Forma XML

Viewer espelha as operações de carregamento/leitura contra uma sessão: LoadAnnotationData(token, manager) ou LoadAnnotationData(token, encodedData) (o envelope Base64 de GetAnnotationData()), LoadAnnotationXML(token, xml), GetAnnotationXML(token).

Exportar com anotações incorporadas

csharp
// PDF de todas as páginas com anotações renderizadas sobre elas
app.MapGet("/api/annotations/export-pdf", async (string token, Viewer viewer) =>
{
    byte[] pdf = await viewer.ExportAnnotationsToPdfAsync(token, zoom: 100);
    return Results.File(pdf, "application/pdf", "export.pdf");
});

// Ou um ZIP de PNGs por página
app.MapGet("/api/annotations/export-png-zip", async (string token, Viewer viewer) =>
{
    byte[] zip = await viewer.ExportAnnotationsToPngZipAsync(token, zoom: 100);
    return Results.File(zip, "application/zip", "annotations-png.zip");
});

Exportações usam o mesmo queimador que a renderização na tela, portanto o que os usuários veem é o que o arquivo contém — exceto para anotações de imagem, descritas a seguir.

Anotações de imagem em um host intranet exportam como "Imagem bloqueada"

O visualizador e a exportação buscam a imagem de ImageAnnotation de lugares diferentes:

SuperfícieQuem baixa a imagemEm um host intranet ou de desenvolvimento
O visualizador no navegadorO navegador do usuárioA imagem aparece
ExportAnnotationsToPdfAsync / …PngZipAsyncO servidorUm placeholder vermelho "Imagem bloqueada"

Quando o servidor busca uma imagem para incorporá‑la, ele recusa endereços que apontam de volta para redes privadas: loopback (localhost, 127.0.0.1), 0.0.0.0, link‑local (169.254.x.x), os intervalos privados 10.x, 172.16–31.x e 192.168.x, NAT de nível de operadora (100.64.0.0/10) e endereços IPv6 link‑local e unique‑local. Isso protege o servidor de ser usado para alcançar sistemas internos por meio de uma URL de imagem manipulada, e não há nenhuma opção para desativar esse comportamento.

Uma URL de imagem relativa é resolvida em relação ao host da requisição atual, de modo que em localhost, em um servidor intranet, ou em qualquer site acessado através de um endereço privado, a imagem é exibida no visualizador e a exportação contém o placeholder em seu lugar. Esse é o mecanismo de proteção em ação, não uma falha de renderização. Se as exportações precisam conter a imagem, sirva‑a a partir de um host com endereço público e use uma URL absoluta. Um nome de host que não pode ser resolvido é recusado da mesma forma; qualquer outra falha de download desenha a URL e a mensagem de erro em vermelho onde a imagem estaria.

Fluxo de persistência

  1. Abra o documento e obtenha seu token.
  2. Carregue XML ou dados codificados previamente armazenados nesse token.
  3. Permita que o widget leia e edite as anotações da sessão.
  4. Recupere XML com GetAnnotationXML(token) quando sua aplicação decidir persistir.
  5. Exporte PDF/PNG quando for necessário um entregável achatado.
  6. Feche a sessão do documento.

Não use o token opaco do visualizador como identificador permanente de anotação. Associe os dados de anotação persistidos aos seus próprios identificadores de documento e versão.

Notas de segurança e renderização

  • Solicitações de anotação usam a mesma segurança de sessão/token das solicitações de página.
  • Valide e controle qualquer URL de imagem fornecida pelo usuário para evitar falsificação de solicitações no lado do servidor.
  • Exportações aplicam a mesma decisão de licença/marca‑d’água personalizada que a renderização de página na tela.
  • Cargas úteis de desenho livre grandes e exportações de alta resolução aumentam o uso de memória; teste documentos realistas e valores de zoom.

Resolução de problemas

SintomaVerificação
Faixa de anotação está ausentecapacidade Annotation e as quatro flags de CSS/script de anotação
Callback de salvamento relata um erroExpiração de token/sessão e middleware BasePath
ctlDoc_Created (ou outra função de evento) nunca é executadaO nome da função: id do visualizador + _ + evento, como uma função global
Anotações C# não aparecemA numeração de páginas começa em 1 e os dados foram carregados no token ativo
Anotação de imagem aparece na tela mas não na exportaçãoO host da imagem tem um endereço privado ou de loopback — veja acima
Documento reaberto não tem anotaçõesPersista XML/dados fora da sessão do visualizador, então carregue‑os no novo token

Esta página foi útil?