Word-Dokument-Hintergründe mit JavaScript festlegen

Jeder Vertrag, jedes offizielle Schreiben und jedes Stück Markenkommunikation trägt eine implizite visuelle Identität. Eine schlichte weiße Seite erfüllt ihren Zweck, sagt aber nichts über die dahinterstehende Organisation aus. In dem Moment, in dem Sie eine sanfte Tönung, einen dezenten zweifarbigen Verlauf oder ein gekacheltes Hintergrundbild hinzufügen, verwandelt sich das gesamte Dokument von einer generischen Datei in ein wiedererkennbares Markenartefakt – und Ihre Leser bemerken es, auch wenn sie nicht in Worte fassen können, warum.

Spire.Doc for JavaScript bringt diese visuelle Gestaltung über WebAssembly direkt in den Browser. Es gibt keinen Server-Roundtrip, keine Abhängigkeit von Office-Automatisierung und keine Notwendigkeit einer Desktop-Installation. Sie laden eine Word-Datei in das virtuelle Dateisystem (VFS) von WASM, wählen einen von drei Hintergrundmodi und exportieren das gestaltete Dokument – alles clientseitig in einer React-Anwendung.

Dieser Leitfaden behandelt jede der drei Hintergrundoptionen nicht als API-Katalog, sondern als eine Reihe von Designentscheidungen. Wir beginnen mit einem kurzen Vergleich, damit Sie die richtige Technik für Ihren Anwendungsfall auswählen können, und tauchen dann in die Implementierungsdetails für jede einzelne ein.

Drei Hintergrundansätze auf einen Blick

Bevor Sie Code schreiben, ist es hilfreich zu verstehen, was jeder Hintergrundtyp aus Designperspektive bietet. Die folgende Tabelle fasst das visuelle Ergebnis, den Konfigurationsaufwand und die Szenarien zusammen, in denen jeder Ansatz seine Stärken ausspielt.

Alle drei teilen denselben Gesamtworkflow: Laden Sie das Quelldokument in das VFS, konfigurieren Sie die Eigenschaft Background einer Document-Instanz, speichern Sie das Ergebnis und lösen Sie einen Browser-Download aus. Die Unterschiede liegen ausschließlich darin, wie Sie diese Eigenschaft Background konfigurieren – und genau hier kommen die Designentscheidungen ins Spiel.

Informationen zur Projekteinrichtung und Installation finden Sie unter Integrating Spire.Doc for JavaScript in a React Project. Die folgenden Codebeispiele setzen voraus, dass das WASM-Modul bereits initialisiert und unter window.wasmModule verfügbar ist.

Einfarbiger Hintergrund

Eine einfarbige Hintergrundfarbe ist die zurückhaltendste Wahl – und oft die wirkungsvollste. Ein warmes Creme oder ein helles Grau hinter schwarzem Text reduziert die Augenbelastung, ohne um Aufmerksamkeit zu konkurrieren. Bei formellen Dokumenten wie Verträgen und Richtlinienpapieren signalisiert eine dezente Tönung: „Dieses Dokument gehört zu einer bestimmten Organisation“, ohne in Dekoration abzudriften.

Die Implementierung folgt drei klaren Schritten. Zunächst laden Sie mit FetchFileToVFS die Ziel-Word-Datei (und Schriftdateien) in das virtuelle Dateisystem von WASM. Zweitens erstellen Sie ein Document, laden die Datei, setzen Background.Type auf BackgroundType.Color und weisen Background.Color eine integrierte Farbe zu. Drittens speichern Sie das Dokument mit SaveToFile zurück in das VFS, lesen die resultierende Datei als Byte-Array ein, verpacken sie in einen Blob und starten einen 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;

Sobald Background.Color angewendet wurde, wird jede Seite des Dokuments mit der gewählten integrierten Farbe gefüllt – in diesem Fall LightYellow.

Verlaufshintergrund

Verläufe vermitteln ein Gefühl von Räumlichkeit, das flache Farben nicht bieten können. Ein Übergang von Weiß zu Hellblau von oben nach unten beispielsweise weckt Assoziationen an Himmel und Offenheit – nützlich für Zertifikate, Auszeichnungsschreiben oder jedes Dokument, bei dem ein Hauch von Feierlichkeit angebracht ist. Der Schlüssel ist Zurückhaltung: Wählen Sie zwei eng verwandte Farben und lassen Sie den Verlauf die Arbeit leise erledigen.

Der Code entspricht dem Workflow für einfarbige Hintergründe, doch der mittlere Schritt wird umfangreicher. Nachdem Sie Background.Type auf BackgroundType.Gradient gesetzt haben, rufen Sie das Verlaufsobjekt über Background.Gradient ab und konfigurieren vier Eigenschaften: Color1 (Startfarbe), Color2 (Endfarbe), ShadingVariant (Übergangsrichtung) und ShadingStyle (Achse des Verlaufs).

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;

