API JavaScript per generare documenti Word dinamici
Libreria JavaScript open source per creare documenti Word dinamici con Node.js e applicazioni basate su browser.
Che cos'è Docx-templates?
Docx-Templates è una libreria JavaScript open-source che consente agli sviluppatori software di generare documenti Microsoft Word (.docx) dinamici utilizzando modelli predefiniti. Invece di costruire manualmente i documenti Word programmaticamente, gli sviluppatori possono progettare i modelli in Microsoft Word e inserire dati dinamici tramite comandi incorporati. Questa libreria funziona sia in ambienti Node.js che nei browser, rendendola altamente versatile per le moderne applicazioni web e lato server. Elabora i file DOCX analizzando la loro struttura XML interna e sostituendo i comandi del modello con i dati reali durante l'esecuzione.
La libreria Docx-Templates è uno strumento potente e open-source progettato sia per ambienti Node.js che per browser. Il principale vantaggio della libreria è la separazione tra design e logica. Gli utenti non tecnici possono progettare il layout e lo stile in Word, mentre gli sviluppatori si concentrano sull'inserimento dei dati. Supporta logiche complesse come cicli, formattazione condizionale e persino l'esecuzione di snippet JavaScript direttamente nel documento. Questo la rende una soluzione ideale per gli sviluppatori che devono produrre report ad alta fedeltà senza doversi confrontare con XML o strumenti di design proprietari.
Guida introduttiva a Docx-templates
Il modo consigliato per installare la libreria Docx-templates è tramite npm. Si prega di utilizzare il seguente comando per un'installazione senza problemi
Installa Docx-Templates via NPM
$ npm install docx-templates Installa Docx-Templates via Yarn
$ yarn add docx-templates Generazione di documenti basata su template tramite API JS
La libreria open source Docx-Templates consente agli sviluppatori software di progettare documenti in Word e di inserire dati in modo dinamico usando comandi semplici. Questo approccio separa la presentazione dalla logica, rendendo i modelli facili da gestire e aggiornare senza modificare il codice. È possibile accedere direttamente alle proprietà del proprio oggetto dati o anche eseguire semplici espressioni. Ad esempio, per inserire un nome completo, il modello dovrebbe apparire così: {firstName} {surname}. La libreria valuta il codice e lo sostituisce senza problemi.
Come creare dinamicamente documenti Word all'interno delle app JavaScript?
import createReport from 'docx-templates';
import fs from 'fs';
const template = fs.readFileSync('template.docx');
const report = await createReport({
template,
data: { name: 'John', surname: 'Doe' },
});
fs.writeFileSync('output.docx', report);
Iniezione dinamica di immagini tramite JavaScript
Oltre al testo, la libreria open source Docx-Templates può inserire immagini al volo. Questo include file locali, immagini da un URL o anche codici QR generati programmaticamente. È possibile controllare le dimensioni dell'immagine e il suo posizionamento. Questa funzionalità è rivoluzionaria per creare badge di identificazione, cataloghi di prodotti o report che richiedono grafici dinamici e prove visive. Ecco un semplice esempio che dimostra come inserire un'immagine in un documento Word tramite l'API JavaScript.
Come inserire un'immagine al volo nei documenti Word tramite API JavaScript?
const buffer = await createReport({
template,
data: {
userAvatar: async () => {
const resp = await fetch('https://example.com/photo.png');
return { width: 3, height: 3, data: await resp.arrayBuffer(), extension: '.png' };
}
},
});
// In Word: {IMAGE userAvatar()}
Loop potenti (FOR/END-FOR)
La gestione delle liste di dati è fluida con il comando FOR. Questa funzionalità consente di iterare sugli array per generare righe di tabelle, elenchi o persino intere sezioni di un documento. La libreria Docx-Templates ha incluso il supporto per i cicli annidati, permettendo di rappresentare strutture dati gerarchiche complesse, come un elenco di dipartimenti con i rispettivi dipendenti, mantenendo al contempo lo stile originale di Word. Il seguente esempio di codice mostra come ottenere questo risultato.
Come applicare un ciclo avanzato nelle app JavaScript?
const buffer = await createReport({
template,
data: {
projects: [
{ name: 'SEO Optimization', status: 'Completed' },
{ name: 'API Integration', status: 'In Progress' }
]
},
});
/* In Word:
{FOR project IN projects}
Project: {project.name} - Status: {project.status}
{END-FOR}
*/
Contesto JavaScript personalizzato (EXEC)
Una delle funzionalità più avanzate della libreria Docx-Templates è la capacità di eseguire frammenti JavaScript arbitrari usando il comando EXEC (o !). Fornendo un additionalJsContext, è possibile esporre funzioni di supporto personalizzate al modello. Questo consente al modello di eseguire calcoli, formattare date o manipolare stringhe internamente senza dover pre-elaborare ogni singolo dato nella logica principale dell'applicazione.
