@pzeta/vue-components
Data

OrderList

Lista riordinabile con pulsanti freccia (su/giù/top/bottom), selezione multipla e, con `draggable`, trascinamento col puntatore o da tastiera; supporta slot personalizzati per item e header.

Import

import { OrderList } from '@pzeta/vue-components'

Esempio Base

Props

PropTipoDefaultDescrizione
modelValueOrderListItem[] | nullnullArray degli elementi della lista (v-model)
selectionOrderListItem[] | nullnullArray degli elementi selezionati (v-model:selection)
dataKeystring | nullnullProprietà usata come chiave univoca per gli elementi oggetto
scrollHeightstring'14rem'Altezza massima della lista con scroll
listStylestring | Record<string, string | number> | nullnullStile inline aggiuntivo per il contenitore lista
breakpointstring'960px'Larghezza viewport sotto la quale il layout diventa verticale
stripedbooleanfalseAlterna il colore di sfondo delle righe
metaKeySelectionbooleanfalseRichiede Ctrl/Meta per la selezione multipla; senza questa prop il click toglie/aggiunge alla selezione
autoOptionFocusbooleantrueMette il focus automaticamente sul primo elemento
focusOnHoverbooleantrueSposta il focus sull'elemento al passaggio del mouse
disabledbooleanfalseDisabilita il componente
draggablebooleanfalseRiordino col trascinamento, col puntatore o da tastiera (dalla 1.22.0). Spazio afferra invece di selezionare: la selezione resta su Invio e click
moveUpButtonPropsRecord<string, unknown> | nullnullAttributi aggiuntivi per il pulsante "sposta su"
moveTopButtonPropsRecord<string, unknown> | nullnullAttributi aggiuntivi per il pulsante "sposta in cima"
moveDownButtonPropsRecord<string, unknown> | nullnullAttributi aggiuntivi per il pulsante "sposta giù"
moveBottomButtonPropsRecord<string, unknown> | nullnullAttributi aggiuntivi per il pulsante "sposta in fondo"
ariaLabelstring | nullnullEtichetta accessibilità aria-label della lista
ariaLabelledbystring | nullnullID elemento che etichetta la lista

Emits

EventoPayloadDescrizione
update:modelValueOrderListItem[]Nuovo array dopo riordinamento (v-model)
update:selectionOrderListItem[]Aggiornamento della selezione corrente
reorderOrderListReorderEventEmesso dopo ogni operazione di riordinamento
selection-changeOrderListSelectionChangeEventEmesso quando cambia la selezione
focusFocusEventFocus sulla lista
blurFocusEventBlur dalla lista

Struttura eventi

interface OrderListReorderEvent {
  originalEvent: Event
  value: OrderListItem[]          // Nuovo array ordinato
  direction: 'up' | 'down' | 'top' | 'bottom' | 'drag'  // 'drag' dalla 1.22.0
  dragIndex?: number              // Con 'drag': indice di partenza
  dropIndex?: number              // Con 'drag': indice finale
}

interface OrderListSelectionChangeEvent {
  originalEvent: Event
  value: OrderListItem[]          // Elementi selezionati
}

Slot

SlotScopeDescrizione
option{ option: OrderListItem; index: number; selected: boolean }Template per ogni elemento della lista. Il contenuto è avvolto in .hs-orderlist-option-content; con draggable occupa il resto della riga accanto alla maniglia (dalla 1.24.0)
header{ value: OrderListItem[] }Intestazione sopra la lista
controlsstart—Contenuto inserito prima dei pulsanti di controllo
controlsend—Contenuto inserito dopo i pulsanti di controllo
moveupicon—Icona personalizzata per il pulsante "sposta su"
movetopicon—Icona personalizzata per il pulsante "sposta in cima"
movedownicon—Icona personalizzata per il pulsante "sposta giù"
movebottomicon—Icona personalizzata per il pulsante "sposta in fondo"

Esempi

Template personalizzato con prodotti

Ascolto evento reorder

Lista con righe alternate e disabled

Trascinamento

Con draggable (dalla 1.22.0) le voci mostrano una maniglia e si trascinano col puntatore; da tastiera, con il focus sulla lista: Spazio afferra la voce, frecce, Home e Fine scelgono la posizione, Spazio (o Invio) rilascia, Esc annulla. L'Escape che annulla non chiude un Dialog contenitore. Ogni passo è annunciato agli screen reader e le istruzioni sono collegate alla lista con aria-describedby. I pulsanti restano disponibili, anche come alternativa al trascinamento su touch.

Con draggable la voce è una riga flex: la maniglia resta a sinistra, centrata in verticale, e il contenuto dello slot option (avvolto in .hs-orderlist-option-content) occupa il resto della riga. Funziona anche con uno slot a blocco, per esempio un div con titolo, tag e pulsanti (dalla 1.24.0: prima la maniglia restava da sola su una riga e la voce raddoppiava l'altezza). Senza draggable la voce resta un blocco come prima.

La stessa logica è disponibile come composable: useDragReorder.

Accessibilità

  • La lista usa role="listbox" con aria-multiselectable="true".
  • I quattro pulsanti di riordino hanno un aria-label (i18n list.moveUp, list.moveTop, list.moveDown, list.moveBottom) e l'icona è aria-hidden (dalla 1.22.0; prima lo screen reader leggeva il glifo). Un aria-label passato con move*ButtonProps vince.
  • Ogni elemento ha role="option" e aria-selected.
  • Navigazione da tastiera: ArrowUp/ArrowDown per navigare, Ctrl+ArrowUp/Ctrl+ArrowDown per spostare gli elementi, Ctrl+Home/Ctrl+End per spostare in cima/fondo, Ctrl+A per selezionare tutto, Space/Enter per selezionare/deselezionare l'elemento con focus. Con draggable, Space afferra la voce e la selezione resta su Enter.

TypeScript

import type { OrderListProps, OrderListItem, OrderListReorderEvent } from '@pzeta/vue-components'

// Tipo per gli elementi della lista
type OrderListItem = Record<string, unknown> | string | number | boolean | null

Knob

Controllo rotante (dial) per la selezione di valori numerici tramite drag del mouse, touch o tastiera, con arco SVG personalizzabile per colori e spessore.

Paginator

Controllo di paginazione standalone con navigazione configurabile, dropdown righe per pagina, report pagina corrente e slot personalizzabili.