Establecer fondos de documentos de Word con JavaScript

Cada contrato, carta oficial y pieza de material de marca conlleva una identidad visual implícita. Una página blanca simple cumple su función, pero no dice nada sobre la organización que la respalda. En el momento en que añades un tinte suave, un sutil degradado de dos tonos o una imagen de fondo en mosaico, todo el documento pasa de ser un archivo genérico a un artefacto de marca reconocible, y tus lectores lo notan, aunque no sepan explicar por qué.

Spire.Doc for JavaScript lleva este estilo visual directamente al navegador a través de WebAssembly. No hay ida y vuelta al servidor, ni dependencia de automatización de Office, ni requisito de instalación en el escritorio. Cargas un archivo de Word en el sistema de archivos virtual (VFS) de WASM, eliges uno de los tres modos de fondo y exportas el documento con estilo, todo del lado del cliente en una aplicación React.

Esta guía recorre cada una de las tres opciones de fondo no como un catálogo de API, sino como un conjunto de decisiones de diseño. Comenzamos con una comparación rápida para que puedas relacionar la técnica adecuada con tu caso de uso, y luego profundizamos en los detalles de implementación de cada una.

Tres enfoques de fondo de un vistazo

Antes de escribir cualquier código, ayuda entender qué aporta cada tipo de fondo desde una perspectiva de diseño. La siguiente tabla resume el resultado visual, la cantidad de configuración necesaria y los escenarios en los que destaca cada enfoque.

Los tres comparten el mismo flujo de trabajo general: carga el documento de origen en el VFS, configura la propiedad Background en una instancia de Document, guarda el resultado y activa una descarga en el navegador. Las diferencias residen enteramente en cómo configuras esa propiedad Background, que es donde entran las decisiones de diseño.

Para obtener instrucciones de configuración e instalación del proyecto, consulta Integración de Spire.Doc for JavaScript en un proyecto de React. Los ejemplos de código a continuación asumen que el módulo WASM ya está inicializado y disponible en window.wasmModule.

Fondo de color sólido

Un color sólido es la opción de fondo más sobria, y a menudo la más eficaz. Un tono crema cálido o gris pálido detrás de texto negro reduce la fatiga visual sin competir por la atención. Para documentos formales como contratos y documentos de políticas, un tinte sutil indica "este documento pertenece a una organización específica" sin llegar a ser decorativo.

La implementación sigue tres pasos claros. Primero, usa FetchFileToVFS para cargar el archivo de Word objetivo (y los archivos de fuentes) en el sistema de archivos virtual de WASM. Segundo, crea un Document, carga el archivo, establece Background.Type en BackgroundType.Color y asigna un color integrado a Background.Color. Tercero, guarda el documento de nuevo en el VFS con SaveToFile, lee el archivo resultante como una matriz de bytes, envuélvelo en un Blob e inicia una descarga.

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 vez aplicado Background.Color, cada página del documento se rellena con el color integrado elegido; en este caso, LightYellow.

Fondo degradado

Los degradados introducen una sensación de dimensión que los colores planos no pueden lograr. Una transición de arriba a abajo de blanco a azul pálido, por ejemplo, evoca el cielo y la apertura; es útil para certificados, cartas de reconocimiento o cualquier documento donde sea apropiado un toque de ceremonia. La clave está en la moderación: elige dos colores estrechamente relacionados y deja que el degradado haga su trabajo discretamente.

El código refleja el flujo de trabajo del color sólido, pero el paso intermedio se amplía. Después de establecer Background.Type en BackgroundType.Gradient, recuperas el objeto de degradado mediante Background.Gradient y configuras cuatro propiedades: Color1 (color inicial), Color2 (color final), ShadingVariant (dirección de la transición) y ShadingStyle (eje del degradado).

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;

Después de aplicar Background.Gradient, la página se rellena con una transición horizontal suave de blanco a azul claro, que fluye hacia abajo.

Fondo de imagen

Un fondo de imagen es la opción más expresiva. Ya sea un sutil patrón de marca de agua, una textura corporativa o un motivo decorativo para programas de eventos, una imagen en mosaico puede llevar elementos de marca que el color y el degradado simplemente no pueden. La contrapartida es el peso del archivo: la imagen debe cargarse en el VFS junto con el documento, así que reserva este enfoque para plantillas donde la recompensa visual justifique el recurso adicional.

La configuración difiere de los dos métodos anteriores en un aspecto importante: la imagen de fondo también debe cargarse en el VFS mediante FetchFileToVFS antes de poder referenciarla. Una vez que tanto el documento como la imagen están en el VFS, establece Background.Type en BackgroundType.Picture y llama a Background.SetPicture con la ruta de la imagen en el VFS. La imagen se coloca entonces en mosaico en todas las páginas como fondo.

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;

Después de llamar a Background.SetPicture, la imagen especificada se coloca en mosaico por toda la superficie de la página como fondo del documento.

Consideraciones de impresión

Hay una advertencia práctica que toma por sorpresa a muchos desarrolladores: Microsoft Word no imprime los fondos de página de forma predeterminada. Esto no es un error en tu código ni una limitación de Spire.Doc; el fondo se almacena correctamente en el documento y se muestra normalmente en pantalla. Word simplemente lo omite en la salida impresa a menos que le indiques explícitamente lo contrario.

Para garantizar que los fondos aparezcan en las copias impresas, el usuario final debe habilitar una configuración específica en su cliente de Word:

1. Abre el documento en Microsoft Word.
2. Ve a Archivo > Opciones > Mostrar.
3. Marca Imprimir colores e imágenes de fondo.
4. Imprime como de costumbre.

Si necesitas que el fondo se represente en todos los entornos de salida, independientemente de la configuración de Word del lector, considera un enfoque alternativo: coloca una forma de página completa en el encabezado del documento o usa una marca de agua para simular el efecto de fondo. Estas técnicas se tratan como contenido en lugar de formato de página, por lo que se imprimen de forma fiable en todas las configuraciones.

Preguntas frecuentes

¿Por qué no aparece el fondo cuando imprimo el documento?

Este es el comportamiento esperado. Word suprime los fondos de página en la salida impresa de forma predeterminada; la configuración se almacena correctamente y se representa en pantalla, pero las opciones de impresión del cliente de Word la filtran. El fondo no se ha perdido; simplemente no se incluye en el flujo de impresión.

Para solucionarlo, habilita Imprimir colores e imágenes de fondo en Archivo > Opciones > Mostrar en Word antes de imprimir. En entornos donde no puedas controlar la configuración de impresión del lector, usa una forma de página completa en el encabezado o una marca de agua para replicar el efecto visual, ya que esos elementos se tratan como contenido imprimible.

¿Por qué el fondo de imagen no tiene efecto?

Esto suele ocurrir por una de dos razones: o bien Background.Type no se estableció en BackgroundType.Picture antes de llamar a SetPicture, o el archivo de imagen nunca se cargó en el VFS mediante FetchFileToVFS, por lo que SetPicture no puede localizarlo.

Asegúrate de establecer primero el tipo de fondo y pasar el nombre de archivo exacto de una imagen que ya se haya cargado en el sistema de archivos virtual:

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

Véase también

• Cómo integrar Spire.Doc for JavaScript en un proyecto de React
• Establecer marcas de agua de Word con Spire.Doc for JavaScript
• Establecer propiedades de documentos de Word con Spire.Doc for JavaScript
• Establecer márgenes de página de Word con Spire.Doc for JavaScript