Composables

useImport

Composable principale per orchestrare l'intero workflow di import.

Panoramica

useImport è il composable di alto livello che gestisce l'intero ciclo di vita dell'import: stato globale, upload, lettura headers client-side, mapping (delegato a useFieldMapping), test (dry-run), esecuzione e polling per import asincroni (delegato a useImportStatus). Include anche il download del template d'esempio e l'annullamento dell'upload tramite AbortController.

ImportWizard lo usa internamente — chiamarlo manualmente serve solo se vuoi comporre un wizard custom o invocare gli step da pagine separate.

Inizializzazione

import { useImport } from '@pzeta/vue-importexport'

const {
  stepCorrente, errore, loading,
  file, formato, risorsa, opzioniCsv,
  setFile, upload, cancelUpload,
  campiDestinazione, fieldMapping, anteprimaRigheFile,
  testResult, testImport,
  importResult, importStatus, isAsync, executeImport,
  canProceed, goToStep, reset, downloadTemplate,
} = useImport()

Parametri

Parametro	Tipo	Default	Descrizione
`apiOverride`	`ImportExportApi`	`useApi()`	Istanza API; se omesso viene iniettata via `inject(IMPORT_EXPORT_API_KEY)`
`options.asyncThreshold`	`number`	`500`	Soglia righe oltre cui l'esecuzione è considerata asincrona (parte il polling)

Stato reattivo

Proprietà	Tipo	Descrizione
`stato`	`Ref<ImportStato>`	Stato della macchina (`idle`, `uploading`, ...)
`stepCorrente`	`Ref<number>`	Indice step (0-3)
`errore`	`Ref<string \| null>`	Messaggio errore corrente
`loading`	`Ref<boolean>`	Operazione in corso
`file`	`Ref<File \| null>`	File selezionato
`formato`	`Ref<FileFormato>`	Derivato dall'estensione
`risorsa`	`Ref<string>`	Codice risorsa target
`opzioniCsv`	`Ref<CsvOpzioni>`	Opzioni di parsing CSV
`uploadResult`	`Ref<UploadResult \| null>`	Risposta upload (sessionId, righe, colonne)
`campiDestinazione`	`Ref<CampoMetadato[]>`	Campi target dalla risorsa
`fieldMapping`	oggetto	Restituito da `useFieldMapping`
`anteprimaRigheFile`	`Ref<Record<string, unknown>[]>`	Prime righe lette client-side
`testResult`	`Ref<TestImportResult \| null>`	Risultato dry-run
`importResult`	`Ref<ImportResult \| null>`	Risultato esecuzione
`importStatus`	oggetto	Restituito da `useImportStatus`
`isAsync`	`ComputedRef<boolean>`	`true` se `righe >= asyncThreshold`
`canProceed`	`ComputedRef<boolean>`	Validità dello step corrente

Tipo `ImportStato`

type ImportStato =
  | 'idle' | 'uploading' | 'uploaded'
  | 'testing' | 'tested'
  | 'importing' | 'completed' | 'error'

Metodi

`setFile(file)`

Imposta il file e deriva il formato dall'estensione.

setFile(fileFromInput)
// formato.value = 'csv' | 'xlsx' | 'xls' | 'json'

`upload()`

Esegue l'upload (POST /api/import/upload), legge headers client-side via readFileHeaders, carica i metadati campi (getImportFieldMetadata), inizializza il mapping (fieldMapping.initFromColumns) e avanza allo step 1.

Le colonne reali vengono lette dal file lato client; la risposta server è usata come fallback. Questo permette il mapping anche se il backend non restituisce le colonne.

await upload()
// stepCorrente.value = 1
// fieldMapping inizializzato con auto-suggest

`cancelUpload()`

Annulla l'upload in corso. Funziona solo durante loading: true (upload effettivamente attivo).

`testImport()`

Esegue il dry-run filtrando i mapping attivi. Aggiorna testResult e avanza allo step 2.

await testImport()
// testResult.value = { righeValide, righeErrore, ... }

`executeImport()`

Esegue l'import effettivo. Se isAsync.value === true e il server non risponde subito con completato, parte il polling tramite importStatus.startPolling(importId).

await executeImport()
// Sincrono: stato.value = 'completed'
// Async: importStatus.progresso si aggiorna nel tempo

await downloadTemplate('anagrafica', 'xlsx')
// browser scarica template_anagrafica.xlsx

Validazione step (`canProceed`)

Step	Condizione
0 (Upload)	`file !== null && risorsa !== ''`
1 (Mapping)	`fieldMapping.isValid.value === true`
2 (Preview)	`testResult !== null && testResult.righeErrore === 0`
3 (Execute)	sempre `false` (è lo step finale)

Esempio completo (wizard custom)

<script setup lang="ts">
import { useImport, useApi } from '@pzeta/vue-importexport'

const api = useApi()
const importer = useImport(api, { asyncThreshold: 1000 })

async function start(file: File) {
  importer.risorsa.value = 'contratto'
  importer.setFile(file)
  await importer.upload()      // step 1
  // L'utente fa il mapping...
  await importer.testImport()  // step 2
  // L'utente conferma...
  await importer.executeImport() // step 3
}
</script>

useFieldMapping

Stato del mapping colonne sorgente → campi destinazione con auto-suggest.

useApi, useCancelHandler, usePolling

Helper interni per injection API, gestione abort e polling generico.