Dialog Message para Quasar

🇺🇸 English | 🇧🇷 Versão em português

Extensión Quasar para diálogos modales de mensaje (alertas y confirmación) en apps Vue 3 + Quasar, con API imperativa basada en composable.

Tabla de contenidos

• En 30 segundos
• Qué es y qué incluye
• Requisitos y compatibilidad
• Instalación en app Quasar
• Qué agrega la extensión al host
• Defaults globales (boot)
• Idioma (i18n)
• Uso rápido
• TypeScript en tu IDE
• API pública
• Presets visuales
• Icono y botones por tema
• Alertas vs confirmación
• Tipos TypeScript exportados
• Entrypoints públicos
• Troubleshooting

En 30 segundos

Flujo base recomendado:

1. Instalar la extensión en tu app Quasar (quasar ext add).
2. Asegurar que el boot de Pinia del host corre antes que el boot de esta extensión.
3. Importar useDialogMessage() donde muestres feedback al usuario.
4. Llamar await message.success() (preset i18n) o await message.success({ text: '...' }); confirm: const ok = await message.confirm({ text: '...' }).

La extensión registra boots y CSS en el proyecto host automáticamente tras quasar ext add.

Qué es y qué incluye

Diálogo modal global controlado por useDialogMessage() — no es un componente embebible.

• Presets de alerta — success, info, warn, error (un botón Aceptar).
• Confirmación — confirm() con dos botones (Cancelar / Confirmar) y Promise<boolean>.
• Defaults por preset en boot del host (title, icon, iconColor, labels).
• i18n built-in en, es, pt — presets y botones siguen $q.lang; overrides en boot (locale, messages, presets).
• Tema light / dark — iconColor: { light, dark } y buttonStyle global o por preset.
• Override por llamada — title, text, icon, colores, variantes de botón y labels.
• onAccept / onCancel — side-effects opcionales al pulsar botones.
• hide() — cierre imperativo sin ejecutar callbacks.
• persistent — impide cerrar con backdrop o Esc (configurable en boot).

Requisitos y compatibilidad

El boot de Pinia del host debe ejecutarse antes del boot de esta extensión.

Instalación en app Quasar

quasar ext add @benjaminor-dev/dialog-message

Remover:

quasar ext remove @benjaminor-dev/dialog-message

Tras quasar ext add, la extensión registra boots y CSS en tu app automáticamente. No necesitas pasos adicionales en una instalación normal desde npm.

Qué agrega la extensión al host

Recursos que instala o registra la extensión:

Install (quasar ext add / invoke): crea src/boot/bor/bor-dialog-message-defaults.ts (o .js) y lo registra en quasar.config → boot: [] automáticamente. No hace falta editarlo a mano en una instalación normal. El boot de paquete (boot/dialog) y main.css los inyecta la extensión en cada dev/build (no aparecen como entradas cortas en quasar.config).

Remove (quasar ext remove): elimina el defaults boot y su entrada en quasar.config.

Orden de boots mínimo:

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

En quasar.config solo verás bor/bor-dialog-message-defaults; el boot boot/dialog lo añade el runner al compilar.

El boot monta el diálogo en el documento y conecta la store de Pinia del host. No necesitas importar DialogMessage en App.vue.

Defaults globales (boot)

Evita repetir títulos, iconos, labels y medidas en cada llamada. Prioridad: opciones por llamada → boot del host → i18n (locale / $q.lang / en).

Tras quasar ext add, revisa src/boot/bor/bor-dialog-message-defaults.ts — plantilla con instrucciones de idioma en el comentario del archivo.

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

configureDialogMessageDefaults({
  // locale: "es", // descomenta para fijar un idioma concreto en Dialog Message
  width: "420px",
  persistent: true,
  zIndex: 7000,
  gap: "1rem",
  actionsGap: "2rem",
  font: {
    family: "Arial, sans-serif",
    sizeTitle: "1.4rem",
    sizeText: "1.2rem",
  },
  buttonStyle: {
    light: {
      acceptColor: "primary",
      acceptVariant: "unelevated",
      cancelColor: "primary",
      cancelVariant: "outline",
    },
    dark: {
      acceptColor: "primary",
      acceptVariant: "unelevated",
      cancelColor: "white",
      cancelVariant: "outline",
    },
  },
});

Idioma (i18n)

