Dialog Loader para Quasar

🇺🇸 English | 🇪🇸 Versión en español

Extensão Quasar para diálogo modal de carregamento global 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
• Variantes visuais
• Indicadores de carregamento (spinner)
• Anti-piscar e operações concorrentes
• Tipos TypeScript exportados
• 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 do Pinia do host roda antes do boot desta extensão.
3. Importar useDialogLoader() onde executar pedidos async.
4. Envolver a tarefa com await loader.run({ task: () => api.save() }) — ou { label, task } para override pontual.

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

O que é e o que inclui

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

• run({ task }) ou run(task) — caso principal; usa o label do boot se não passar label.
• run({ label, task }) — override pontual do texto sem alterar o boot.
• show() / hide() — controlo manual com contador interno de operações pendentes.
• Três variantes de apresentação: glass, primary, minimal.
• Spinners configuráveis (subset curado do Quasar; default ios).
• Anti-piscar: delays de abertura/fecho e tempo mínimo visível.
• Defaults globais no boot do host (gap, font, variant, spinner…); label por chamada opcional.
• i18n built-in en, es, pt — segue $q.lang do Quasar; overrides no boot (locale, messages).
• Controlos em task: pause, resume, cancel e signal (AbortSignal).

Requisitos e compatibilidade

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

Instalação na app Quasar

quasar ext add @benjaminor-dev/dialog-loader

Remover:

quasar ext remove @benjaminor-dev/dialog-loader

Após quasar ext add, a extensão regista boots e CSS na sua app automaticamente. Não precisa de passos adicionais numa instalação normal via npm.

O que a extensão adiciona ao host

Recursos instalados ou registados pela extensão:

Install (quasar ext add / invoke): cria src/boot/bor/bor-dialog-loader-defaults.ts (ou .js) e regista-o em quasar.config → boot: [] automaticamente. Não precisa de editar manualmente numa instalação normal. O boot de pacote (boot/dialog) e main.css são injetados em cada dev/build (não aparecem como entradas curtas em quasar.config).

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

Ordem mínima de boots:

1. Pinia (host)
2. Dialog Loader — boot/dialog
3. bor/bor-dialog-loader-defaults (host)

Em quasar.config só verá bor/bor-dialog-loader-defaults; o boot boot/dialog é adicionado pelo runner ao compilar.

O boot monta o diálogo no documento e liga a store Pinia do host. Não precisa importar DialogLoader em App.vue.

Defaults globais (boot)

Evite repetir variant, spinner, gap, font, delays e zIndex em cada chamada. Prioridade do label: run({ label }) / show() → boot label → i18n (locale / $q.lang / en).

