@benjaminor-dev/quasar-app-extension-datatable

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

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

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.

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

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

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

Entrypoints públicos

Troubleshooting

MIT © Benjamín Olvera R.