ViewerConfig

Opções do widget de visualizador cliente

ViewerConfig (namespace Doconut) descreve a aparência e o comportamento do visualizador no navegador. Não afeta a qualidade de renderização do documento; use uma configuração de formato para isso. A classe C# e o widget JavaScript de longa data têm padrões diferentes, portanto mapeie os valores explicitamente.

Duas alterações do lado do cliente nesta versão falham silenciosamente. As funções de manipulador são passadas como opções — o widget não deriva mais seus callbacks de evento do id do contêiner — e ResPath deve apontar para o prefixo de recursos em vez da raiz da aplicação. Ambas deixam o servidor funcionando perfeitamente e não relatam nada no console do navegador. Se você está avançando uma página da biblioteca anterior, leia Retornos de chamada e Lista de verificação de caminhos antes de qualquer outra coisa.

Propriedades C#

TipoPropriedadePadrãoDescrição
boolShowThumbstrueMostrar o painel de miniaturas.
boolAutoLoadfalseCarregar automaticamente após a inicialização. O fluxo normal de tokens chama View(token) explicitamente.
boolAutoFocustrueMover o foco/rolagem do navegador para o visualizador durante a inicialização.
boolAutoPageFocustrueManter a miniatura atual visível enquanto as páginas mudam.
intPageZoom100Percentual de zoom inicial.
intZoomStep10Percentual adicionado ou removido pelos comandos de zoom.
intMaxZoom300Percentual máximo de zoom.
boolShowToolTiptrueMostrar a dica de posição da página enquanto rola.
stringToolTipPageText"Page "Prefixo usado na dica da página.
boolCacheEnabledfalseManter uma janela móvel de imagens de página na memória do navegador. Não usa localStorage.
boolLargeDocfalseAnexar elementos de página em lotes cronometrados para documentos grandes.
boolShowHyperlinksfalseRenderizar sobreposições de hiperlink quando a configuração do servidor as extrair.
boolFixedZoomtrueUsar um percentual de zoom fixo ao invés de recalculação responsiva.
intFixedZoomPercent100Zoom fixo para desktop.
intFixedZoomPercentMobile75Zoom fixo para mobile.
stringBasePath"/"Onde o visualizador envia solicitações de página. "/" está DocImage.axd na raiz do site; caso contrário, o ramo onde o host mapeia UseDoconut(), sem um / inicial ("doconut" significa /doconut/DocImage.axd).
stringResPath"doconut-res/images" (26.9.0; "doconut-res" antes)Pasta de onde o widget carrega suas próprias imagens: a pasta images sob ResourcesPath, sem um / inicial.
stringFitType"width""width", "height", ou vazio para nenhum ajuste automático. "page" não é aceito pelo widget atual.
boolRetryOn409falseHabilitar polling quando a produção de página assíncrona/distribuída responde 202 Accepted; 409 também é aceito para compatibilidade com servidores mais antigos. Não é necessário para o visualizador síncrono normal.
csharp
var config = new ViewerConfig
{
    ShowThumbs = true,
    AutoLoad = false,
    PageZoom = 100,
    MaxZoom = 300,
    FitType = "width",
    BasePath = "doconut",           // sem '/' inicial: o visualizador o adiciona ("/doconut" se tornaria //doconut, outro host)
    ResPath = "doconut-res/images",
    ShowHyperlinks = true
};

Mapeamento de C# para JavaScript

Não passe um ViewerConfig serializado diretamente para docViewer(...). A maioria das chaves do widget são camelCase, enquanto três chaves estabelecidas de caminho/ajuste são PascalCase.

C#JavaScript
ShowThumbsshowThumbs
AutoLoadautoLoad
AutoFocusautoFocus
AutoPageFocusautoPageFocus
PageZoompageZoom
ZoomStepzoomStep
MaxZoommaxZoom
ShowToolTipshowToolTip
ToolTipPageTexttoolTipPageText
CacheEnabledcacheEnabled
LargeDoclargeDoc
ShowHyperlinksshowHyperlinks
FixedZoomfixedZoom
FixedZoomPercentfixedZoomPercent
FixedZoomPercentMobilefixedZoomPercentMobile
BasePathBasePath
ResPathResPath
FitTypeFitType
RetryOn409retryOn409

