Vue ImportExport

Cos'è @pzeta/vue-importexport

@pzeta/vue-importexport è la libreria Vue 3 per gestire importazioni ed esportazioni massive di dati con un workflow guidato. Fornisce:

• ImportWizard — dialog multi-step (upload → mapping → anteprima → esecuzione) con dry-run e polling per import asincroni
• ExportDialog — selezione campi, ordinamento, applicazione di template salvati, download del file generato
• Composables (useImport, useExport, useFieldMapping, useImportHistory, useImportStatus, useExportTemplates) per costruire UI custom
• Contratti client (IImportClient, IExportClient, ITemplateClient, ImportExportClient) per sostituire il backend senza ereditare dalla classe concreta

Backend di riferimento: i microservizi node-excel-import e node-excel-export tramite ImportExportApi. Sostituibile passando un'implementazione delle interfacce alle prop api di ImportWizard / ExportDialog.

Funzionalità principali

• Import multi-step: upload + mapping interattivo + dry-run (testImport) + esecuzione con ImportStatusTracker
• Auto-suggest mapping colonne sorgente → campi destinazione (algoritmo basato su nome, etichetta, alias)
• Polling per import asincroni (file > 500 righe per default) con cleanup automatico
• Export sincrono e asincrono: il server può rispondere con Blob immediato o 202 Accepted con exportId per polling
• Template export salvabili: TemplateManager per creare, applicare, condividere modelli persistenti
• Formati supportati: CSV (via papaparse), XLSX/XLS (via exceljs), JSON
• Errori categorizzati via ErrorBoundary interno + ErrorCode enum per logging strutturato
• Annullamento upload/export tramite AbortController integrato

Architettura

ImportWizard / ExportDialog                    ← Componenti smart (Dialog + Stepper)
        ↓
useImport / useExport                          ← Composable orchestratori
        ↓
useApi → IMPORT_EXPORT_API_KEY                 ← Provide/inject del client
        ↓
ImportExportClient (interfaccia)               ← Strategy: 3 contratti aggregati
        ↓
ImportExportApi (default)                      ← Implementazione fetch verso microservizi
        ↓
node-excel-import + node-excel-export          ← Backend Fastify

I 3 contratti aggregati nell'ImportExportClient:

type ImportExportClient = IImportClient & IExportClient & ITemplateClient

Vedi Client interfaces per le firme complete e gli esempi di implementazione custom.

Mappa componenti

Componenti smart (caso comune)

Componenti per UI custom

Sotto-pagine

Nessuna sotto-pagina disponibile.

Quick start

<script setup lang="ts">
import { ref } from 'vue'
import { ImportWizard, ExportDialog } from '@pzeta/vue-importexport'
import '@pzeta/vue-importexport/style.css'

const showImport = ref(false)
const showExport = ref(false)
const baseUrl = import.meta.env.VITE_IMPORTEXPORT_API_URL
</script>

<template>
  <button @click="showImport = true">Importa</button>
  <button @click="showExport = true">Esporta</button>

  <ImportWizard
    v-model:visible="showImport"
    :base-url="baseUrl"
    risorsa="anagrafica"
    @import-completed="(r) => console.log('Importate', r.righeImportate)"
  />

  <ExportDialog
    v-model:visible="showExport"
    :base-url="baseUrl"
    risorsa="anagrafica"
  />
</template>

ImportWizard istanzia internamente new ImportExportApi(baseUrl) e la fornisce ai sotto-componenti via provide(IMPORT_EXPORT_API_KEY). Per condividere la stessa istanza tra Wizard e Dialog (o passare un client custom), usa la prop api.

Quando usare cosa

Versione

npm install @pzeta/vue-importexport
# v0.2.0 — peer deps: vue@^3.5, @pzeta/vue-components@^1.4