DataTable para Quasar

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

Extensão Quasar com DataTable homologado: shell sobre QTable, paginação client/server unificada e cards em viewports < sm.

Índice

• Em 30 segundos
• O que é e o que inclui
• Requisitos e compatibilidade
• Instalação em app Quasar
• O que a extensão adiciona ao host
• Defaults globais (boot)
• Uso rápido
• Idioma (i18n)
• TypeScript no seu IDE
• API do componente DataTable
• Paginação client-side
• Paginação server-side
• Layout móvel (grid / cards)
• Referência compacta
• Entrypoints públicos
• Troubleshooting

Em 30 segundos

1. Instale a extensão: quasar ext add @benjaminor-dev/datatable.
2. Importe DataTable no seu componente Vue.
3. Passe rows, columns, row-key e v-model:pagination.
4. Adicione client-pagination para paginação integrada no cliente (ou server-pagination + emits se você controla o backend).

A extensão registra CSS e um boot de defaults no host automaticamente.

O que é e o que inclui

DataTable é uma camada de apresentação sobre Quasar QTable: shell com borda opcional, barra de paginação (TablePaginationBar) e layout em cards no mobile.

• Paginação client (client-pagination) ou server (server-pagination + emits).
• Posição da barra: auto | top | bottom | both (em auto, barra superior só se a página atual mostrar ≥ 15 linhas).
• Escala builtin de linhas por página (5…300) e «Todas» quando aplicável.
• Breakpoint móvel compartilhado (useDataTableGridLayout) — cards em < 600px.
• Slot #item para cards customizados; card padrão incluído.
• Helpers exportáveis para orquestrar paginação em camadas superiores da app.
• i18n integrado en, es, pt — a barra de paginação segue $q.lang; overrides opcionais no boot (locale, messages).

Requisitos e compatibilidade

| Item | Valor | | --- | --- | | Node | >= 20.0.0 | | Quasar | ^2.6.0 | | Vue | ^3.4.18 | | Formato do pacote | ES modules | | CLI recomendado | @quasar/app-vite ^2.x ou ^3.x |

Instalação em app Quasar

quasar ext add @benjaminor-dev/datatable

Após quasar ext add, a extensão registra CSS e o boot de defaults automaticamente. Nada extra numa instalação npm normal.

Remover:

quasar ext remove @benjaminor-dev/datatable

Remove o boot de defaults gerado e a entrada em quasar.config. A injeção de estilos pode permanecer se outro pacote instalado registar o mesmo caminho CSS.

O que a extensão adiciona ao host

| Recurso | Caminho no host | | --- | --- | | Estilos | ~@benjaminor-dev/quasar-app-extension-datatable/main.css | | Boot defaults do host | src/boot/bor/bor-datatable-defaults.ts — criado na instalação; Skip/Overwrite se já existir |

Install (quasar ext add / invoke): cria src/boot/bor/bor-datatable-defaults.ts (ou .js) e registra em quasar.config → boot: [] automaticamente. Sem edição manual numa instalação normal. main.css é injetado em cada dev/build (não aparece como entrada curta em quasar.config).

Remove (quasar ext remove): remove o boot de defaults e a entrada em quasar.config quando a extensão o criou.

Ordem de boots (esta extensão):

1. bor/bor-datatable-defaults (host)
2. resto dos seus boots

Em quasar.config só verá bor/bor-datatable-defaults; main.css é injetado pela extensão ao compilar.

Defaults globais (boot)

Edite src/boot/bor/bor-datatable-defaults.ts após instalar para fixar locale ou override de textos de paginação:

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

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