Padrões JavaScript

O widget tem padrões mais antigos que diferem da classe C#. Os valores a seguir provêm da implementação atual docViewer.js.

OpçãoPadrãoObservações
leftMinWidth / leftMaxWidth220 / 800Limites da largura do painel de miniaturas.
showThumbstrueVisibilidade inicial da miniatura.
autoFocus / autoPageFocustrue / falseautoPageFocus difere do padrão C#.
thumbWidth / thumbHeight / thumbPadding150 / 200 / 10Geometria da miniatura em pixels.
pageZoom / zoomStep / maxZoom100 / 10 / 200JavaScript maxZoom difere de C# (300).
showToolTip / toolTipPageTexttrue / "Page "Dica de posição da página.
format / doc / AccessToken"" / 0 / ""Valores internos de inicialização; normalmente preenchidos por View(token).
debugModefalseDiagnósticos adicionais do cliente.
FitType""Nenhum ajuste automático a menos que fornecido.
BasePath"DocImage.axd"Padrão histórico do cliente mantido por compatibilidade. Hosts ASP.NET Core atuais devem defini-lo explicitamente para o ramo de middleware mapeado.
ResPath""Defina explicitamente para o caminho das imagens incorporadas.
cacheEnabled / cacheCount / cacheDelayfalse / 3 / 3Janela e atraso de pré-carregamento de página em memória.
autoLoadfalseFluxo de token explícito é recomendado.
largeDoctrueDifere do padrão C#.
fixedZoomfalseDifere do padrão C#.
fixedZoomPercent / fixedZoomPercentMobile100 / 50Valor móvel difere de C# (75).
showHyperlinkstrueRequer extração no lado do servidor para produzir sobreposições.

Defina todos os valores importantes de comportamento em vez de depender de qualquer conjunto de padrões:

html
<div id="divDocViewer"><div id="div_ctlDoc"></div></div>

<script>
const objViewer = $('#div_ctlDoc').docViewer({
    showThumbs: true,
    autoLoad: false,
    autoFocus: true,
    autoPageFocus: true,
    pageZoom: 100,
    zoomStep: 10,
    maxZoom: 300,
    FitType: 'width',
    cacheEnabled: false,
    largeDoc: false,
    showHyperlinks: true,
    fixedZoom: true,
    fixedZoomPercent: 100,
    fixedZoomPercentMobile: 75,
    BasePath: 'doconut',
    ResPath: 'doconut-res/images',
    onViewerReady: function () {},
    onError: function (message) { console.error('DocViewer:', message); }
});
</script>

Callbacks

CallbackArgumentosPropósito
onPageLoadingpageNumUma solicitação de página está iniciando.
onPageLoadedpageNumUma imagem de página terminou de carregar.
onThumbnailClickedpageNumO usuário selecionou uma miniatura.
onPageClickedpageNumO usuário selecionou uma página.
onDoubleClicknoneO visualizador recebeu um duplo clique.
onViewerBusynoneO visualizador entrou em estado ocupado.
onViewerReadynoneInicialização concluída.
onViewerErrornoneO visualizador entrou em estado de erro.
onErrormessageUma operação retornou uma mensagem de erro.
onCopydataDados de cópia de texto estão disponíveis.
onAutoLoadStatuspageNumCarregamento automático avançou para uma página.
onThumbsShownnoneO painel de miniaturas tornou-se visível.
onAnnLoadednoneDados de anotação carregados.
onAnnSavednoneDados de anotação salvos.
onAnnSaveErrornoneFalha ao salvar anotação.
onAnnClosednoneInterface de anotação fechada.

Mantenha os callbacks rápidos; envie telemetria de forma assíncrona e não bloqueie a renderização da página.

Cada um desses é uma opção no objeto de inicialização. O visualizador anterior procurava funções globais cujos nomes eram derivados do id do contêiner — uma página com <div id="div_ctlDoc"> só precisava declarar function ctlDoc_OnViewerReady(). Essa procura desapareceu. Passe a função explicitamente:

javascript
function ctlDoc_OnViewerBusy() { /* show your busy indicator */ }
function ctlDoc_OnViewerReady() { /* hide it */ }
function ctlDoc_Copy(text) { /* use the copied text */ }
function ctlDoc_AutoLoadStatus(pageNum) { /* report progress */ }

