Dialog File Preview para Quasar

🇬🇧 English version | 🇪🇸 Versión en español

Extensão Quasar para pré-visualizar arquivos em um diálogo modal em apps Vue 3 + Quasar, com API imperativa baseada em composable.

Índice

• Em 30 segundos
• O que é e o que inclui
• Requisitos e compatibilidade
• Instalação na app Quasar
• O que a extensão adiciona ao host
• Defaults globais (boot)
• Idioma (i18n)
• Uso rápido
• TypeScript no seu IDE
• API pública
• Opções de sessão (PreviewSessionOptions)
• Limites de tamanho para pré-visualização
• Fontes de arquivo aceitas
• Tipos de arquivo suportados
• Tipos TypeScript exportados
• Utilitários MIME
• Extensões opcionais relacionadas
• Entrypoints públicos
• Troubleshooting

Em 30 segundos

Fluxo base recomendado:

1. Instalar a extensão na sua app Quasar (quasar ext add).
2. Garantir que o boot de Pinia do host rode antes do boot desta extensão.
3. Importar useDialogFilePreview() onde precisar abrir a pré-visualização.
4. Chamar void preview.show(arquivo) — o diálogo é montado globalmente; não é necessário adicionar componentes aos seus templates.

A extensão registra boots e CSS no projeto host automaticamente após quasar ext add.

O que é e o que inclui

Diálogo modal global controlado por useDialogFilePreview() — não é um componente embutível.

• show() / hide() / canPreview(); File, Blob, URL ou objeto descriptor; galeria multi-arquivo.
• Visualizadores: imagem (zoom), PDF adaptativo, vídeo, áudio, texto; fallback + download.
• Opções de sessão em show(input, options); defaults globais no boot.
• i18n integrado en, es, pt — segue $q.lang do Quasar; overrides no boot (locale, messages).
• canPreview() síncrono (MIME + tamanho local); show() pode sondar URLs remotas.
• Integração opcional com Form Builder (InputFile / showPreview).

Requisitos e compatibilidade

O boot de Pinia do host deve executar antes do boot desta extensão.

Instalação na app Quasar

Adicionar a extensão na sua app Quasar:

quasar ext add @benjaminor-dev/dialog-file-preview

Remover:

quasar ext remove @benjaminor-dev/dialog-file-preview

Após quasar ext add, a extensão registra boots e CSS na sua app automaticamente. Não são necessários passos adicionais em uma instalação normal via npm.

O que a extensão adiciona ao host

Recursos que a extensão instala ou registra:

Install (quasar ext add / invoke): cria src/boot/bor/bor-dialog-file-preview-defaults.ts (ou .js) e o registra em quasar.config → boot: [] automaticamente. Não é necessário editá-lo manualmente em uma instalação normal. O boot do pacote (boot/dialog) e main.css são injetados pela extensão em cada dev/build (não aparecem como entradas curtas em quasar.config).

Remove (quasar ext remove): remove o defaults boot e sua entrada em quasar.config.

Ordem de boots (esta extensão): Pinia → boot dialog DFP → bor/bor-dialog-file-preview-defaults → resto. Em quasar.config você verá bor/bor-dialog-file-preview-defaults; o boot boot/dialog é adicionado pelo runner ao compilar.

O boot monta o diálogo no documento e conecta a store Pinia do host. Não é necessário importar DialogFilePreview em App.vue.

Defaults globais (boot)

Evite repetir showPrint / restrictInteraction em cada show(). Prioridade: show(input, options) → boot (configureDialogFilePreviewDefaults) → built-in.

