DataTable para Quasar

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

Extensión Quasar con DataTable homologado: shell sobre QTable, paginación client/server unificada y cards en viewports < sm.

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)
• Uso rápido
• Idioma (i18n)
• TypeScript en tu IDE
• API del componente DataTable
• Paginación client-side
• Paginación server-side
• Layout móvil (grid / cards)
• Referencia compacta
• Entrypoints públicos
• Troubleshooting

En 30 segundos

1. Instala la extensión: quasar ext add @benjaminor-dev/datatable.
2. Importa DataTable en tu componente Vue.
3. Pasa rows, columns, row-key y v-model:pagination.
4. Añade client-pagination para paginación integrada en el cliente (o server-pagination + emits si controlas el backend).

La extensión registra CSS y un boot de defaults en el host automáticamente.

Qué es y qué incluye

DataTable es una capa de presentación sobre Quasar QTable: shell con borde opcional, barra de paginación (TablePaginationBar) y layout en cards en móvil.

• Paginación client (client-pagination) o server (server-pagination + emits).
• Colocación de barra: auto | top | bottom | both (en auto, barra superior solo si la página actual muestra ≥ 15 filas).
• Escala builtin de filas por página (5…300) y «Todas» cuando aplica.
• Breakpoint móvil compartido (useDataTableGridLayout) — cards en < 600px.
• Slot #item para cards custom; tarjeta por defecto incluida.
• Helpers exportables para orquestar paginación en capas superiores de tu app.
• i18n integrado en, es, pt — la barra de paginación sigue $q.lang; overrides opcionales en boot (locale, messages).

Requisitos y compatibilidad

Instalación en app Quasar

quasar ext add @benjaminor-dev/datatable

Tras quasar ext add, la extensión registra CSS y el boot de defaults automáticamente. No hace falta nada extra en una instalación npm normal.

Remover:

quasar ext remove @benjaminor-dev/datatable

Elimina el boot de defaults generado y su entrada en quasar.config. La inyección de estilos puede permanecer si otro paquete instalado registra la misma ruta CSS.

Qué agrega la extensión al host

Install (quasar ext add / invoke): crea src/boot/bor/bor-datatable-defaults.ts (o .js) y lo registra en quasar.config → boot: [] automáticamente. No hace falta editarlo a mano en una instalación normal. main.css se inyecta en cada dev/build (no aparece como entrada corta en quasar.config).

Remove (quasar ext remove): elimina el boot de defaults y su entrada en quasar.config cuando la extensión lo creó.

Orden de boots (esta extensión):

1. bor/bor-datatable-defaults (host)
2. resto de tus boots

En quasar.config solo verás bor/bor-datatable-defaults; main.css lo inyecta la extensión al compilar.

Defaults globales (boot)

Edita src/boot/bor/bor-datatable-defaults.ts tras instalar para fijar locale u overridear textos de paginación:

import { configureDataTableDefaults } from "@benjaminor-dev/quasar-app-extension-datatable";

configureDataTableDefaults({
  // locale: "es", // fija en | es | pt; omitir = sigue $q.lang
  // messages: { allRows: "Ver todas" },
});

configureDataTable es alias de configureDataTableDefaults. Prioridad: boot locale → $q.lang.isoName → en; boot messages hace merge sobre el catálogo builtin.

Uso rápido

<script setup lang="ts">
import { ref } from "vue";
import DataTable from "@benjaminor-dev/quasar-app-extension-datatable";
import type { ClientTablePaginationState } from "@benjaminor-dev/quasar-app-extension-datatable/types";

const rows = [
  { id: 1, name: "Ana", role: "Admin" },
  { id: 2, name: "Luis", role: "Editor" },
];

const columns = [
  { name: "name", label: "Nombre", field: "name", align: "left" as const },
  { name: "role", label: "Rol", field: "role", align: "left" as const },
];

const pagination = ref<ClientTablePaginationState>({
  sortBy: "name",
  descending: false,
  page: 1,
  rowsPerPage: 10,
});
</script>