const objViewer = $('#div_ctlDoc').docViewer({
    // ... your existing options ...
    onViewerBusy:     ctlDoc_OnViewerBusy,      // was found by name
    onViewerReady:    ctlDoc_OnViewerReady,     // was found by name
    onCopy:           ctlDoc_Copy,              // was ctlDoc_Copy(text)
    onAutoLoadStatus: ctlDoc_AutoLoadStatus     // was ctlDoc_AutoLoadStatus(page)
});

A antiga procura estava encapsulada em um catch vazio, portanto nada foi relatado. Nesta versão as funções simplesmente nunca são executadas: o sintoma usual é um spinner ocupado que nunca para, porque o manipulador que o ocultava era onViewerReady. O documento por trás dele está sendo renderizado corretamente.

Dois ganchos de salvamento de anotação ainda são procurados por nome: SaveAnnotations() chama <elementId>_BeforeAnnSave() e <elementId>_DeletedAnnotationIds() quando existem, usando o id completo do elemento (div_ctlDoc_BeforeAnnSave para o exemplo acima).

Não há callback de clique em link — o tratamento de hiperlink está incorporado e é controlado por showHyperlinks.

Grupos de métodos públicos

GrupoMétodos comuns
Ciclo de vidaView(token, accessToken?), Close(server?), Token(), Init(), IsLoaded()
NavegaçãoGotoPage(page), ShowPage(page, focus?), Next(next), CurrentPage(), TotalPages()
Zoom e ajusteZoom(zoomIn), CurrentZoom(), FitType(value), Refit()
OrientaçãoRotate(page, angle), Flip(page, flipType)
MiniaturasHideThumbs(hide), ThumbSize(size), ReloadThumbs(width), ScrollToThumb(thumb)
PesquisaCanSearch(), Search(...), SearchMatchCount(), SearchSummary(...), GotoSearchMatch(...)
AnotaçãoSaveAnnotations(), GetAnnotations(), PushAnnotations(...), CloseAnnotations(...), ShowAnnotations(...)
CópiaCopy(...), CopyPage(pageNumber), CopyMode(enabled)

O arquivo JavaScript também contém auxiliares internos. Considere apenas os métodos usados pela interface de referência e documentados aqui ou nos guias de recursos como pontos de integração estáveis.

Repetir enquanto uma página distribuída ainda está renderizando

retryOn409 mantém seu nome histórico. É para produção assíncrona de páginas e repete a resposta de prontidão atual 202 Accepted assim como o sinal mais antigo 409 Conflict. Quando habilitado, o widget faz sondagens com esses padrões JavaScript:

OpçãoPadrão
retryInitialDelayMs250
retryBackoffFactor1.6
retryMaxDelayMs2500
retryMaxAttempts150
retryMaxTotalMs300000

Deixe desativado para o visualizador de nó único normal. Habilitá-lo não pode tornar uma renderização síncrona não suportada assíncrona.

Habilite-o quando as páginas são servidas a partir de armazenamento compartilhado com FirstPagePriority, onde páginas posteriores respondem legitimamente 202 Accepted até serem gravadas. Um cliente que não repete mostra blocos quebrados para páginas ainda em renderização — veja Implantações Distribuídas.

Lista de verificação de caminho

  • DoconutOptions.MiddlewarePath deve descrever o ramo que você realmente mapeia.
  • BasePath deve apontar para esse ramo, escrito sem um / inicial ('doconut', não '/doconut': o visualizador adiciona a barra, e //doconut/... é uma solicitação para outro host). Uma configuração comum mantém a forma de solicitação histórica DocImage.axd em um ramo MapWhen e, portanto, define BasePath: '/'.
  • DoconutOptions.ResourcesPath é a rota de recurso incorporado.
  • ResPath normalmente aponta para sua subpasta images, sem um / inicial — 'doconut-res/images' com o prefixo padrão. Um ResPath vazio era correto na biblioteca anterior, onde os recursos vinham da raiz da aplicação; não está correto aqui, e falha sem gerar erro.
  • ExtractHyperlinks deve estar habilitado na configuração de formato do servidor antes que showHyperlinks possa exibir qualquer coisa.

Esta página foi útil?