Após quasar ext add, revise src/boot/bor/bor-dialog-file-preview-defaults.ts — template com todas as opções boot (// recomendado: …). O boot não admite title nem forcePreview — essas opções vão apenas em show(input, options).

// src/boot/bor/bor-dialog-file-preview-defaults.ts
import { configureDialogFilePreviewDefaults } from "@benjaminor-dev/quasar-app-extension-dialog-file-preview";

configureDialogFilePreviewDefaults({
  showPrint: false,
  restrictInteraction: true,
});

configureDialogFilePreview é alias de configureDialogFilePreviewDefaults.

Idioma (i18n)

Integrado en, es e pt. Por padrão, rótulos da toolbar, tooltips, controles PDF e mensagens fallback seguem o idioma do Quasar ($q.lang.isoName); se o Quasar não tiver idioma, fallback en.

Resolução de locale: boot locale → prefixo de $q.lang.isoName (es* → es, pt* → pt) → en.

Exemplo no quasar.config (português para todo o app):

framework: {
  lang: "pt-BR",
},

Template boot (após install):

configureDialogFilePreviewDefaults({
  // locale: "pt", // descomente para fixar só o idioma do Dialog File Preview
  showPrint: true,
});

Override de um único string:

configureDialogFilePreviewDefaults({
  messages: { loadingFile: "Abrindo arquivo…" },
});

Uso rápido

<script setup lang="ts">
import { useDialogFilePreview } from "@benjaminor-dev/quasar-app-extension-dialog-file-preview";

const preview = useDialogFilePreview();

function onViewPdf(file: File) {
  if (preview.canPreview(file)) {
    void preview.show(file);
  }
}
</script>

<template>
  <q-btn label="Ver PDF" @click="onViewPdf(selectedFile)" />
</template>

Vários arquivos (galeria ou anexos):

void preview.show([imageFile, pdfFile, anotherImage]);

URL remota com nome explícito:

void preview.show({
  source:
    "https://mozilla.github.io/pdf.js/web/compressed.tracemonkey-pldi-09.pdf",
  name: "tracemonkey-pldi-09.pdf",
  mimeType: "application/pdf",
});

TypeScript no seu IDE

O composable expõe uma API tipada: use autocompletar em vez de adivinhar opções.

• useDialogFilePreview() retorna DialogFilePreviewApi — métodos e refs aparecem ao digitar preview..
• Em show(arquivo, opções), o segundo argumento é PreviewSessionOptions: Ctrl+Space (Windows/Linux) ou Cmd+Space (macOS) lista showPrint, showDownload, restrictInteraction, forcePreview, etc.
• Descriptors tipados: PreviewItemInput, PreviewSourceInput no entrypoint principal ou /types.
• title e forcePreview vão apenas em show() — não em configureDialogFilePreviewDefaults (o boot usa DialogFilePreviewDefaults, mais restrito).
• No boot, locale aceita "en" \| "es" \| "pt"; messages aceita DialogFilePreviewMessages parcial (toolbar, PDF, fallback).
• Passe o cursor sobre um método: o tooltip mostra parâmetros e JSDoc.

Para verificar se um arquivo pode ser pré-visualizado antes de abrir o modal, canPreview() também está tipado conforme a fonte que você passar.

API pública

Ponto de entrada: useDialogFilePreview().

import { useDialogFilePreview } from "@benjaminor-dev/quasar-app-extension-dialog-file-preview";

const preview = useDialogFilePreview();

Métodos

Estado reativo (somente leitura)

Use canPreview() para mostrar ou ocultar botões «Ver» na sua UI sem abrir o diálogo. Se a URL não tem extensão nem MIME conhecido, passe mimeType no descriptor ou chame show() diretamente (a sondagem remota ocorre ao abrir, não em canPreview). Se o arquivo local excede o limite de tamanho, canPreview() retorna false mesmo que o MIME seja válido; show() mostra fallback salvo que você passe forcePreview: true (por sua conta e risco).

Comportamento ao abrir (show)

1. O diálogo fica visível instantaneamente.
2. Um único overlay de carregamento cobre o viewport (fundo escuro, spinner branco, «Carregando arquivo...») enquanto:
   • as fontes são enriquecidas (File/Blob/URL → itens com MIME e URL de visualização), e
   • o visualizador do item atual termina seu carregamento visível (em PDF: primeiro render do canvas, não apenas metadados do documento).
3. Os botões imprimir e download na toolbar aparecem apenas quando o visualizador emite estado pronto (ready) e a opção de sessão correspondente está ativa (showPrint / showDownload).
4. Imprimir só é oferecido para PDF, imagens e texto; vídeo e áudio não mostram o botão mesmo que showPrint seja true.
5. Ao mudar de arquivo em uma galeria (next / previous), o loader volta até o novo visualizador estar pronto.
6. Ao imprimir (botão ou Ctrl/Cmd+P), se a preparação do iframe/PDF demorar, o mesmo overlay mostra «Preparando impressão...» após ~250 ms e some no instante em que aparece o diálogo do sistema (não espera você confirmar ou cancelar).

O estado interno de preparação não é exposto em useDialogFilePreview(); basta visible e a UX do overlay.

Opções de sessão (PreviewSessionOptions)

Segundo argumento opcional de show(). Aplica-se a toda a sessão do diálogo (incluindo galeria multi-arquivo).

import type { PreviewSessionOptions } from "@benjaminor-dev/quasar-app-extension-dialog-file-preview";

void preview.show(confidentialPdf, {
  showPrint: false,
  showDownload: true,
  restrictInteraction: true,
  title: "Contrato confidencial",
});

void preview.show([scan1, scan2], {
  showGalleryNav: true,
  showPdfZoom: false,
});

// Forçar visualizador embutido mesmo excedendo o limite de tamanho (risco de desempenho / crash)
void preview.show(heavyLocalPdf, { forcePreview: true });

Se omitir options, são usados os valores padrão da tabela.

Limites de tamanho para pré-visualização

Para File / Blob com .size conhecido, a extensão aplica um teto antes de usar o visualizador embutido. Os mesmos limites usam canPreview() e show() por padrão.

Constante exportada: PREVIEW_MAX_BYTES_BY_KIND (bytes por tipo de visualizador).

Comportamento:

• canPreview(file) → false se o MIME é válido mas o tamanho excede o limite.
• show(file) (padrão) → diálogo com mensagem de arquivo grande demais, tamanho formatado e botão de download.
• show(file, { forcePreview: true }) → tenta o visualizador embutido mesmo assim. Use apenas se aceitar o risco de desempenho ou fechamento do navegador; não altera canPreview().
• URLs remotas sem tamanho conhecido: não são bloqueadas por tamanho nesta verificação síncrona (a sondagem MIME ao abrir não inclui Content-Length de forma confiável em todos os casos).

Fontes de arquivo aceitas

Tipo unificado PreviewSourceInput:

// File ou Blob direto
void preview.show(file);
void preview.show([imageFile, pdfFile]);

// URL com metadados explícitos (recomendado sem extensão clara)
void preview.show({
  source: "https://exemplo.com/documento",
  name: "contrato.pdf",
  mimeType: "application/pdf",
});

// Descriptor com File
void preview.show({
  source: selectedFile,
  name: "anexo-renomeado.pdf",
});

Tipos de arquivo suportados

Se o MIME não tem visualizador, show() ainda pode abrir o diálogo em modo fallback para permitir o download.

Visualizador de imagens

• A imagem é redimensionada para caber na área visível sem recortes.
• Clique sobre a imagem: zoom ×2 ancorado ao ponto do cursor; mova o mouse para deslocar a vista ampliada.
• Clique novamente (ou fora da imagem em modo zoom): volta ao ajuste inicial.
• O cursor indica zoom-in / zoom-out apenas sobre a imagem.

Visualizador de PDF (modo adaptativo)

O visualizador escolhe automaticamente entre duas apresentações conforme o tamanho do documento:

Em ambos os modos:

• Barra inferior: primeira / anterior / campo numérico / total / próxima / última.
• O campo de página aceita apenas dígitos, limita o valor ao intervalo 1…total, seleciona tudo ao focar e confirma com Enter ou ao sair do campo (blur).
• Os botões e o salto direto posicionam a vista (scroll suave no modo contínuo).
• Zoom com botões ± (40–100%) ou Ctrl/Cmd + roda / Ctrl/Cmd + +/-; a porcentagem aparece na toolbar se showPdfZoom não for false.
• Links internos do PDF navegam para a página correspondente.

Não há opção pública para forçar um modo: a heurística protege o navegador contra documentos enormes (ex.: centenas de MB ou milhares de páginas).

Tipos TypeScript exportados

Do entrypoint principal:

import type {
  DialogFilePreviewApi,
  DialogFilePreviewDefaults,
  PreviewBlockReason,
  PreviewSourceInput,
  PreviewItemInput,
  PreviewItem,
  PreviewKind,
  PreviewSessionOptions,
} from "@benjaminor-dev/quasar-app-extension-dialog-file-preview";

type PreviewItemInput = {
  source: File | Blob | string;
  name?: string;
  mimeType?: string;
};

Utilitários MIME

Também exportados para validar na sua UI sem abrir o diálogo:

import {
  isPreviewableMime,
  PREVIEWABLE_MIME_PREFIXES,
} from "@benjaminor-dev/quasar-app-extension-dialog-file-preview";

if (isPreviewableMime(file.type)) {
  // mostrar botão de pré-visualização
}

Valores de PREVIEWABLE_MIME_PREFIXES (prefixo com / = família completa; resto = MIME exato):

Extensões opcionais relacionadas

Se usar ambas no host:

quasar ext add @benjaminor-dev/form-builder
quasar ext add @benjaminor-dev/dialog-file-preview

Ordem de boots (stack completo):

1. Pinia (host)
2. Form Builder — boot/store
3. bor/bor-form-builder-defaults (host)
4. Table Builder — boot/store
5. bor/bor-table-builder-defaults (host)
6. Dialog File Preview — boot/dialog
7. bor/bor-dialog-file-preview-defaults (host)
8. Dialog Loader — boot/dialog
9. bor/bor-dialog-loader-defaults (host)
10. Dialog Message — boot/dialog
11. bor/bor-dialog-message-defaults (host)

Em quasar.config você verá o defaults boot de cada extensão (ex.: bor/bor-dialog-file-preview-defaults); os boots do pacote são injetados pela extensão ao compilar — não aparecem como entradas curtas na sua config.

Uso manual a partir de um callback ou botão custom (sem depender de Form Builder):

<script setup lang="ts">
import { useDialogFilePreview } from "@benjaminor-dev/quasar-app-extension-dialog-file-preview";

const preview = useDialogFilePreview();

function onPreviewFile(file: File) {
  void preview.show(file);
}
</script>

O boot também expõe a API via provide (DIALOG_FILE_PREVIEW_API_KEY) para integrações de bibliotecas irmãs — mesma instância que useDialogFilePreview().

Entrypoints públicos

Troubleshooting

Os textos da UI continuam em inglês

• Configure framework.lang no quasar.config (ex.: "pt-BR") ou chame $q.lang.set() em runtime.
• Ou fixe a extensão: configureDialogFilePreviewDefaults({ locale: "pt" }) em src/boot/bor/bor-dialog-file-preview-defaults.ts.

Boots ou estilos não aparecem em quasar.config

Em condições normais o install registra o defaults boot em boot: [] e o runner injeta boot/dialog + CSS ao compilar. Se faltar o defaults boot (projeto antigo):

npx quasar ext invoke @benjaminor-dev/dialog-file-preview

Erro: Pinia não inicializada / store indisponível

• Verifique que exista um boot de Pinia no host (app.use(pinia) ou equivalente).
• Em quasar.config, o boot de Pinia deve vir antes do boot dialog desta extensão.

useDialogFilePreview() fora de setup

Chame-o dentro de setup, outro composable ou <script setup>. Se precisar usá-lo fora do contexto de componente, garanta que o boot da extensão já foi executado (app montada).

O botão «Ver» não deveria ser mostrado

Use preview.canPreview(file) antes de renderizar a ação. Retorna false se o MIME não tem visualizador ou se o arquivo local excede o limite de tamanho. isPreviewableMime() só avalia MIME, não tamanho.

canPreview() retorna false por tamanho

O arquivo local excede o limite do seu tipo (ex.: imagem > 50 MB). Por padrão show(file) abre fallback com download. Para forçar o visualizador embutido: show(file, { forcePreview: true }) — por sua conta e risco (desempenho, aba congelada ou fechamento do navegador). canPreview() continuará false.

canPreview() retorna false em uma URL sem extensão

canPreview() não faz sondagem remota. Se a URL não tem extensão nem heurística conhecida, passe mimeType no descriptor ou chame show() diretamente.

PDF muito grande: só vejo uma página por vez

É o comportamento esperado no modo paginado: arquivos acima de ~25 MB, com mais de 40 páginas, ou documentos longos sem tamanho conhecido (> 15 páginas) são renderizados um por vez para não saturar a memória do navegador. Use a barra de páginas para navegar.

O contador de página do PDF não muda ao rolar

No modo contínuo com zoom alto (≥ 90%), aguarde um instante ao parar o scroll; o contador acompanha a página com maior área visível. Se o documento entrou em modo paginado, o scroll do viewport não se aplica — use os botões de página.

PDF ou texto de URL externa não carrega

• CORS: o servidor deve permitir fetch da sua origem (PDF remoto é baixado como blob antes de renderizar).
• Passe mimeType explícito se a URL não tem extensão.
• Verifique que a URL responde 200 (links quebrados mostram o erro no visualizador).
• Para domínios sem CORS, baixe no seu backend e passe um File/Blob local.

Exemplo de URL pública que funciona em testes:

preview.show({
  source:
    "https://mozilla.github.io/pdf.js/web/compressed.tracemonkey-pldi-09.pdf",
  name: "tracemonkey-pldi-09.pdf",
  mimeType: "application/pdf",
});

O botão de download não aparece ao abrir

É esperado no início: o download na toolbar só é habilitado quando o visualizador emite estado pronto (ready) e showDownload não é false. Enquanto prepara fontes ou carrega PDF/imagem/texto você verá «Carregando arquivo...» no viewport. Se o loader não desaparecer, revise erros de rede/CORS no console.

Não aparece o botão imprimir

• Verifique que showPrint não seja false nas opções de sessão.
• Apenas PDF, imagens e texto são imprimíveis; em vídeo/áudio o botão não é mostrado.
• Igual ao download, requer estado pronto (ready) do visualizador.

O loader de impressão demora ou não aparece

• Texto e imagem já em cache costumam abrir o diálogo instantaneamente sem overlay (comportamento esperado).
• PDF ou imagem remota podem mostrar «Preparando impressão...» enquanto o iframe é preparado; o overlay some assim que abre a janela de impressão do navegador, não ao clicar Imprimir ou Cancelar nesse diálogo.

restrictInteraction não bloqueia tudo

A opção reduz cópia, seleção e menu contextual no visualizador, mas não substitui DRM nem impede capturas de tela. Um usuário com conhecimentos técnicos ainda pode acessar o conteúdo.

O diálogo abre vazio por um instante ou demora a mostrar o arquivo

show() abre o modal imediatamente e normaliza as fontes em segundo plano. Com URLs remotas ou vários arquivos, o overlay pode permanecer alguns segundos; isso por si só não indica falha.

A pré-visualização de imagem/PDF funciona em local mas não em produção

Verifique que a extensão está instalada/invocada no build de produção e que main.css da extensão está na config gerada.

Vários arquivos: não aparece navegação

Passe um array para show([...]). A barra anterior/próximo só é mostrada quando há mais de um item e showGalleryNav não é false.

MIT © Benjamín Olvera R.