DataTable

Import

import { DataTable, Column } from '@pzeta/vue-components'
import type {
  DataTableProps,
  DataTableEmits,
  DataTableFilterMeta,
  DataTableSortMeta,
  ColumnProps,
} from '@pzeta/vue-components'

Esempio Base

Props — DataTable

Props — Column

Le props booleane di Column si possono scrivere senza valore, come attributi HTML: <Column frozen truncate /> vale :frozen="true" :truncate="true" (dalla 1.24.0; prima solo sortable, hidden ed expander erano riconosciute così, e frozen senza valore non fissava la colonna). Un valore assente resta il default: exportable resta true.

Emits

Slot — DataTable

Slot — Column

Esempi

Ordinamento

Con sort-field la colonna ordina su un campo diverso da quello mostrato, anche annidato:

<Column field="cliente" sort-field="cliente.ragione" header="Cliente" sortable>
  <template #body="{ data }">{{ data.cliente.ragione }}</template>
</Column>

Filtri per riga

Selezione righe

selection-mode sulla tabella si può cambiare quando serve, per esempio per attivare la selezione solo in una modalità «modifica». In alternativa basta <Column selection-mode="multiple" /> senza selection-mode sulla tabella: la colonna diventa quella delle caselle (equivale a selection-mode="checkbox"). Con almeno una riga selezionata compare la barra con il conteggio, «Deseleziona tutto» e lo slot bulkactions per le azioni sulla selezione.

Nome contestuale della casella di selezione

Di default ogni casella si chiama "Seleziona riga N", che a uno screen reader non dice quale record si sta selezionando. selectionRowAriaLabel costruisce il nome dalla riga; in alternativa selectionRowAriaLabelKey indica il campo da interpolare nell'etichetta i18n table.selectRow.

<DataTable
  v-model:selection="selezionati"
  :value="lead"
  data-key="idlead"
  selection-mode="multiple"
  :selection-row-aria-label="(riga) => `Seleziona lead ${riga.cognome}`"
>
  <Column field="cognome" header="Cognome" />
</DataTable>
<!-- casella della prima riga: aria-label="Seleziona lead Rossi" -->

<!-- Oppure, con l'etichetta i18n standard: "Seleziona riga Rossi" -->
<DataTable :value="lead" selection-mode="multiple" selection-row-aria-label-key="cognome">
  …
</DataTable>

Espansione riga

La freccia di espansione la aggiunge lo slot #expansion: non serve una <Column expander />, che senza field né slot body non genera colonne (prima aggiungeva una colonna vuota).

Footer per-Column e aggregazioni built-in

Ogni Column può definire uno slot #footer per-colonna, una prop footer: string testuale, oppure una prop aggregate che produce un'aggregazione built-in (sum, count, avg, min, max) o una funzione custom (rows) => unknown. Le aggregazioni vengono calcolate sui dati della pagina corrente (paginatedData, già filtrati e paginati). Lo slot #footer ha priorità su aggregate, che a sua volta vince sulla prop footer. Se nessuna colonna definisce contenuto footer, il <tfoot> non viene renderizzato (backward-compatible).

Regole di priorità per la cella footer (alta → bassa):

1. Slot #footer="{ column, value }" definito sulla Column
2. Prop aggregate (con eventuale aggregateFormat)
3. Prop footer: string (testo statico)
4. Cella vuota

Funzioni di aggregazione built-in:

Lo slot footer del DataTable (riga full-width colspan) può coesistere con i footer per-Column: viene renderizzata come riga separata dopo quella per-colonna.

La cella footer eredita hideAt / responsivePriority della sua colonna: una riga "Totale" non resta visibile nelle colonne nascoste sotto il breakpoint, quindi non serve replicare le classi responsive in footerClass.

Colonne senza field

Una Column è riconosciuta anche senza field né header (tipicamente la colonna delle azioni) e ogni colonna ha una chiave univoca, calcolata così:

