Chaque contrat, lettre officielle et support de marque porte une identité visuelle implicite. Une page blanche ordinaire fait l'affaire, mais elle ne dit rien de l'organisation qui se trouve derrière. Dès que vous ajoutez une teinte douce, un subtil dégradé à deux tons ou une image d'arrière-plan répétée, l'ensemble du document passe d'un fichier générique à un artefact de marque reconnaissable — et vos lecteurs le remarquent, même s'ils ne savent pas l'exprimer.
Spire.Doc pour JavaScript apporte ce style visuel directement dans le navigateur via WebAssembly. Aucun aller-retour serveur, aucune dépendance à l'automatisation Office et aucune installation de bureau requise. Vous chargez un fichier Word dans le système de fichiers virtuel (VFS) WASM, choisissez l'un des trois modes d'arrière-plan et exportez le document stylisé — le tout côté client dans une application React.
Ce guide présente chacune des trois options d'arrière-plan non pas comme un catalogue d'API, mais comme un ensemble de décisions de conception. Nous commençons par une comparaison rapide afin que vous puissiez associer la bonne technique à votre cas d'usage, puis nous examinons en détail l'implémentation de chacune.
Trois approches d'arrière-plan en un coup d'œil
Avant d'écrire du code, il est utile de comprendre ce que chaque type d'arrière-plan apporte d'un point de vue de conception. Le tableau ci-dessous résume le résultat visuel, la quantité de configuration nécessaire et les scénarios dans lesquels chaque approche se distingue.
| Approche | Effet visuel | Effort de configuration | Idéal pour |
|---|---|---|---|
| Couleur unie | Une couleur unique et uniforme remplit chaque page | Faible — définissez BackgroundType.Color et attribuez une couleur |
Contrats, notes internes, lettres officielles nécessitant une teinte de base propre et professionnelle |
| Dégradé | Un mélange directionnel de deux couleurs sur toute la page | Moyen — définissez Color1, Color2, ainsi que ShadingStyle et ShadingVariant
|
Pages de couverture, certificats, modèles marketing qui bénéficient d'une profondeur subtile |
| Image | Une image d'arrière-plan répétée sur toute la page | Moyen — chargez l'image dans le VFS, puis appelez SetPicture
|
Papeterie de marque, en-têtes avec éléments décoratifs, modèles de documents à thème |
Les trois partagent le même flux de travail global : chargez le document source dans le VFS, configurez la propriété Background sur une instance Document, enregistrez le résultat et déclenchez un téléchargement dans le navigateur. Les différences résident entièrement dans la manière dont vous configurez cette propriété Background — c'est là que les choix de conception entrent en jeu.
Pour la configuration du projet et les instructions d'installation, consultez Intégration de Spire.Doc pour JavaScript dans un projet React. Les exemples de code ci-dessous supposent que le module WASM est déjà initialisé et disponible sur window.wasmModule.
Arrière-plan de couleur unie
Une couleur unie est le choix d'arrière-plan le plus sobre — et souvent le plus efficace. Un crème chaud ou un gris pâle derrière un texte noir réduit la fatigue oculaire sans attirer l'attention. Pour les documents formels comme les contrats et les documents de politique, une teinte subtile signale « ce document appartient à une organisation spécifique » sans tomber dans la décoration.
L'implémentation suit trois étapes claires. Premièrement, utilisez FetchFileToVFS pour charger le fichier Word cible (et les fichiers de police) dans le système de fichiers virtuel WASM. Deuxièmement, créez un Document, chargez le fichier, définissez Background.Type sur BackgroundType.Color et attribuez une couleur intégrée à Background.Color. Troisièmement, enregistrez le document dans le VFS avec SaveToFile, lisez le fichier résultant sous forme de tableau d'octets, encapsulez-le dans un Blob et lancez un téléchargement.
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;
Une fois Background.Color appliqué, chaque page du document est remplie avec la couleur intégrée choisie — dans ce cas, LightYellow.
Arrière-plan dégradé
Les dégradés introduisent une sensation de dimension que les couleurs unies ne peuvent pas offrir. Une transition de haut en bas du blanc au bleu pâle, par exemple, évoque le ciel et l'ouverture — utile pour les certificats, les lettres de distinction ou tout document où une touche de solennité est appropriée. La clé est la retenue : choisissez deux couleurs proches et laissez le dégradé faire son travail discrètement.
Le code reprend le flux de travail de la couleur unie, mais l'étape intermédiaire s'étoffe. Après avoir défini Background.Type sur BackgroundType.Gradient, vous récupérez l'objet dégradé via Background.Gradient et configurez quatre propriétés : Color1 (couleur de début), Color2 (couleur de fin), ShadingVariant (direction de transition) et ShadingStyle (axe du dégradé).
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;
Après avoir appliqué Background.Gradient, la page est remplie d'une transition horizontale fluide du blanc au bleu clair, s'écoulant vers le bas.
Arrière-plan avec image
Un arrière-plan avec image est l'option la plus expressive. Qu'il s'agisse d'un motif de filigrane subtil, d'une texture d'entreprise ou d'un motif décoratif pour des programmes d'événements, une image répétée peut porter des éléments de marque que la couleur et le dégradé ne peuvent tout simplement pas transmettre. Le compromis est le poids du fichier — l'image doit être chargée dans le VFS en même temps que le document — alors réservez cette approche aux modèles où le rendu visuel justifie la ressource supplémentaire.
La configuration diffère des deux méthodes précédentes d'une manière importante : l'image d'arrière-plan doit également être chargée dans le VFS à l'aide de FetchFileToVFS avant de pouvoir être référencée. Une fois le document et l'image dans le VFS, définissez Background.Type sur BackgroundType.Picture et appelez Background.SetPicture avec le chemin VFS de l'image. L'image est alors répétée sur chaque page en tant qu'arrière-plan.
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;
Après avoir appelé Background.SetPicture, l'image spécifiée est répétée sur toute la surface de la page comme arrière-plan du document.
Considérations d'impression
Il existe une mise en garde pratique qui prend de nombreux développeurs au dépourvu : Microsoft Word n'imprime pas les arrière-plans de page par défaut. Ce n'est pas un bug dans votre code ni une limitation de Spire.Doc — l'arrière-plan est correctement stocké dans le document et s'affiche normalement à l'écran. Word l'omet simplement de la sortie imprimée, sauf si vous lui indiquez explicitement le contraire.
Pour que les arrière-plans apparaissent sur les copies imprimées, l'utilisateur final doit activer un paramètre spécifique dans son client Word :
- Ouvrez le document dans Microsoft Word.
- Accédez à Fichier > Options > Affichage.
- Cochez Imprimer les couleurs et les images d'arrière-plan.
- Imprimez comme d'habitude.
Si vous avez besoin que l'arrière-plan s'affiche dans tous les environnements de sortie, quels que soient les paramètres Word du lecteur, envisagez une approche alternative : placez une forme pleine page dans l'en-tête du document ou utilisez un filigrane pour simuler l'effet d'arrière-plan. Ces techniques sont traitées comme du contenu plutôt que comme une mise en forme de page, de sorte qu'elles s'impriment de manière fiable dans toutes les configurations.
FAQ
Pourquoi l'arrière-plan n'apparaît-il pas lorsque j'imprime le document ?
Il s'agit d'un comportement attendu. Word supprime les arrière-plans de page dans la sortie imprimée par défaut — le paramètre est correctement stocké et s'affiche à l'écran, mais les options d'impression du client Word le filtrent. L'arrière-plan n'a pas été perdu ; il n'est simplement pas inclus dans le flux d'impression.
Pour corriger cela, activez Imprimer les couleurs et les images d'arrière-plan sous Fichier > Options > Affichage dans Word avant d'imprimer. Pour les environnements où vous ne pouvez pas contrôler les paramètres d'impression du lecteur, utilisez une forme pleine page dans l'en-tête ou un filigrane pour reproduire l'effet visuel, car ces éléments sont traités comme du contenu imprimable.
Pourquoi l'arrière-plan avec image n'a-t-il aucun effet ?
Cela se produit généralement pour l'une des deux raisons suivantes : soit Background.Type n'a pas été défini sur BackgroundType.Picture avant d'appeler SetPicture, soit le fichier image n'a jamais été chargé dans le VFS via FetchFileToVFS, de sorte que SetPicture ne peut pas le localiser.
Assurez-vous de définir d'abord le type d'arrière-plan et de transmettre le nom de fichier exact d'une image déjà chargée dans le système de fichiers virtuel :
document.Background.Type = wasmModule.BackgroundType.Picture;
document.Background.SetPicture("Background.png");