Ogni contratto, lettera ufficiale e materiale di brand porta con sé un'identità visiva implicita. Una semplice pagina bianca fa il suo lavoro, ma non dice nulla sull'organizzazione che vi sta dietro. Nel momento in cui aggiungi una tenue sfumatura, un sottile gradiente a due toni o un'immagine di sfondo ripetuta, l'intero documento passa da file generico ad artefatto brandizzato riconoscibile — e i lettori lo notano, anche se non sanno spiegare il perché.
Spire.Doc per JavaScript porta questo stile visivo direttamente nel browser tramite WebAssembly. Non ci sono round-trip verso il server, nessuna dipendenza da automazione Office e nessun requisito di installazione desktop. Carichi un file Word nel file system virtuale (VFS) WASM, scegli una delle tre modalità di sfondo ed esporti il documento formattato — il tutto lato client in un'applicazione React.
Questa guida illustra ciascuna delle tre opzioni di sfondo non come un catalogo di API, ma come un insieme di scelte di progettazione. Iniziamo con un rapido confronto per aiutarti ad abbinare la tecnica giusta al tuo caso d'uso, poi approfondiamo i dettagli di implementazione per ciascuna.
Tre approcci allo sfondo in sintesi
Prima di scrivere qualsiasi codice, è utile capire cosa offre ciascun tipo di sfondo da un punto di vista progettuale. La tabella seguente riassume il risultato visivo, la quantità di configurazione necessaria e gli scenari in cui ciascun approccio dà il meglio di sé.
| Approccio | Effetto visivo | Impegno di configurazione | Ideale per |
|---|---|---|---|
| Tinta unita | Un unico colore uniforme riempie ogni pagina | Basso — imposta BackgroundType.Color e assegna un colore |
Contratti, memo interni, lettere ufficiali che necessitano di una base pulita e professionale |
| Gradiente | Una miscela direzionale a due colori attraverso la pagina | Medio — definisci Color1, Color2, oltre a ShadingStyle e ShadingVariant
|
Copertine, certificati, modelli di marketing che traggono vantaggio da una profondità sottile |
| Immagine | Un'immagine di sfondo ripetuta su tutta la pagina | Medio — carica l'immagine nel VFS, quindi chiama SetPicture
|
Carta intestata brandizzata, carta intestata con elementi decorativi, modelli di documento a tema |
Tutti e tre condividono lo stesso flusso di lavoro generale: caricare il documento di origine nel VFS, configurare la proprietà Background su un'istanza di Document, salvare il risultato e avviare il download dal browser. Le differenze risiedono interamente nel modo in cui configuri quella proprietà Background — ed è qui che entrano in gioco le scelte di progettazione.
Per le istruzioni di configurazione e installazione del progetto, consulta Integrare Spire.Doc per JavaScript in un progetto React. Gli esempi di codice seguenti presuppongono che il modulo WASM sia già inizializzato e disponibile su window.wasmModule.
Sfondo a tinta unita
Un colore a tinta unita è la scelta di sfondo più sobria — e spesso la più efficace. Un caldo color crema o un grigio pallido dietro il testo nero riduce l'affaticamento degli occhi senza competere per l'attenzione. Per documenti formali come contratti e documenti di policy, una sfumatura discreta segnala "questo documento appartiene a un'organizzazione specifica" senza sconfinare nella decorazione.
L'implementazione segue tre semplici passaggi. Primo, usa FetchFileToVFS per caricare il file Word di destinazione (e i file dei font) nel file system virtuale WASM. Secondo, crea un Document, carica il file, imposta Background.Type su BackgroundType.Color e assegna un colore predefinito a Background.Color. Terzo, salva il documento di nuovo nel VFS con SaveToFile, leggi il file risultante come array di byte, avvolgilo in un Blob e avvia un download.
function App() {
const SetSolidColorBackground = async () => {
const docModule = window.wasmModule?.spiredoc;
if (!docModule) {
alert('Spire.Doc is not ready yet');
return;
}
// Load the sample file into the virtual file system (VFS)
let inputFileName = "ScienceTemplate.docx";
await window.spire.FetchFileToVFS(inputFileName, "", `${process.env.PUBLIC_URL}static/data/`);
// Create Word document
let doc = new docModule.Document();
// Load the file
doc.LoadFromFile(inputFileName);
// Set the background type as Color
doc.Background.Type = docModule.BackgroundType.Color;
// Set the background color
doc.Background.Color = docModule.Color.get_LightYellow();
// Define the output file name
const outputFileName = "SetSolidColorBackground_out.docx";
// Save the document to the specified path
doc.SaveToFile({ fileName: outputFileName, fileFormat: docModule.FileFormat.Docx2013 });
doc.Dispose();
const modifiedFileArray = window.dotnetRuntime.Module.FS.readFile(outputFileName);
const blob = new Blob([modifiedFileArray], { type: 'application/vnd.openxmlformats-officedocument.wordprocessingml.document' });
const url = URL.createObjectURL(blob);
const a = document.createElement('a');
a.href = url;
a.download = outputFileName;
a.click();
URL.revokeObjectURL(url);
};
return (
<div style={{ textAlign: 'center', height: '300px' }}>
<h1>Set a Solid Color Background for a Word Document</h1>
<button onClick={SetSolidColorBackground}>Generate</button>
</div>
);
}
export default App;
Una volta applicato Background.Color, ogni pagina del documento viene riempita con il colore predefinito scelto — in questo caso, LightYellow.
Sfondo con gradiente
I gradienti introducono un senso di dimensione che i colori piatti non possono offrire. Una transizione dall'alto verso il basso dal bianco all'azzurro pallido, per esempio, evoca cielo e apertura — utile per certificati, lettere di premiazione o qualsiasi documento in cui sia appropriato un tocco di cerimonia. La chiave è la sobrietà: scegli due colori strettamente correlati e lascia che il gradiente faccia il suo lavoro in modo discreto.
Il codice rispecchia il flusso di lavoro della tinta unita, ma il passaggio centrale si amplia. Dopo aver impostato Background.Type su BackgroundType.Gradient, recuperi l'oggetto gradiente tramite Background.Gradient e configuri quattro proprietà: Color1 (colore iniziale), Color2 (colore finale), ShadingVariant (direzione della transizione) e ShadingStyle (asse del gradiente).
function App() {
const SetGradientBackground = async () => {
const docModule = window.wasmModule?.spiredoc;
if (!docModule) {
alert('Spire.Doc is not ready yet');
return;
}
// Load the sample file into the virtual file system (VFS)
let inputFileName = "ScienceTemplate.docx";
await window.spire.FetchFileToVFS(inputFileName, "", `${process.env.PUBLIC_URL}static/data/`);
// Create Word document
let doc = new docModule.Document();
// Load the file
doc.LoadFromFile(inputFileName);
// Set the background type as Gradient
doc.Background.Type = docModule.BackgroundType.Gradient;
let gradient = doc.Background.Gradient;
// Set the start color and the end color of the gradient
gradient.Color1 = docModule.Color.get_White();
gradient.Color2 = docModule.Color.get_LightBlue();
// Set the shading style and variant of the gradient
gradient.ShadingVariant = docModule.GradientShadingVariant.ShadingDown;
gradient.ShadingStyle = docModule.GradientShadingStyle.Horizontal;
// Define the output file name
const outputFileName = "SetGradientBackground_out.docx";
// Save the document to the specified path
doc.SaveToFile({ fileName: outputFileName, fileFormat: docModule.FileFormat.Docx2013 });
doc.Dispose();
const modifiedFileArray = window.dotnetRuntime.Module.FS.readFile(outputFileName);
const blob = new Blob([modifiedFileArray], { type: 'application/vnd.openxmlformats-officedocument.wordprocessingml.document' });
const url = URL.createObjectURL(blob);
const a = document.createElement('a');
a.href = url;
a.download = outputFileName;
a.click();
URL.revokeObjectURL(url);
};
return (
<div style={{ textAlign: 'center', height: '300px' }}>
<h1>Set a Gradient Background for a Word Document</h1>
<button onClick={SetGradientBackground}>Generate</button>
</div>
);
}
export default App;
Dopo aver applicato Background.Gradient, la pagina viene riempita con una transizione orizzontale uniforme dal bianco all'azzurro chiaro, che scorre verso il basso.
Sfondo con immagine
Uno sfondo con immagine è l'opzione più espressiva. Che si tratti di un motivo filigranato discreto, di una texture aziendale o di un motivo decorativo per programmi di eventi, un'immagine ripetuta può veicolare elementi di branding che colore e gradiente semplicemente non possono trasmettere. Il compromesso è il peso del file — l'immagine deve essere caricata nel VFS insieme al documento — quindi riserva questo approccio ai modelli in cui il risultato visivo giustifica la risorsa aggiuntiva.
La configurazione differisce dai due metodi precedenti per un aspetto importante: anche l'immagine di sfondo deve essere caricata nel VFS usando FetchFileToVFS prima di poter essere referenziata. Una volta che sia il documento sia l'immagine sono nel VFS, imposta Background.Type su BackgroundType.Picture e chiama Background.SetPicture con il percorso VFS dell'immagine. L'immagine viene quindi ripetuta su ogni pagina come sfondo.
function App() {
const SetImageBackground = async () => {
const docModule = window.wasmModule?.spiredoc;
if (!docModule) {
alert('Spire.Doc is not ready yet');
return;
}
// Load the sample file into the virtual file system (VFS)
let inputFileName1 = "ScienceTemplate.docx";
await window.spire.FetchFileToVFS(inputFileName1, "", `${process.env.PUBLIC_URL}static/data/`);
// Load the background image into the virtual file system (VFS)
let inputFileName2 = "Background.png";
await window.spire.FetchFileToVFS(inputFileName2, "", `${process.env.PUBLIC_URL}static/data/`);
// Load a Word document
let doc = new docModule.Document();
doc.LoadFromFile(inputFileName1);
// Set the background type as Picture
doc.Background.Type = docModule.BackgroundType.Picture;
// Set the background picture
doc.Background.SetPicture(inputFileName2);
// Define the output file name
const outputFileName = "SetImageBackground_out.docx";
// Save the document to the specified path
doc.SaveToFile({ fileName: outputFileName, fileFormat: docModule.FileFormat.Docx2013 });
doc.Dispose();
const modifiedFileArray = window.dotnetRuntime.Module.FS.readFile(outputFileName);
const blob = new Blob([modifiedFileArray], { type: 'application/vnd.openxmlformats-officedocument.wordprocessingml.document' });
const url = URL.createObjectURL(blob);
const a = document.createElement('a');
a.href = url;
a.download = outputFileName;
a.click();
URL.revokeObjectURL(url);
};
return (
<div style={{ textAlign: 'center', height: '300px' }}>
<h1>Set a Picture Background in a Word Document</h1>
<button onClick={SetImageBackground}>Generate</button>
</div>
);
}
export default App;
Dopo aver chiamato Background.SetPicture, l'immagine specificata viene ripetuta sull'intera superficie della pagina come sfondo del documento.
Considerazioni sulla stampa
C'è un avvertimento pratico che coglie di sorpresa molti sviluppatori: Microsoft Word non stampa gli sfondi delle pagine per impostazione predefinita. Non è un bug nel tuo codice né un limite di Spire.Doc — lo sfondo viene memorizzato correttamente nel documento e visualizzato normalmente sullo schermo. Word semplicemente lo omette dall'output di stampa, a meno che tu non gli dica esplicitamente il contrario.
Per assicurarti che gli sfondi compaiano nelle copie stampate, l'utente finale deve abilitare un'impostazione specifica nel proprio client Word:
- Apri il documento in Microsoft Word.
- Vai su File > Opzioni > Visualizza.
- Seleziona Stampa colori e immagini di sfondo.
- Stampa come al solito.
Se hai bisogno che lo sfondo venga visualizzato in ogni ambiente di output indipendentemente dalle impostazioni di Word del lettore, considera un approccio alternativo: inserisci una forma a pagina intera nell'intestazione del documento oppure usa una filigrana per simulare l'effetto di sfondo. Queste tecniche sono trattate come contenuto anziché come formattazione di pagina, quindi vengono stampate in modo affidabile in tutte le configurazioni.
FAQ
Perché lo sfondo non compare quando stampo il documento?
Questo è il comportamento previsto. Word sopprime gli sfondi delle pagine nell'output di stampa per impostazione predefinita — l'impostazione è memorizzata correttamente e viene visualizzata sullo schermo, ma le opzioni di stampa del client Word la filtrano. Lo sfondo non è andato perso; semplicemente non è incluso nel flusso di stampa.
Per risolvere, abilita Stampa colori e immagini di sfondo in File > Opzioni > Visualizza in Word prima di stampare. Per gli ambienti in cui non puoi controllare le impostazioni di stampa del lettore, usa una forma a pagina intera nell'intestazione o una filigrana per replicare l'effetto visivo, poiché tali elementi sono trattati come contenuto stampabile.
Perché lo sfondo con immagine non ha effetto?
Questo di solito accade per uno di due motivi: o Background.Type non è stato impostato su BackgroundType.Picture prima di chiamare SetPicture, oppure il file immagine non è mai stato caricato nel VFS tramite FetchFileToVFS, quindi SetPicture non riesce a trovarlo.
Assicurati di impostare prima il tipo di sfondo e di passare il nome file esatto di un'immagine già caricata nel file system virtuale:
document.Background.Type = wasmModule.BackgroundType.Picture;
document.Background.SetPicture("Background.png");