1. columnKey, se presente;
2. altrimenti field;
3. altrimenti la posizione della colonna.

Se due colonne hanno la stessa chiave, la seconda riceve un suffisso posizionale: allineamento, hideAt e stili restano sempre della colonna giusta. Per le colonne senza field è comunque raccomandato un columnKey esplicito, stabile anche se l'ordine delle colonne cambia.

<DataTable :value="lead" caption="Lead">
  <Column field="cognome" header="Cognome" />
  <Column field="valore" header="Valore" data-type="number" hide-at="md" />
  <Column column-key="azioni" align-body="right">
    <template #header><span class="sr-only">Azioni</span></template>
    <template #body="{ data }">
      <Button icon="pi pi-pencil" text aria-label="Modifica" @click="modifica(data)" />
    </template>
  </Column>
</DataTable>

Lo slot #header della Column sostituisce il testo dell'intestazione, anche nelle colonne ordinabili (resta dentro il pulsante di ordinamento).

Colonne fisse

frozen fissa la colonna a sinistra durante lo scorrimento orizzontale (scrollable), con align-frozen="right" a destra. La cella fissa ha sempre uno sfondo opaco, così le colonne che le scorrono sotto non traspaiono: in intestazione e piede quello del <thead>/<tfoot> (--color-surface-secondary), nel corpo quello della riga, anche selezionata o in hover (dalla 1.24.0). La riga selezionata usa i token opachi --color-surface-selected e --color-surface-selected-hover (vedi Proprietà CSS); con striped-rows l'hover si vede anche sulle righe pari.

Se un modulo forzava lo sfondo dell'intestazione fissa con header-style (il workaround delle versioni precedenti), va tolto: nel tema scuro la renderebbe più chiara del resto.

A capo. Le celle non vanno a capo, ma dalla 1.24.0 la regola sta in @layer components: una utility del chiamante la sostituisce, quindi body-class="whitespace-normal" (o header-class) manda a capo il testo. Prima la regola era fuori dai layer e vinceva sempre.

Righe trascinate su un albero

Con draggable-rows (dalla 1.24.0) le righe si trascinano su un nodo di una TreeTable o di un Tree con droppable, che emette nodeDrop con { node, data, originalEvent }: data sono le righe trascinate, e una riga che fa parte della selezione trascina tutta la selezione. È il gesto per spostare documenti in una cartella; il riordino nella stessa tabella resta la colonna rowReorder, la cui maniglia mantiene il proprio trascinamento.

<DataTable v-model:selection="scelti" :value="documenti" data-key="id" selection-mode="multiple" draggable-rows>
  <Column field="nome" header="Documento" />
</DataTable>

<TreeTable :value="cartelle" droppable caption="Cartelle" @node-drop="({ node, data }) => sposta(data, node.key)">
  <Column field="nome" header="Cartella" expander />
</TreeTable>

Il trascinamento richiede un puntatore: da tastiera serve un'alternativa equivalente, per esempio un'azione «Sposta in…» sulle righe selezionate.

Paginatore responsive

paginatorTemplate sceglie quali elementi del paginatore mostrare (vedi le chiavi in Paginator). Con un oggetto il template cambia con la larghezza del viewport: ogni chiave '<N>px' vale fino a quella larghezza (max-width), vince la più stretta che corrisponde, default si applica oltre. Esempio: a 390px il paginatore completo fa scorrere la pagina, quindi su schermi stretti restano solo le frecce e il report.

<script setup lang="ts">
import type { PaginatorTemplate } from '@pzeta/vue-components'

const template: PaginatorTemplate = {
  '640px': 'PrevPageLink CurrentPageReport NextPageLink',
  default: 'FirstPageLink PrevPageLink PageLinks NextPageLink LastPageLink RowsPerPageDropdown',
}
</script>