Built-in en, es y pt para títulos, textos y labels de presets (success, info, warn, error, confirm). Por defecto sigue $q.lang; sin idioma Quasar, cae en en.

Resolución de locale: boot locale → prefijo de $q.lang.isoName (es* → es, pt* → pt) → en.

Resolución de textos: opciones por llamada → boot presets.<variant> → boot messages → catálogo built-in → en. Iconos y colores default vienen de visuales built-in; override visual en boot presets.

Ejemplo español en toda la app:

// quasar.config.ts
framework: {
  lang: "es",
},

Override de un preset (visual + texto):

configureDialogMessageDefaults({
  presets: {
    confirm: { title: "¿Eliminar registro?", acceptLabel: "Eliminar" },
  },
});

Override i18n sin cambiar iconos:

configureDialogMessageDefaults({
  messages: {
    acceptLabel: "Entendido",
    presets: { warn: { title: "Atención", text: "Revisa los datos" } },
  },
});

configureDialogMessage es alias de configureDialogMessageDefaults.

Cada preset incluye title, text y labels por idioma. Override en boot solo si necesitas personalizar iconos o textos de dominio.

Variantes de preset: success, info, warn, error, confirm.

Prioridad por campo: llamada → preset (boot) → i18n → global (boot). Dentro de botones, buttonStyle.<tema> gana sobre acceptColor / cancelColor planos del mismo nivel.

Uso rápido

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

const message = useDialogMessage();

async function onSave() {
  try {
    await api.save(formData);
    await message.success(); // preset i18n (title + text)
    // await message.success({ text: "Se ha guardado el registro" });
  } catch (error) {
    await message.error({ text: "No se pudo guardar" });
  }
}

async function onDelete(item: { id: string }) {
  const confirmed = await message.confirm({
    title: "Eliminar registro",
    text: "Se eliminará el registro seleccionado. ¿Deseas continuar?",
  });
  if (!confirmed) return;

  await api.delete(item.id);
  await message.success({ text: "Registro eliminado" });
}
</script>

<template>
  <q-btn label="Guardar" @click="onSave" />
  <q-btn label="Eliminar" color="negative" @click="onDelete({ id: '1' })" />
</template>

Alerta con override puntual de título e icono:

await message.info({
  title: "Aviso importante",
  text: "Revisa los datos antes de continuar",
  icon: "campaign",
  iconColor: "warning",
});

Confirm con override de botones solo en dark:

const ok = await message.confirm({
  text: "¿Deseas continuar?",
  buttonStyle: {
    dark: { cancelColor: "grey-4" },
  },
});
if (!ok) return;

Side-effect al aceptar (p. ej. logout):

await message.warn({
  text: "Tu sesión expirará en 5 minutos",
  onAccept: async () => {
    await auth.refreshSession();
  },
});

TypeScript en tu IDE

No memorices la API: deja que el autocompletado te guíe.

• useDialogMessage() devuelve DialogMessageApi — métodos y refs aparecen al escribir message..
• En configureDialogMessageDefaults({ ... }), Ctrl+Space / Cmd+Space lista presets, buttonStyle, gap, font, zIndex, etc.
• Dentro de presets.success, presets.confirm, etc., el IDE sugiere title, text, icon, iconColor, acceptLabel, cancelLabel, buttonStyle.
• En font, el IDE sugiere family, sizeTitle, sizeText.
• iconColor acepta string plano o { light, dark }; buttonStyle agrupa colores y variantes de botones por tema.
• success / info / warn / error aceptan DialogMessageOptions; confirm acepta DialogMessageConfirmOptions (añade cancelLabel, cancelColor, cancelVariant, onCancel).
• confirm() resuelve Promise<boolean>; los presets de alerta resuelven Promise<void> al pulsar Aceptar.
• Pasa el cursor sobre un método: el tooltip muestra parámetros y JSDoc.

Si algo no aparece en autocompletado, suele ser una prop inexistente o un import incorrecto — revisa el entrypoint principal antes de buscar en el README.

API pública

Punto de entrada: useDialogMessage().

import { useDialogMessage } from "@benjaminor-dev/quasar-app-extension-dialog-message";

const message = useDialogMessage();

Métodos

Estado reactivo (solo lectura)

Opciones por llamada (DialogMessageOptions)

DialogMessageConfirmOptions extiende lo anterior con:

Presets visuales

Configura cada preset en presets del boot (o usa los built-in).