configureDataTable é alias de configureDataTableDefaults. Prioridade: boot locale → $q.lang.isoName → en; boot messages faz merge sobre o 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: "Nome", field: "name", align: "left" as const },
  { name: "role", label: "Função", 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 e pt. Por padrão a barra de paginação segue o idioma do Quasar ($q.lang.isoName); se o Quasar não tiver idioma, o fallback é en.

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

| Opção | Quando usar | | --- | --- | | framework.lang em quasar.config.ts | Recomendado — alinha DataTable ao resto do Quasar | | locale: 'pt' em boot | Fixar idioma (en | es | pt); ignora mudanças de $q.lang | | messages: { allRows: '…' } em boot | Alterar um texto sem fixar locale |

Exemplo em quasar.config.ts (português para toda a app):

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

Chaves i18n: labels aria de navegação, linhas por página, indicador de página ({page}, {lastPage}), formato de intervalo ({start}, {end}, {total}) e allRows.

TypeScript no seu IDE

Não decore a API: deixe o autocompletar guiar você.

• Importe tipos de @benjaminor-dev/quasar-app-extension-datatable/types (ou o entry principal para componentes e helpers).
• No VS Code / Cursor: Ctrl+Space / Cmd+Space dentro de client-pagination ou server-pagination para ver props válidas (DataTableClientPaginationConfig, DataTableServerPaginationConfig).
• Passe o cursor sobre props de <DataTable>: o tooltip mostra JSDoc e tipos do Quasar QTable quando aplicável.
• v-model:pagination é tipado como ClientTablePaginationState — compatível com o modelo de paginação do QTable.
• useDataTableGridLayout() retorna Ref<boolean>; em templates com TS estrito, use computed(() => layoutRef.value) se :grid não desembrulhar o ref.

Se algo não aparecer no autocompletar, revise o import (/types vs entry principal) antes de buscar no 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 do componente DataTable

| Prop | Tipo | Default | Descrição | | --- | --- | --- | --- | | rows | readonly Record<string, unknown>[] | — | Linhas a exibir | | columns | QTableProps['columns'] | — | Colunas Quasar | | row-key | string \| fn | — | Chave da linha | | grid | boolean | auto | true = cards; false = tabela no mobile; omitido = cards em < sm | | bordered | boolean | true | Borda do shell | | flat | boolean | true | QTable flat | | dense | boolean | true | QTable dense | | client-pagination | DataTableClientPaginationConfig | — | Paginação client integrada | | server-pagination | DataTableServerPaginationConfig | — | Estado server + barra | | pagination-placement | DataTablePaginationPlacement | 'auto' | Posição da barra | | selection | 'single' \| 'multiple' | — | Seleção de linhas | | loading | boolean | false | Estado de carregamento | | hide-pagination | boolean | true | Oculta paginação nativa do QTable |

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

Slots: item (card em grid), top, bottom, slots de coluna padrão do QTable.

Paginação 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],
  }"
/>

• A barra fica oculta se totalRows não superar o primeiro degrau da escala.
• Escala builtin: «Todas» quando 5 ≤ total ≤ 100.
• pageSizeLadder custom: sem opção «Todas».

Paginação server-side

O pai controla pagination e escuta emits. Passe estado derivado em 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,
}));

Os mesmos helpers (buildDynamicRowsPerPageOptions, resolveDataTablePaginationPlacement, …) são exportáveis deste pacote.

Layout móvel (grid / cards)

Por padrão, viewports ≤ 599px usam 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 customizado:

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

Referência compacta

| Símbolo | Entry | Nota | | --- | --- | --- | | DataTable | . | Componente principal (default export) | | TablePaginationBar | . | Barra standalone | | useClientTablePagination | . | Lógica client + handlers | | useDataTableGridLayout | . | Breakpoint móvel (singleton) | | buildDynamicRowsPerPageOptions | . / /types | Opções do seletor de tamanho | | resolveDataTablePaginationPlacement | . / /types | top / bottom conforme placement | | shouldShowDataTablePaginationBar | . / /types | Mostrar barra? | | ClientTablePaginationState | /types | v-model:pagination | | DataTableClientPaginationConfig | /types | Prop client-pagination | | DataTableServerPaginationConfig | /types | Prop server-pagination | | DataTablePaginationPlacement | /types | 'auto' \| 'top' \| 'bottom' \| 'both' |

Lista completa de tipos e reexports: importe /types e use autocompletar do IDE.

Entrypoints públicos

| Entrypoint | Conteúdo | | --- | --- | | @benjaminor-dev/quasar-app-extension-datatable | DataTable, TablePaginationBar, composables, utils, i18n (configureDataTableDefaults, resolveDataTableMessages) | | @benjaminor-dev/quasar-app-extension-datatable/types | Tipos + reexports tipados de helpers | | @benjaminor-dev/quasar-app-extension-datatable/main.css | Estilos (registrado em quasar.config na instalação) |

Troubleshooting

| Sintoma | Causa provável | Fix | | --- | --- | --- | | Tabela sem estilos | Extensão não instalada ou CSS ausente | quasar ext add @benjaminor-dev/datatable; revisar quasar.config → css | | Barra de paginação não aparece | Poucas linhas vs primeiro degrau | Normal se totalRows ≤ minPageSizeStep | | Cards estreitas no mobile | Slot #item sem largura 100% | width: 100% na raiz do slot ou classes dt-data-table-grid-* | | Erro TS Ref<boolean> em :grid | Ref importado de pacote externo | computed(() => layoutRef.value) no consumidor | | Textos de paginação em inglês | Idioma do Quasar não configurado | framework.lang em quasar.config ou configureDataTableDefaults({ locale: 'pt' }) no boot | | Boot defaults ausente após remove | Desinstalação parcial ou delete manual | quasar ext add @benjaminor-dev/datatable novamente |

MIT © Benjamín Olvera R.