Come creare una stampa unione automatica con immagini in LibreOffice Writer

È possibile creare una stampa unione perfettamente funzionante con LibreOffice Writer per nomi, indirizzi, date e altri campi di testo, per poi scoprire che nel momento in cui ogni destinatario necessita di una foto, una firma, un'immagine del prodotto, un codice QR o un badge diverso, il flusso di lavoro, prima semplice, smette di essere semplice. Il motivo è importante: i campi di stampa unione documentati in Writer sono campi di database utilizzati come segnaposto di testo. Anche LibreOffice supporta immagini incorporate e collegate, ma la sua guida attuale non documenta un "campo immagine di stampa unione" nativo che sostituisca automaticamente un'immagine da una colonna di percorso file per ogni record.

Rimangono quindi due opzioni pratiche. Se ogni documento unito utilizza lo stesso logo o la stessa immagine di sfondo, è possibile utilizzare la normale funzione di stampa unione di Writer e mantenere l'immagine fissa nel modello. Se invece l'immagine deve cambiare per ogni riga, l'approccio più gestibile consiste nel mantenere i dati di testo e immagine in Calc, riservare un oggetto grafico denominato nel modello di Writer e automatizzare la stampa unione con una macro di LibreOffice Basic. Questa guida utilizza il secondo approccio.

Le istruzioni sono allineate alla documentazione di LibreOffice 26.2 disponibile nel 2026. I menu possono differire leggermente in altre versioni o su macOS. La guida attuale di LibreOffice Writer afferma che le immagini possono essere incorporate o collegate, mentre l'API UNO espone gli oggetti grafici di Writer XTextGraphicObjectsSuppliere consente l'automazione dell'impostazione di un'immagine da un URL esterno. Questi elementi rendono possibile un flusso di lavoro per le immagini per ogni record, anche se la procedura guidata di stampa unione standard non lo espone come campo immagine dedicato.

Scegli il flusso di lavoro giusto prima di iniziare

Se il tuo caso d'uso prevede solo un logo aziendale fisso, fermati qui e usa il normale flusso di lavoro di LibreOffice per le lettere precompilate . Il resto di questo articolo è dedicato alle immagini variabili.

Passaggio 1: Preparare un'origine dati Calc pulita

Crea un foglio Calc con una riga di intestazione e un record per riga. Mantieni i riferimenti alle immagini in una colonna separata. Un layout pratico è CustomerID, FirstName, LastName, Email, ImagePath, e OutputName.

Utilizza percorsi assoluti durante la fase di compilazione e test dell'unione. Sono meno portabili, ma eliminano le ambiguità. Ad esempio, C:\MailMerge\Imageslice.jpgsu Windows o /home/user/mailmerge/images/alice.jpgLinux è più facile diagnosticare un problema rispetto a un percorso relativo, la cui directory di base cambia a seconda di come è stato aperto il documento.

Non mescolare formati di percorso Windows e Linux nello stesso file di produzione. Gli esempi misti nell'illustrazione mostrano semplicemente il tipo di valore contenuto nella colonna. La tua origine dati reale dovrebbe utilizzare percorsi validi sulla macchina che esegue l'unione.

Una buona OutputNamecolonna previene anche le collisioni di nomi di file. È preferibile utilizzare un ID stabile o un nome formattato piuttosto che un indirizzo email o un testo libero arbitrario. Se lo stesso valore compare due volte, è necessario decidere in anticipo se la macro debba sovrascrivere, aggiungere un suffisso o fallire.

Passaggio 2: Verificare che Writer possa leggere i record

La funzione di stampa unione standard di Writer utilizza un'origine dati registrata. È possibile utilizzare la Creazione guidata stampa unione, un'origine dati indirizzi o il browser delle origini dati. La guida di LibreOffice aggiornata descrive la procedura guidata stampa unione (Strumenti > Creazione guidata stampa unione) e consente anche l'inserimento di campi di database tramite Inserisci > Campo > Altri campi > ​​Database . Consultare la documentazione ufficiale sui campi di database .

Questo controllo è utile anche se la macro finale legge direttamente il foglio di calcolo. Permette di individuare tempestivamente i problemi più comuni: il foglio sbagliato, nomi di intestazione inattesi, record vuoti o un foglio di calcolo spostato dopo la registrazione.

Per la stampa unione standard di solo testo, è possibile trascinare un'intestazione di colonna nel documento o inserire un campo di stampa unione dalla scheda Database. La guida ufficiale di Writer conferma che questi campi vengono sostituiti con il contenuto del database durante l'esecuzione della stampa unione. Per quanto riguarda l'immagine variabile, tuttavia, non bisogna dare per scontato che trascinandola ImagePathnella pagina il percorso venga trasformato in un'immagine. Rimarrà un dato a meno che il codice non lo interpreti e aggiorni un oggetto grafico.

Passaggio 3: crea il modello Writer e assegna un nome al segnaposto dell'immagine

Crea il layout per la lettera, il certificato, il badge o il report in Writer. Per i valori di testo, utilizza i normali campi di stampa unione oppure utilizza token inconfondibili come {FirstName}, {LastName}, e {CustomerID}se la tua macro li sostituirà automaticamente.

