Getting Started

Installazione

Installazione, peer dependencies e setup base di @pzeta/vue-importexport.

Installazione

npm install @pzeta/vue-importexport

Peer dependencies

La libreria richiede Vue 3.5+ e @pzeta/vue-components come peer dependencies — devono essere già presenti nel progetto:

npm install vue @pzeta/vue-components

Pacchetto	Versione richiesta	Note
`vue`	`^3.5.0`	Composition API + `<script setup>`
`@pzeta/vue-components`	`^1.4.0`	Dialog, Stepper, DataTable, PickList, Select, Button, ecc.

Dipendenze runtime

Le seguenti dipendenze vengono installate automaticamente:

Pacchetto	Versione	Uso
`papaparse`	`^5.5.3`	Parsing CSV (lettura headers e anteprima)
`exceljs`	`^4.4.0`	Lettura/scrittura XLSX/XLS

Import CSS

Importa il CSS della libreria una volta sola, all'avvio dell'app:

import '@pzeta/vue-importexport/style.css'

Il file viene esportato anche automaticamente da index.ts della libreria, quindi è già incluso quando importi un componente. È comunque buona pratica importarlo esplicitamente per avere lo stile garantito anche con tree-shaking aggressivo.

Setup base

A differenza di altre librerie PZeta, @pzeta/vue-importexport non fornisce un plugin globale: i componenti ImportWizard e ExportDialog ricevono il baseUrl direttamente come prop e creano internamente l'istanza di ImportExportApi (provided via IMPORT_EXPORT_API_KEY ai loro figli).

<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>

Uso con istanza API condivisa

Per condividere la stessa istanza API tra più componenti (utile in test o con interceptor custom), passa la prop api:

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

const api = new ImportExportApi(baseUrl)

<ImportWizard :api="api" :base-url="baseUrl" risorsa="anagrafica" />
<ExportDialog :api="api" :base-url="baseUrl" risorsa="anagrafica" />

La prop api accetta il tipo interfacciaImportExportClient, non solo la classe ImportExportApi. Puoi quindi passare qualsiasi oggetto che implementi i contratti IImportClient & IExportClient & ITemplateClient. Vedi Client interfaces.

Path endpoint custom

Se i microservizi sono esposti sotto path diversi dai default /api/import / /api/export, configura ImportExportApi con ImportExportApiOptions:

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

const api = new ImportExportApi(baseUrl, {
  importPath: '/v2/import',   // default '/api/import'
  exportPath: '/v2/export',   // default '/api/export'
})

<ImportWizard :api="api" :base-url="baseUrl" risorsa="anagrafica" />

Backend custom (non `node-excel-*`)

Per backend completamente diversi (SDK custom, GraphQL, mock di test), implementa l'interfaccia ImportExportClient:

import { ImportWizard } from '@pzeta/vue-importexport'
import type { ImportExportClient } from '@pzeta/vue-importexport'

const myClient: ImportExportClient = {
  async uploadFile(file, risorsa, opzioni) { /* ... */ },
  async getImportFieldMetadata(risorsa) { /* ... */ },
  async testImport(sessionId, mappings) { /* ... */ },
  async executeImport(sessionId, mappings) { /* ... */ },
  // ...altri metodi delle 3 interfacce
}

<ImportWizard :api="myClient" base-url="https://my-backend" risorsa="anagrafica" />

Vedi Client interfaces per le firme complete dei 3 contratti.

Endpoint backend

Il client ImportExportApi si aspetta i seguenti pattern:

Endpoint	Metodo	Microservizio
`{baseUrl}/api/import/upload`	POST	`node-excel-import`
`{baseUrl}/api/import/test`	POST	`node-excel-import`
`{baseUrl}/api/import/execute`	POST	`node-excel-import`
`{baseUrl}/api/import/status/:id`	GET	`node-excel-import`
`{baseUrl}/api/import/metadata/:risorsa/fields`	GET	`node-excel-import`
`{baseUrl}/api/import/template/:risorsa`	GET	`node-excel-import`
`{baseUrl}/api/import/history`	GET	`node-excel-import`
`{baseUrl}/api/export/execute`	POST	`node-excel-export`
`{baseUrl}/api/export/status/:id`	GET	`node-excel-export`
`{baseUrl}/api/export/metadata/:risorsa/fields`	GET	`node-excel-export`
`{baseUrl}/api/export/templates`	GET/POST/PUT/DELETE	`node-excel-export`

Import individuali

import {
  // Componenti principali
  ImportWizard,
  ExportDialog,
  // Step wizard
  ImportStepUpload,
  ImportStepMapping,
  ImportStepPreview,
  ImportStepExecute,
  // Mapping
  FieldMapper,
  FieldMapperRow,
  // Anteprima e storico
  ImportPreview,
  ImportStatusTracker,
  ImportHistory,
  // Export
  ExportFieldSelector,
  FormatOptions,
  // Template
  TemplateManager,
  TemplateSaveDialog,
  // Composables
  useImport,
  useExport,
  useFieldMapping,
  useImportHistory,
  useImportStatus,
  useExportTemplates,
  // Service
  ImportExportApi,
  // Utility
  parseCSV,
} from '@pzeta/vue-importexport'

// Tipi (interfacce client + opzioni + DTO)
import type {
  ImportExportApiOptions,
  ImportExportClient,
  IImportClient,
  IExportClient,
  ITemplateClient,
  CampoMetadato,
  CsvOpzioni,
  UploadResult,
  TestImportResult,
  ImportResult,
  ImportProgresso,
  ImportHistoryItem,
  MappingColonna,
  ExportRequest,
  ExportProgresso,
  ExportResult,
  ModelloExport,
  FileFormato,
  ImportStato,
} from '@pzeta/vue-importexport'

// Iniezione manuale del client
import { IMPORT_EXPORT_API_KEY } from '@pzeta/vue-importexport'

Formati CSV ed Excel

Formati supportati, parsing CSV con papaparse e lettura XLSX con exceljs.

Mapping campi

Modello di mapping sorgente → destinazione, auto-suggest, validazione e trasformazioni.