Após quasar ext add, reveja src/boot/bor/bor-dialog-loader-defaults.ts — plantilla com todas as opções boot (// recomendado: …) e instruções de idioma no comentário do ficheiro.

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

configureDialogLoaderDefaults({
  // locale: "pt", // descomente para fixar um idioma específico no Dialog Loader
  variant: "glass",
  spinner: "ios",
  openDelayMs: 120,
  hideDelayMs: 450,
  minVisibleMs: 600,
  backdropBlur: "blur(10px)",
  zIndex: 6000,
  gap: "2rem",
  font: {
    family: "Arial, sans-serif",
    size: "1.35rem",
  },
  spinnerColor: {
    light: "primary",
    dark: "white",
  },
  spinnerTrackColor: {
    light: "grey-4",
    dark: "grey-7",
  },
});

Idioma (i18n)

Built-in en, es e pt. Por defeito o label segue o idioma do Quasar ($q.lang.isoName); se o Quasar não definir idioma, cai em en ("Loading...").

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

Resolução do label: run({ label }) / show(label) → boot label → boot messages.loadingLabel → catálogo built-in → en.

Chaves i18n built-in: loadingLabel (texto padrão do loader), operationCancelled (DialogLoaderRunCancelledError quando cancel() aborta a tarefa).

Exemplo Quasar config (português em toda a app):

// quasar.config.ts
framework: {
  lang: "pt-BR",
},

configureDialogLoader é alias de configureDialogLoaderDefaults.

Se omitir spinnerColor / spinnerTrackColor, o fallback depende de variant: em primary o spinner é branco; em glass e minimal usa primary e grey-4. Configure { light, dark } no boot para adaptar o spinner ao tema do host ($q.dark).

Uso rápido

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

const loader = useDialogLoader();

async function onSave() {
  try {
    await loader.run({ task: () => api.save(formData) });
    // notify.success('Guardado');
  } catch (error) {
    // notify.error('Erro ao guardar');
  }
}
</script>

<template>
  <q-btn label="Guardar" @click="onSave" />
</template>

Sem label explícito — usa i18n conforme $q.lang (p. ex. "Carregando..." com lang: 'pt-BR'):

await loader.run(() => fetchUsers());
// equivalente:
await loader.run({ task: () => fetchUsers() });

Override pontual do texto:

await loader.run({ label: "A guardar...", task: () => api.save(formData) });

Controlos opcionais dentro de task:

await loader.run({
  task: async ({ pause, resume, cancel, signal }) => {
    await api.prepare();
    pause(); // oculta overlay; a tarefa continua
    await api.finishInBackground();
    resume(); // volta a mostrar o loader
    await fetch("/api/finalize", { signal }); // cancel() aborta este fetch
  },
});

pause(), resume() e cancel() são idempotentes e só afetam essa operação de run().

import { DialogLoaderRunCancelledError } from "@benjaminor-dev/quasar-app-extension-dialog-loader";

try {
  await loader.run({ task: ({ signal }) => fetch(url, { signal }) });
} catch (error) {
  if (error instanceof DialogLoaderRunCancelledError) return;
  throw error;
}

Controlo manual (menos habitual):

loader.show("A processar...");
try {
  await longTask();
} finally {
  loader.hide();
}

TypeScript no seu IDE

Não memorize a API: deixe o autocompletado guiá-lo.

• useDialogLoader() devolve DialogLoaderApi — métodos e refs aparecem ao escrever loader..
• Em configureDialogLoaderDefaults({ ... }), Ctrl+Space (Windows/Linux) ou Cmd+Space (macOS) lista variant, spinner, spinnerColor, spinnerTrackColor, gap, font, openDelayMs, etc.
• variant aceita "glass" \| "primary" \| "minimal"; spinner aceita os valores de DIALOG_LOADER_SPINNER_TYPES (p. ex. "ios", "dots", "circular").
• run() — overloads: run(task) ou run({ task, label? }); em task, desestruture { pause, resume, cancel, signal } com tipos inferidos.
• No boot, locale aceita "en" \| "es" \| "pt"; messages aceita DialogLoaderMessages parcial (loadingLabel, operationCancelled).
• Passe o cursor sobre um método: o tooltip mostra parâmetros e JSDoc.

Se algo não aparecer no autocompletado, costuma ser uma prop inexistente ou import incorreto — reveja o entrypoint principal antes de procurar no README.

API pública

Ponto de entrada: useDialogLoader().

import { useDialogLoader } from "@benjaminor-dev/quasar-app-extension-dialog-loader";

const loader = useDialogLoader();

Métodos

Estado reativo (somente leitura)

Quando usar run vs show / hide

Variantes visuais

Configure variant no boot do host (ou built-in).

Indicadores de carregamento (spinner)

Configure spinner no boot. Subset curado de spinners Quasar:

Constante exportada: DIALOG_LOADER_SPINNER_TYPES — útil para validar valores em runtime.

Anti-piscar e operações concorrentes

A store mantém um pendingCount: cada show() / início de run() incrementa; cada hide() / fim de run() decrementa. A UI só fecha quando o contador chega a zero.

Delays configuráveis no boot:

• openDelayMs — não mostra o diálogo se todas as operações terminarem antes.
• minVisibleMs — evita flash de fecho imediato após abrir.
• hideDelayMs — alinha o fecho com a animação fade do overlay.

Várias chamadas concorrentes a run() ou show() partilham o mesmo diálogo até todas terminarem.

Tipos TypeScript exportados

Desde o entrypoint principal:

import {
  useDialogLoader,
  DialogLoaderRunCancelledError,
  resolveDialogLoaderMessages,
  resolveExtensionLocale,
  type DialogLoaderApi,
  type DialogLoaderRunControls,
  type DialogLoaderRunOptions,
  type DialogLoaderRunTask,
  type DialogLoaderDefaults,
  type DialogLoaderFontDefaults,
  type DialogLoaderMessages,
  type DialogLoaderThemeColor,
  type DialogLoaderThemeColorValue,
  type DialogLoaderThemeMode,
  type DialogLoaderVariant,
  type DialogLoaderSpinnerType,
  type ExtensionLocale,
  type ResolvedDialogLoaderDefaults,
} from "@benjaminor-dev/quasar-app-extension-dialog-loader";

Também se exportam BUILTIN_DIALOG_LOADER_DEFAULTS, DIALOG_LOADER_SPINNER_TYPES, resolveDialogLoaderMessages, resolveExtensionLocale, configureDialogLoader (alias) e DIALOG_LOADER_API_KEY (chave de provide do boot para integrações avançadas).

Entrypoints públicos

O que importa no seu código:

Boot (boot/dialog) e estilos (main.css) são registados pela extensão em quasar.config ao instalar — não precisa importá-los manualmente.

Troubleshooting

Vejo "Loading..." e quero português (ou espanhol)

O default sem configurar Quasar é inglês. Escolha uma linha:

// quasar.config.ts — recomendado (toda a app Quasar)
framework: {
  lang: "pt-BR",
},

// src/boot/bor/bor-dialog-loader-defaults.ts — fixar só o locale do Dialog Loader
configureDialogLoaderDefaults({ locale: "pt" });

Override de um só texto:

configureDialogLoaderDefaults({ messages: { loadingLabel: "Carregando..." } });

O label não muda se o idioma for alterado durante um run()

Se o usuário mudar o idioma da app enquanto o loader está visível, o texto na tela permanece o de quando run() / show() começou. Ao fechar o loader, o label em repouso segue o novo locale. Para fixar um idioma em toda a extensão, use locale no boot.

Boots ou estilos não aparecem em quasar.config

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

npx quasar ext invoke @benjaminor-dev/dialog-loader

Erro: Pinia não inicializada

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

useDialogLoader() fora de setup

Chame dentro de setup, outro composable ou <script setup>. O boot deve ter sido executado (app montada).

O loader pisca em pedidos rápidos

Ajuste no boot: suba openDelayMs, minVisibleMs ou ambos.

O loader não fecha após show()

Cada show() requer um hide() correspondente (ou use run(), que equilibra automaticamente).

O diálogo fica atrás de outro overlay

Revise zIndex no boot (default 6000).

Mudei spinner no boot e não se reflete

Reinicie o dev server. Confirme que edita src/boot/bor/bor-dialog-loader-defaults.ts do host.

MIT © Benjamín Olvera R.