Successivamente, inserisci un'immagine di esempio nel punto in cui dovrebbe apparire l'immagine variabile. Imposta le dimensioni, l'allineamento e l'ancoraggio desiderati prima di automatizzare il processo. LibreOffice documenta le dimensioni, il posizionamento, l'ancoraggio, l'allineamento e il comportamento delle immagini collegate nel capitolo "Immagini e grafica" della versione corrente di Writer 26.2 .

Assegna all'oggetto grafico un nome stabile, ad esempio MergeImage. La finestra di dialogo delle proprietà esatta può variare a seconda della versione, quindi se non sei sicuro di quale oggetto Writer esponga, usa Strumenti > Strumenti di sviluppo . Gli Strumenti di sviluppo di LibreOffice possono esaminare oggetti grafici, proprietà, metodi e interfacce nel documento corrente. Questo li rende uno strumento di diagnostica più sicuro rispetto a indovinare il nome di un oggetto interno.

Per un layout prevedibile, utilizza lo stesso rapporto d'aspetto per tutte le immagini sorgente oppure decidi come ritagliarle. Writer può ridimensionare un'immagine in base alle dimensioni del segnaposto, ma una foto verticale inserita in una cornice ampia a forma di banner apparirà comunque errata a meno che non si normalizzino prima i file.

Passaggio 4: Automatizzare l'esportazione di immagini e documenti variabili

L'operazione di automazione principale è semplice: aprire il modello, sostituire i segnaposto di testo, trovare l'oggetto grafico denominato, caricare il file immagine della riga in quell'oggetto e quindi esportare il risultato. La documentazione API UNO di LibreOffice getGraphicObjects()descrive come accedere alla grafica incorporata e collegata e il TextGraphicObjectservizio per le proprietà grafiche. La GraphicURLproprietà è deprecata per l'archiviazione di oggetti generici a favore di Graphic, ma l'API attuale indica esplicitamente che l'impostazione di un URL esterno carica l'immagine nell'oggetto grafico. Ciò rende comodo per una semplice macro Basic che utilizza percorsi di file locali.

L'esempio seguente è volutamente ridotto. Modifica i tre percorsi, il nome del foglio, gli indici di colonna e i nomi dei segnaposto in modo che corrispondano ai tuoi file. Esegui una prova su due record prima di eseguire un'elaborazione batch di grandi dimensioni.

Sub MailMergeWithImages()
    Dim calcDoc As Object, sheet As Object, doc As Object
    Dim graphics As Object, imageObj As Object
    Dim row As Long
    Dim firstName As String, lastName As String
    Dim imagePath As String, outputName As String
    Dim sourceURL As String, templateURL As String, outputDir As String

    sourceURL = ConvertToURL("C:\MailMerge\customers.ods")
    templateURL = ConvertToURL("C:\MailMerge\LetterTemplate.odt")
    outputDir = ConvertToURL("C:\MailMerge\Output")

    calcDoc = StarDesktop.loadComponentFromURL(sourceURL, "_blank", 0, Array())
    sheet = calcDoc.Sheets.getByName("Sheet1")

    row = 1  ' row 0 contains headers
    Do While sheet.getCellByPosition(0, row).String <> ""
        firstName = sheet.getCellByPosition(1, row).String
        lastName = sheet.getCellByPosition(2, row).String
        imagePath = sheet.getCellByPosition(4, row).String
        outputName = sheet.getCellByPosition(5, row).String

        doc = StarDesktop.loadComponentFromURL(templateURL, "_blank", 0, Array())

        ReplaceAll doc, "{FirstName}", firstName
        ReplaceAll doc, "{LastName}", lastName

        graphics = doc.getGraphicObjects()
        If graphics.hasByName("MergeImage") Then
            imageObj = graphics.getByName("MergeImage")
            imageObj.GraphicURL = ConvertToURL(imagePath)
        Else
            MsgBox "Graphic object MergeImage was not found."
            doc.close(True)
            Exit Sub
        End If

        Dim args(1) As New com.sun.star.beans.PropertyValue
        args(0).Name = "FilterName"
        args(0).Value = "writer_pdf_Export"
        args(1).Name = "Overwrite"
        args(1).Value = True

        doc.storeToURL(outputDir & outputName & ".pdf", args())
        doc.close(True)
        row = row + 1
    Loop

    calcDoc.close(True)
End Sub

Sub ReplaceAll(doc As Object, findText As String, replacement As String)
    Dim d As Object
    d = doc.createReplaceDescriptor()
    d.SearchString = findText
    d.ReplaceString = replacement
    doc.replaceAll(d)
End Sub

Questa macro è un modello, non un programma universale pronto all'uso. Le installazioni di LibreOffice possono avere diverse politiche di sicurezza delle macro, regole di percorso del sistema operativo e layout dei modelli. I concetti API importanti e verificati sono che Writer espone la sua raccolta di oggetti grafici e LibreOffice può impostare un elemento grafico da un URL esterno. Per implementazioni più ampie, si consiglia di caricare l'elemento grafico tramite l' GraphicAPI moderna piuttosto che affidarsi al comportamento di compatibilità di GraphicURL. I riferimenti ufficiali sono XTextGraphicObjectsSupplier e TextGraphicObject .