Nach dem Anwenden von Background.Gradient wird die Seite mit einem sanften horizontalen Übergang von Weiß zu Hellblau gefüllt, der nach unten fließt.

Bildhintergrund

Ein Bildhintergrund ist die ausdrucksstärkste Option. Ob es sich um ein dezentes Wasserzeichenmuster, eine Unternehmensstruktur oder ein dekoratives Motiv für Veranstaltungsprogramme handelt – ein gekacheltes Bild kann Branding-Elemente transportieren, die Farbe und Verlauf einfach nicht leisten können. Der Kompromiss ist das Dateigewicht – das Bild muss zusammen mit dem Dokument in das VFS geladen werden –, daher sollten Sie diesen Ansatz für Vorlagen reservieren, bei denen der visuelle Nutzen den zusätzlichen Ressourceneinsatz rechtfertigt.

Die Einrichtung unterscheidet sich in einem wichtigen Punkt von den beiden vorherigen Methoden: Das Hintergrundbild muss ebenfalls mit FetchFileToVFS in das VFS geladen werden, bevor es referenziert werden kann. Sobald sowohl das Dokument als auch das Bild im VFS liegen, setzen Sie Background.Type auf BackgroundType.Picture und rufen Background.SetPicture mit dem VFS-Pfad des Bildes auf. Das Bild wird dann als Hintergrund über jede Seite gekachelt.

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;

Nach dem Aufruf von Background.SetPicture wird das angegebene Bild als Dokumenthintergrund über die gesamte Seitenfläche gekachelt.

Hinweise zum Drucken

Es gibt einen praktischen Vorbehalt, der viele Entwickler überrascht: Microsoft Word druckt Seitenhintergründe standardmäßig nicht. Das ist kein Fehler in Ihrem Code und keine Einschränkung von Spire.Doc – der Hintergrund wird korrekt im Dokument gespeichert und normal auf dem Bildschirm angezeigt. Word lässt ihn lediglich aus der Druckausgabe weg, es sei denn, Sie weisen es ausdrücklich anders an.

Damit Hintergründe in gedruckten Exemplaren erscheinen, muss der Endbenutzer eine bestimmte Einstellung in seinem Word-Client aktivieren:

1. Öffnen Sie das Dokument in Microsoft Word.
2. Gehen Sie zu Datei > Optionen > Anzeige.
3. Aktivieren Sie Hintergrundfarben und -bilder drucken.
4. Drucken Sie wie gewohnt.

Wenn der Hintergrund in jeder Ausgabeumgebung gerendert werden soll, unabhängig von den Word-Einstellungen des Lesers, sollten Sie einen alternativen Ansatz in Betracht ziehen: Platzieren Sie eine ganzseitige Form in der Kopfzeile des Dokuments oder verwenden Sie ein Wasserzeichen, um den Hintergrundeffekt zu simulieren. Diese Techniken werden als Inhalt und nicht als Seitenformatierung behandelt, sodass sie in allen Konfigurationen zuverlässig gedruckt werden.

FAQ

Warum wird der Hintergrund beim Drucken des Dokuments nicht angezeigt?

Dies ist das erwartete Verhalten. Word unterdrückt Seitenhintergründe standardmäßig in der Druckausgabe – die Einstellung wird korrekt gespeichert und auf dem Bildschirm gerendert, aber die Druckoptionen des Word-Clients filtern sie heraus. Der Hintergrund ist nicht verloren gegangen; er wird einfach nicht in den Druckdatenstrom aufgenommen.

Um dies zu beheben, aktivieren Sie in Word vor dem Drucken Hintergrundfarben und -bilder drucken unter Datei > Optionen > Anzeige. In Umgebungen, in denen Sie die Druckeinstellungen des Lesers nicht kontrollieren können, verwenden Sie eine ganzseitige Form in der Kopfzeile oder ein Wasserzeichen, um den visuellen Effekt nachzubilden, da diese Elemente als druckbarer Inhalt behandelt werden.

Warum hat der Bildhintergrund keine Wirkung?

Dies geschieht typischerweise aus einem von zwei Gründen: Entweder wurde Background.Type nicht auf BackgroundType.Picture gesetzt, bevor SetPicture aufgerufen wurde, oder die Bilddatei wurde nie über FetchFileToVFS in das VFS geladen, sodass SetPicture sie nicht finden kann.

Stellen Sie sicher, dass Sie zuerst den Hintergrundtyp festlegen und den exakten Dateinamen eines Bildes übergeben, das bereits in das virtuelle Dateisystem geladen wurde:

document.Background.Type = wasmModule.BackgroundType.Picture;
document.Background.SetPicture("Background.png");

Siehe auch

• How to Integrate Spire.Doc for JavaScript in a React Project
• Set Word Watermarks with Spire.Doc for JavaScript
• Set Word Document Properties with Spire.Doc for JavaScript
• Set Word Page Margins with Spire.Doc for JavaScript