<template>
  <DataTable
    v-model:pagination="pagination"
    :rows="rows"
    :columns="columns"
    row-key="id"
    :client-pagination="{ defaultPageSize: 10 }"
  />
</template>

Idioma (i18n)

Integrado en, es y pt. Por defecto la barra de paginación sigue el idioma de Quasar ($q.lang.isoName); si Quasar no tiene idioma, el fallback es en.

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

Ejemplo en quasar.config.ts (español para toda la app):

framework: {
  lang: "es",
},

Claves i18n: etiquetas aria de navegación, filas por página, indicador de página ({page}, {lastPage}), formato de rango ({start}, {end}, {total}) y allRows.

TypeScript en tu IDE

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

• Importa tipos desde @benjaminor-dev/quasar-app-extension-datatable/types (o el entry principal para componentes y helpers).
• En VS Code / Cursor: Ctrl+Space / Cmd+Space dentro de client-pagination o server-pagination para ver props válidas (DataTableClientPaginationConfig, DataTableServerPaginationConfig).
• Pasa el cursor sobre props de <DataTable>: el tooltip muestra JSDoc y tipos de Quasar QTable donde aplica.
• v-model:pagination está tipado como ClientTablePaginationState — compatible con el modelo de paginación de QTable.
• useDataTableGridLayout() devuelve Ref<boolean>; en plantillas con TS estricto, usa computed(() => layoutRef.value) si :grid no desenvuelve el ref.

Si algo no aparece en autocompletado, revisa el import (/types vs entry principal) antes de buscar en el README.

import DataTable, {
  useDataTableGridLayout,
  buildDynamicRowsPerPageOptions,
} from "@benjaminor-dev/quasar-app-extension-datatable";

import type {
  ClientTablePaginationState,
  DataTableServerPaginationConfig,
  DataTablePaginationPlacement,
} from "@benjaminor-dev/quasar-app-extension-datatable/types";

API del componente DataTable

Emits (modo server): pageSizeChange, first, previous, next, last.

Slots: item (card en grid), top, bottom, slots de columna estándar de QTable.

Paginación client-side

<DataTable
  v-model:pagination="pagination"
  :rows="rows"
  :columns="columns"
  row-key="id"
  :client-pagination="{
    defaultPageSize: 10,
    placement: 'auto',
    pageSizeLadder: [5, 10, 25, 50],
  }"
/>

• La barra se oculta si totalRows no supera el primer escalón de la escala.
• Escala builtin: «Todas» cuando 5 ≤ total ≤ 100.
• pageSizeLadder custom: sin opción «Todas».

Paginación server-side

El padre controla pagination y escucha emits. Pasa estado derivado en server-pagination:

import type { DataTableServerPaginationConfig } from "@benjaminor-dev/quasar-app-extension-datatable/types";

const serverPagination = computed<DataTableServerPaginationConfig>(() => ({
  totalRows: store.total,
  pageSize: store.pageSize,
  lastPage: store.lastPage,
  pageSizeOptions: store.pageSizeOptions,
  rangeLabel: store.rangeLabel,
  enabled: store.hasSearched,
}));

Los mismos helpers (buildDynamicRowsPerPageOptions, resolveDataTablePaginationPlacement, …) son exportables desde este paquete.

Layout móvil (grid / cards)

Por defecto, viewports ≤ 599px usan layout grid (cards).

<script setup lang="ts">
import { computed } from "vue";
import { useDataTableGridLayout } from "@benjaminor-dev/quasar-app-extension-datatable";

const isMobileGridRef = useDataTableGridLayout();
const isMobileGrid = computed(() => isMobileGridRef.value);
</script>

<template>
  <DataTable :grid="isMobileGrid" ... />
</template>

Slot #item para card custom:

<template #item="props">
  <MyCard :row="props.row" :cols="props.cols" />
</template>

Referencia compacta

Lista completa de tipos y reexports: importa /types y usa autocompletado del IDE.

Entrypoints públicos

Troubleshooting

MIT © Benjamín Olvera R.