Passaggio 5: Eseguire un piccolo batch e verificare il risultato

Prima di elaborare l'intera fonte di dati, esegui due o tre elaborazioni con righe volutamente diverse: una in formato JPG, una in formato PNG e, idealmente, un'immagine con proporzioni diverse. Verifica tutti i seguenti aspetti prima di ingrandire l'immagine:

• Il nome del destinatario nel documento corrisponde all'immagine presente nella stessa riga del foglio di calcolo.
• Nel documento finale, il percorso dell'immagine non viene visualizzato come testo letterale.
• Il nome del file di output corrisponde al record previsto e non sovrascrive quello di un altro destinatario.
• L'immagine si adatta all'area riservata senza spostare il testo su una nuova pagina o coprire altri oggetti.
• Il file PDF o ODT generato si apre autonomamente dopo la chiusura di LibreOffice e Calc.

Quest'ultimo controllo è importante perché le immagini collegate e quelle incorporate si comportano in modo diverso. La guida di Writer attualmente disponibile spiega che un'immagine collegata rimane un riferimento di file separato, mentre un'immagine incorporata diventa parte integrante del documento. Se si inviano file ODT a un altro computer, è necessario verificare che il risultato non dipenda da un percorso locale presente solo sul computer che ha eseguito l'unione.

Guasti comuni e la soluzione più rapida

L'output mostra il percorso del file anziché l'immagine.

Hai inserito il campo ImagePathcome un normale campo di stampa unione. Ci si aspetta che produca del testo. Mantieni il percorso nell'origine dati, ma lascia che la macro lo carichi nell'oggetto grafico denominato.

Ogni record riceve la stessa immagine

L'immagine del modello non è mai stata modificata tra i record, oppure il ciclo sta leggendo una cella fissa. Registra il numero di riga ImagePathdurante un test con due record. Se il percorso cambia ma l'immagine no, controlla il nome dell'oggetto grafico con gli Strumenti di sviluppo.

La macro dice che MergeImage non esiste

L'immagine è stata rinominata, sostituita o non è visualizzata con il nome previsto. Seleziona l'immagine e ispezionala tramite Strumenti > Strumenti di sviluppo . L'API UNO espone gli oggetti grafici tramite nome, pertanto la macro e il modello devono corrispondere esattamente.

Le immagini scompaiono su un altro computer

Probabilmente hai salvato un documento che fa ancora riferimento a file esterni. Se la portabilità è importante, assicurati che il documento finale includa l'immagine oppure esportalo in PDF dopo aver caricato l'immagine. La guida alle immagini di LibreOffice spiega la differenza tra immagini collegate e immagini incorporate e come interrompere i collegamenti per incorporare i file.

La stampa unione HTML perde le immagini

Si tratta di una limitazione documentata che vale la pena verificare prima di scegliere l'invio tramite e-mail. La Guida di LibreOffice afferma che quando una lettera standard è in formato HTML, le immagini incorporate o collegate non vengono inviate con l'e-mail. Se l'immagine è essenziale, utilizzare un allegato PDF o testare un flusso di lavoro di invio diverso, anziché presumere che la stampa unione HTML la preservi. Vedere Creazione di una lettera standard .

Quando utilizzare invece il servizio MailMerge UNO di LibreOffice

Se i tuoi campi di testo utilizzano già la stampa unione nativa del database di Writer e hai bisogno di controllare programmaticamente l'output, LibreOffice espone anche un MailMergeservizio. Le sue proprietà documentate includono DataSourceName, Command, DocumentURL, OutputURL, FileNameFromColumn, e SaveAsSingleFile. Questa API è utile quando si desidera automatizzare la stampa unione standard tramite codice. Tuttavia, non documenta di per sé un campo per il percorso del file immagine per ogni record, quindi potrebbe essere necessario combinare l'esecuzione della stampa unione con la gestione degli oggetti grafici. Consulta la documentazione ufficiale del servizio MailMerge .

Lista di controllo finale

• Utilizzare la normale funzione di stampa unione di Writer quando l'immagine è fissa per ogni destinatario.
• Utilizzare una ImagePathcolonna vuota quando l'immagine varia da record a record.
• Assegna un nome al segnaposto grafico "Scrittore" e mantienine le dimensioni invariate.
• Gestisci il percorso dell'immagine in modo automatico; non aspettarti che un campo di unione testo si trasformi automaticamente in un'immagine.
• Prima di elaborare un batch completo, testa due o tre record.
• Aprire i file esportati dopo aver chiuso i documenti di origine per verificare che l'output sia autonomo.

Per la maggior parte dei lavori di piccole e medie dimensioni, un foglio di calcolo Calc, un modello di Writer e una breve macro di Basic offrono il miglior equilibrio tra trasparenza e controllo. Richiede una configurazione più complessa rispetto alla normale stampa unione di testo, ma permette di visualizzare esattamente quale riga contiene ciascuna immagine, scegliere il nome del file di output e convalidare il risultato prima di inviare centinaia di file personalizzati.