Definir planos de fundo de documentos do Word com JavaScript

Todo contrato, carta oficial e peça de comunicação da marca carrega uma identidade visual implícita. Uma página branca comum cumpre a função, mas não diz nada sobre a organização por trás dela. No momento em que você adiciona uma tonalidade suave, um gradiente sutil de dois tons ou uma imagem de fundo repetida, todo o documento deixa de ser um arquivo genérico e se torna um artefato de marca reconhecível — e seus leitores percebem, mesmo que não consigam explicar o porquê.

Spire.Doc for JavaScript traz esse estilo visual diretamente para o navegador por meio do WebAssembly. Não há ida e volta ao servidor, nem dependência de automação do Office, nem necessidade de instalação no desktop. Você carrega um arquivo do Word no sistema de arquivos virtual (VFS) do WASM, escolhe um dos três modos de plano de fundo e exporta o documento estilizado — tudo do lado do cliente em um aplicativo React.

Este guia aborda cada uma das três opções de plano de fundo não como um catálogo de API, mas como um conjunto de decisões de design. Começamos com uma comparação rápida para que você possa associar a técnica certa ao seu caso de uso e, em seguida, aprofundamos os detalhes de implementação de cada uma.

Três abordagens de plano de fundo em resumo

Antes de escrever qualquer código, é útil entender o que cada tipo de plano de fundo oferece do ponto de vista de design. A tabela abaixo resume o resultado visual, a quantidade de configuração envolvida e os cenários em que cada abordagem se destaca.

Todas as três compartilham o mesmo fluxo de trabalho geral: carregar o documento de origem no VFS, configurar a propriedade Background em uma instância de Document, salvar o resultado e acionar o download no navegador. As diferenças estão inteiramente na forma como você configura essa propriedade Background — é aí que entram as escolhas de design.

Para configuração do projeto e instruções de instalação, consulte Integrando o Spire.Doc for JavaScript em um projeto React. Os exemplos de código abaixo pressupõem que o módulo WASM já foi inicializado e está disponível em window.wasmModule.

Plano de fundo de cor sólida

Uma cor sólida é a escolha de plano de fundo mais contida — e, muitas vezes, a mais eficaz. Um creme quente ou cinza claro atrás de texto preto reduz o cansaço visual sem competir por atenção. Para documentos formais, como contratos e documentos de políticas, uma tonalidade sutil sinaliza "este documento pertence a uma organização específica" sem chegar a ser decoração.

A implementação segue três etapas claras. Primeiro, use FetchFileToVFS para carregar o arquivo Word de destino (e os arquivos de fonte) no sistema de arquivos virtual do WASM. Segundo, crie um Document, carregue o arquivo, defina Background.Type como BackgroundType.Color e atribua uma cor interna a Background.Color. Terceiro, salve o documento de volta no VFS com SaveToFile, leia o arquivo resultante como uma matriz de bytes, envolva-o em um Blob e inicie um 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;

Depois que Background.Color é aplicado, todas as páginas do documento são preenchidas com a cor interna escolhida — neste caso, LightYellow.

Plano de fundo com gradiente

Gradientes introduzem uma sensação de dimensão que cores planas não conseguem. Uma transição de cima para baixo, do branco para o azul-claro, por exemplo, evoca céu e abertura — útil para certificados, cartas de premiação ou qualquer documento em que um toque de formalidade seja apropriado. A chave é a contenção: escolha duas cores intimamente relacionadas e deixe o gradiente fazer o trabalho discretamente.

O código espelha o fluxo de trabalho da cor sólida, mas a etapa intermediária se amplia. Depois de definir Background.Type como BackgroundType.Gradient, você recupera o objeto de gradiente via Background.Gradient e configura quatro propriedades: Color1 (cor inicial), Color2 (cor final), ShadingVariant (direção da transição) e ShadingStyle (eixo do 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;

Depois de aplicar Background.Gradient, a página é preenchida com uma transição horizontal suave de branco para azul-claro, fluindo para baixo.

Plano de fundo com imagem

Um plano de fundo com imagem é a opção mais expressiva. Seja um padrão de marca d'água sutil, uma textura corporativa ou um motivo decorativo para programas de eventos, uma imagem repetida pode carregar elementos de marca que cor e gradiente simplesmente não conseguem. A desvantagem é o peso do arquivo — a imagem precisa ser carregada no VFS junto com o documento —, então reserve essa abordagem para modelos em que o resultado visual justifique o recurso extra.

A configuração difere dos dois métodos anteriores de uma maneira importante: a imagem de plano de fundo também precisa ser carregada no VFS usando FetchFileToVFS antes de poder ser referenciada. Depois que o documento e a imagem estiverem no VFS, defina Background.Type como BackgroundType.Picture e chame Background.SetPicture com o caminho da imagem no VFS. A imagem então é repetida por todas as páginas como plano de fundo.

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;

Depois de chamar Background.SetPicture, a imagem especificada é repetida por toda a superfície da página como plano de fundo do documento.

Considerações sobre impressão

Há uma ressalva prática que pega muitos desenvolvedores de surpresa: o Microsoft Word não imprime planos de fundo de página por padrão. Isso não é um bug no seu código nem uma limitação do Spire.Doc — o plano de fundo é armazenado corretamente no documento e é exibido normalmente na tela. O Word simplesmente o omite da saída impressa, a menos que você diga explicitamente o contrário.

Para garantir que os planos de fundo apareçam em cópias impressas, o usuário final precisa habilitar uma configuração específica no cliente do Word:

1. Abra o documento no Microsoft Word.
2. Vá para Arquivo > Opções > Exibir.
3. Marque Imprimir cores e imagens de plano de fundo.
4. Imprima normalmente.

Se você precisa que o plano de fundo seja renderizado em todos os ambientes de saída, independentemente das configurações do Word do leitor, considere uma abordagem alternativa: coloque uma forma de página inteira no cabeçalho do documento ou use uma marca d'água para simular o efeito de plano de fundo. Essas técnicas são tratadas como conteúdo, e não como formatação de página, então são impressas de forma confiável em todas as configurações.

Perguntas frequentes

Por que o plano de fundo não aparece quando imprimo o documento?

Este é o comportamento esperado. O Word suprime planos de fundo de página na saída de impressão por padrão — a configuração é armazenada corretamente e é renderizada na tela, mas as opções de impressão do cliente Word a filtram. O plano de fundo não foi perdido; ele simplesmente não é incluído no fluxo de impressão.

Para corrigir isso, habilite Imprimir cores e imagens de plano de fundo em Arquivo > Opções > Exibir no Word antes de imprimir. Para ambientes em que você não pode controlar as configurações de impressão do leitor, use uma forma de página inteira no cabeçalho ou uma marca d'água para replicar o efeito visual, pois esses elementos são tratados como conteúdo imprimível.

Por que o plano de fundo com imagem não tem efeito?

Isso geralmente acontece por um de dois motivos: ou Background.Type não foi definido como BackgroundType.Picture antes de chamar SetPicture, ou o arquivo de imagem nunca foi carregado no VFS via FetchFileToVFS, então SetPicture não consegue localizá-lo.

Certifique-se de definir o tipo de plano de fundo primeiro e passar o nome de arquivo exato de uma imagem que já foi carregada no sistema de arquivos virtual:

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

Veja também

• Como integrar o Spire.Doc for JavaScript em um projeto React
• Definir marcas d'água do Word com Spire.Doc for JavaScript
• Definir propriedades de documento do Word com Spire.Doc for JavaScript
• Definir margens de página do Word com Spire.Doc for JavaScript