<template>
  <DataTable :value="lead" paginator :rows="10" :paginator-template="template">
    <Column field="cognome" header="Cognome" />
  </DataTable>
</template>

Lazy Loading (server-side)

<script setup lang="ts">
import { ref } from 'vue'
import type { DataTablePageEvent, DataTableSortEvent } from '@pzeta/vue-components'

const products = ref<Product[]>([])
const totalRecords = ref(0)
const loading = ref(false)

async function loadData(event: DataTablePageEvent) {
  loading.value = true
  const { data, total } = await fetchProducts({
    first: event.first,
    rows: event.rows,
  })
  products.value = data
  totalRecords.value = total
  loading.value = false
}
</script>

<template>
  <DataTable
    :value="products"
    :total-records="totalRecords"
    :loading="loading"
    :lazy="true"
    :paginator="true"
    :rows="10"
    @page="loadData"
    @sort="loadData"
  >
    <Column field="name" header="Nome" :sortable="true" />
    <Column field="price" header="Prezzo" :sortable="true" data-type="number" />
  </DataTable>
</template>

Editing inline (cell mode)

Riordino delle righe

Una <Column row-reorder /> rende in ogni riga una maniglia (dalla 1.22.0): si trascina sulla riga di arrivo, oppure col focus sulla maniglia Spazio/Invio afferra, frecce, Home e Fine scelgono la posizione, Spazio/Invio rilascia ed Esc annulla (senza chiudere un Dialog contenitore). Il DataTable non cambia value: emette rowReorder con dragIndex e dropIndex (indici di value) e value già riordinato. Dopo un rilascio da tastiera il focus resta sulla maniglia della riga spostata.

Con ordinamento o filtri attivi la riga si sposta al posto della riga di arrivo nell'ordine di value, ma la vista resta ordinata: il riordino ha senso senza ordinamento.

Esportazione CSV

exportCSV(options?) (dalla 1.22.0) scarica le colonne visibili con un field e senza :exportable="false", con le righe filtrate e ordinate di tutte le pagine; exportCSV({ selectionOnly: true }) esporta solo le selezionate. Esporta il valore del campo, non il testo formattato della cella, così il foglio di calcolo legge numeri e date come tali. export-header sostituisce l'intestazione, export-footer aggiunge una riga di piede. Il file usa le regole dell'utility exportCsv: separatore csvSeparator (default ;), virgola decimale, BOM UTF-8, quotatura RFC 4180, neutralizzazione delle formule.

Allineamento automatico per dataType

L'allineamento delle celle body viene determinato automaticamente dal dataType se alignBody non è specificato esplicitamente:

L'header è sempre allineato a sinistra per default. Usa alignHeader e alignBody per override esplicito.

Metodi esposti (defineExpose)

Accessibili via templateRef.value.* quando si ottiene un ref al DataTable.

Accessibilità

La tabella usa markup semantico <table>, <thead>, <th>, <td>. Le colonne ordinabili ricevono l'attributo aria-sort (solo quelle con un campo su cui ordinare). Gli attributi aria-* passati al DataTable (aria-label, aria-labelledby, aria-describedby…) finiscono sulla <table>, mentre classi, data-* e il resto restano sul contenitore (dalla 1.24.0; prima finivano tutti sul contenitore e non nominavano la tabella). Il paginatore interno usa <nav> con aria-label localizzato tramite il sistema i18n. Le caselle di selezione di riga prendono un nome contestuale con selectionRowAriaLabel / selectionRowAriaLabelKey (vedi Selezione righe).

TypeScript

import type {
  DataTableProps,
  DataTableEmits,
  DataTableFilterMeta,
  DataTableSortMeta,
  DataTablePageEvent,
  DataTableSortEvent,
  DataTableFilterEvent,
  DataTableRowClickEvent,
  DataTableRowSelectEvent,
  DataTableState,
  ColumnProps,
  ColumnSlots,
} from '@pzeta/vue-components'