Table

useTableFilter

Composable interno per filtri per-colonna e filtro globale con multi-constraint e match mode configurabili.

Composable interno — utilizzato dal componente DataTable della libreria.

Firma TypeScript

export function useTableFilter(options?: UseTableFilterOptions): UseTableFilterResult

interface UseTableFilterOptions {
  initialFilters?: FilterMeta;
  globalFilterFields?: string[];
  filterMode?: 'lenient' | 'strict';   // default: 'lenient'
}

export interface UseTableFilterResult {
  currentFilters: Ref<FilterMeta>;
  globalFilter: Ref<string>;
  onFilter: (field: string, value: unknown, matchMode?: FilterMatchMode) => void;
  getFilterValue: (field: string) => unknown;
  hasActiveFilter: (field: string) => boolean;
  hasAnyActiveFilter: ComputedRef<boolean>;
  clearFilter: (field: string) => void;
  clearAllFilters: () => void;
  matchFilters: <T>(row: T, getValueFn: (item: T, field: string) => unknown) => boolean;
  matchGlobalFilter: <T>(row: T, getValueFn: (item: T, field: string) => unknown) => boolean;
}

export type FilterMeta = Record<string, FilterConstraint | FilterConstraint[]>

export interface FilterConstraint {
  value: unknown;
  matchMode: FilterMatchMode;
  operator?: 'and' | 'or';   // default: 'and'
}

export enum FilterMatchMode {
  STARTS_WITH = 'startsWith',
  CONTAINS = 'contains',
  NOT_CONTAINS = 'notContains',
  ENDS_WITH = 'endsWith',
  EQUALS = 'equals',
  NOT_EQUALS = 'notEquals',
  IN = 'in',
  LESS_THAN = 'lt',
  LESS_THAN_OR_EQUAL_TO = 'lte',
  GREATER_THAN = 'gt',
  GREATER_THAN_OR_EQUAL_TO = 'gte',
  BETWEEN = 'between',
  DATE_IS = 'dateIs',
  DATE_IS_NOT = 'dateIsNot',
  DATE_BEFORE = 'dateBefore',
  DATE_AFTER = 'dateAfter',
}

Parametri

Parametro	Tipo	Descrizione
`initialFilters`	`FilterMeta`	Filtri iniziali per campo
`globalFilterFields`	`string[]`	Campi inclusi nel filtro globale (testo libero)
`filterMode`	`'lenient' \| 'strict'`	`lenient`: riga passa se almeno un constraint e soddisfatto; `strict`: tutti i constraint attivi devono essere soddisfatti

Valore di Ritorno

Proprietà	Tipo	Descrizione
`currentFilters`	`Ref<FilterMeta>`	Stato corrente di tutti i filtri
`globalFilter`	`Ref<string>`	Testo del filtro globale
`onFilter`	`(field, value, matchMode?) => void`	Imposta/aggiorna il filtro per un campo
`getFilterValue`	`(field) => unknown`	Restituisce il valore corrente del filtro per un campo
`hasActiveFilter`	`(field) => boolean`	True se il campo ha un filtro attivo (valore non nullo/vuoto)
`hasAnyActiveFilter`	`ComputedRef<boolean>`	True se almeno un filtro e attivo
`clearFilter`	`(field) => void`	Rimuove il filtro per un campo specifico
`clearAllFilters`	`() => void`	Rimuove tutti i filtri e resetta il filtro globale
`matchFilters`	funzione	Testa una riga contro tutti i filtri attivi per colonna
`matchGlobalFilter`	funzione	Testa una riga contro il filtro globale nei campi specificati

Esempio

const {
  currentFilters,
  globalFilter,
  onFilter,
  hasAnyActiveFilter,
  matchFilters,
  matchGlobalFilter,
} = useTableFilter({
  globalFilterFields: ['name', 'email', 'role'],
})

// Dati filtrati lato client
const filteredRows = computed(() =>
  allRows.value.filter(row => {
    const passesColumn = matchFilters(row, (item, field) => item[field])
    const passesGlobal = matchGlobalFilter(row, (item, field) => item[field])
    return passesColumn && passesGlobal
  })
)

// Handler input filtro
const onColumnFilter = (field: string, value: string) => {
  onFilter(field, value, FilterMatchMode.CONTAINS)
}

Note

matchFilters supporta constraint multipli per campo (array di FilterConstraint): valutati in AND o OR in base a constraint.operator.
Filtri con value uguale a null, undefined o stringa vuota sono considerati inattivi e saltati.
matchGlobalFilter usa sempre contains case-insensitive su tutti i globalFilterFields.
I match mode numerici (lt, lte, gt, gte, between) convertono il valore della cella in numero prima del confronto.
I match mode data (dateIs, dateBefore, dateAfter, dateIsNot) accettano sia oggetti Date sia stringhe ISO parsabili.
FilterMatchMode.IN si aspetta che value sia un array; la riga passa se il valore del campo e contenuto nell'array.

useTableExpansion

Composable interno per l'espansione delle righe della tabella con slot di dettaglio e gestione eventi.

useTableGrouping

Composable interno per raggruppamento righe con subheader e rowspan, con espansione/collasso dei gruppi.