@pzeta/utils
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
PacchettoVersione richiestaNote
vue^3.5.0Composition API + <script setup>
@pzeta/vue-components^1.17.0Dialog, Stepper, DataTable, PickList, Select, Button, ConfirmDialog, ecc. ^1.17.0 dalla 0.5.0 (prima ^1.13.4): è la prima con entry require .cjs e tipi .d.cts

Dipendenze runtime

Le seguenti dipendenze vengono installate automaticamente:

PacchettoVersioneUso
papaparse^5.7.0Parsing CSV (lettura headers e anteprima)
exceljs^4.4.0Lettura/scrittura XLSX/XLS

Import CSS

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

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

L'import è necessario: il bundle JavaScript non carica il CSS da solo (Vite in library mode lo estrae in dist/style.css, esposto come @pzeta/vue-importexport/style.css).

Nei microfrontend del portale il CSS del modulo non arriva al browser: il loader della shell lo salta e le utility Tailwind le serve la shell stessa. Lì vale la safelist della shell, non questo import.

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 /import / /export, configura ImportExportApi con ImportExportApiOptions:

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

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

Fino alla 0.2.5 i default erano /api/import e /api/export: chi dipende ancora da quel prefisso lo passa qui.

<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, opzioniCsv, valoriFissi) { /* ... */ },
  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:

EndpointMetodoMicroservizio
{baseUrl}/import/uploadPOSTnode-excel-import
{baseUrl}/import/testPOSTnode-excel-import
{baseUrl}/import/executePOSTnode-excel-import
{baseUrl}/import/status/:idGETnode-excel-import
{baseUrl}/import/imagesPOSTnode-excel-import
{baseUrl}/import/metadata/:risorsa/fieldsGETnode-excel-import
{baseUrl}/import/template/:risorsaGETnode-excel-import
{baseUrl}/import/historyGETnode-excel-import
{baseUrl}/export/executePOSTnode-excel-export
{baseUrl}/export/status/:idGETnode-excel-export
{baseUrl}/export/metadata/:risorsa/fieldsGETnode-excel-export
{baseUrl}/export/templatesGET/POST/PUT/DELETEnode-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,
  ApiError,
  // 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,
  OrdinamentoExport,
  FileFormato,
  ImportStato,
} from '@pzeta/vue-importexport'

Sono esportati anche useApi, ApiError (dalla 0.8.0), detectFormulaInjection e detectFormulaInjectionWarnings. I tipi arrivano con export type *: le funzioni e gli enum definiti accanto ai tipi (isAsyncExportResult, ErrorCode) non sono disponibili a runtime, e non lo sono nemmeno IMPORT_EXPORT_API_KEY, usePolling, useCancelHandler, readFileHeaders e downloadBlob, che restano interni.

Formati del pacchetto

CondizioneFileUso
importdist/pzeta-vue-importexport.es.js + dist/index.d.tsBundler e Node in ESM
requiredist/pzeta-vue-importexport.cjs + dist/index.d.ctsConsumer CommonJS: SSR, Jest, script Node. Dalla 0.4.0
—dist/pzeta-vue-importexport.umd.jsSolo <script>: globale PzetaVueImportExport, richiede i globali Vue, PzetaVueComponents ed ExcelJS
./style.cssdist/style.cssCSS compilato della libreria

Fino alla 0.3.6 la condizione require puntava alla UMD e falliva con TypeError: Cannot read properties of undefined (reading 'defineComponent'). Il .cjs carica @pzeta/vue-components con require, per questo la peer è ^1.17.0.

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.