Constante exportada: DIALOG_MESSAGE_VARIANTS — lista de variantes válidas.

Icono y botones por tema

El diálogo resuelve colores según $q.dark.isActive (light / dark).

Icono — iconColor

En boot (por preset) o por llamada:

iconColor: { light: "negative", dark: "red-4" }
// o plano (mismo color en ambos temas):
iconColor: "positive"

Botones — buttonStyle

Global en boot (aplica a todos los presets) o parcial por preset / llamada:

buttonStyle: {
  light: {
    acceptColor: "primary",
    acceptVariant: "unelevated",
    cancelColor: "primary",
    cancelVariant: "outline",
  },
  dark: {
    acceptColor: "primary",
    acceptVariant: "unelevated",
    cancelColor: "white",
    cancelVariant: "outline",
  },
}

Campos por tema en buttonStyle: acceptColor, acceptVariant, cancelColor, cancelVariant.

Built-in de variantes: Aceptar → unelevated, Cancelar → outline.

Alertas vs confirmación

Solo puede haber un diálogo visible a la vez. Una nueva llamada cierra la sesión anterior (confirm pendiente resuelve false).

Tipos TypeScript exportados

Desde el entrypoint principal:

import {
  useDialogMessage,
  resolveDialogMessageMessages,
  resolveExtensionLocale,
  type DialogMessageApi,
  type DialogMessageOptions,
  type DialogMessageConfirmOptions,
  type DialogMessageDefaults,
  type DialogMessagePresetConfig,
  type DialogMessagePresetsDefaults,
  type DialogMessageFontDefaults,
  type DialogMessageI18nMessages,
  type PartialDialogMessageI18nMessages,
  type DialogMessageButtonStyleConfig,
  type DialogMessageButtonThemeStyle,
  type DialogMessageButtonVariant,
  type DialogMessageThemeColor,
  type DialogMessageThemeColorValue,
  type DialogMessageThemeMode,
  type DialogMessageVariant,
  type ExtensionLocale,
  type ResolvedDialogMessageDefaults,
  configureDialogMessageDefaults,
  BUILTIN_DIALOG_MESSAGE_DEFAULTS,
  DIALOG_MESSAGE_VARIANTS,
} from "@benjaminor-dev/quasar-app-extension-dialog-message";

También se exportan configureDialogMessage (alias), resolveDialogMessageMessages, resolveExtensionLocale, BUILTIN_DIALOG_MESSAGE_DEFAULTS y DIALOG_MESSAGE_API_KEY (clave provide del boot para integraciones avanzadas).

Entrypoints públicos

Lo que importas en tu código:

Boot (boot/dialog) y estilos (main.css) los registra la extensión en quasar.config al instalar — no hace falta importarlos a mano en una instalación normal.

Troubleshooting

Veo títulos o botones en inglés y quiero español (o portugués)

Sin configurar Quasar, los presets built-in están en inglés. Elige una opción:

// quasar.config.ts — recomendado
framework: {
  lang: "es",
},

// src/boot/bor/bor-dialog-message-defaults.ts — fijar solo el locale de Dialog Message
configureDialogMessageDefaults({ locale: "es" });

Boots o estilos no aparecen en quasar.config

En condiciones normales el install registra el defaults boot en boot: [] y el runner inyecta boot/dialog + CSS al compilar. Si falta el defaults boot:

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

Error: Pinia no inicializada

• Verifica un boot de Pinia en el host (app.use(pinia) o equivalente).
• En quasar.config, el boot de Pinia debe ir antes que el boot dialog de esta extensión.

useDialogMessage() fuera de setup

Llámalo dentro de setup, otro composable o <script setup>. El boot debe haberse ejecutado (app montada).

El diálogo no muestra título

• Revisa si pasaste title: "" (oculta el título a propósito).
• Si omites title, se usa presets.<variant>.title del boot.

confirm() siempre resuelve false

• Comprueba que no llamas hide() ni abres otro diálogo antes de pulsar un botón.
• Una segunda llamada mientras el primero está abierto cierra el anterior con false.

El diálogo queda detrás de otro overlay

Ajusta zIndex en boot (default 7000) según la jerarquía de capas de tu app.

Cambié presets en boot y no se refleja

Reinicia el dev server. Confirma que editas src/boot/bor/bor-dialog-message-defaults.ts del host, no solo la plantilla de la extensión.

MIT © Benjamín Olvera R.