모든 계약서, 공식 서신, 브랜드 홍보물에는 암묵적인 시각적 정체성이 담겨 있습니다. 순백의 페이지도 용도는 충분히 해내지만, 그 뒤에 있는 조직에 대해서는 아무것도 말해 주지 않습니다. 부드러운 색조, 은은한 두 가지 색 그라데이션, 또는 타일로 반복되는 배경 이미지를 추가하는 순간, 문서 전체가 일반적인 파일에서 알아볼 수 있는 브랜드 결과물로 바뀌며, 독자들은 그 이유를 설명하지 못하더라도 이를 알아차립니다.

Spire.Doc for JavaScript는 WebAssembly를 통해 이러한 시각적 스타일링을 브라우저로 직접 가져옵니다. 서버 왕복도, Office 자동화 의존성도, 데스크톱 설치 요구 사항도 없습니다. Word 파일을 WASM 가상 파일 시스템(VFS)에 로드하고, 세 가지 배경 모드 중 하나를 선택한 다음, 스타일이 적용된 문서를 내보냅니다. 이 모든 과정이 React 애플리케이션의 클라이언트 측에서 이루어집니다.

이 가이드는 세 가지 배경 옵션 각각을 API 목록이 아니라 일련의 디자인 결정으로 살펴봅니다. 먼저 빠른 비교를 통해 사용 사례에 맞는 올바른 기법을 선택할 수 있도록 한 다음, 각각의 구현 세부 사항으로 들어갑니다.

한눈에 보는 세 가지 배경 접근법

코드를 작성하기 전에, 각 배경 유형이 디자인 관점에서 어떤 가치를 제공하는지 이해하면 도움이 됩니다. 아래 표는 시각적 결과, 필요한 구성의 정도, 각 접근법이 빛을 발하는 시나리오를 요약합니다.

세 가지 모두 동일한 전체 워크플로를 공유합니다. 원본 문서를 VFS에 로드하고, Document 인스턴스의 Background 속성을 구성하고, 결과를 저장한 다음, 브라우저 다운로드를 트리거합니다. 차이는 전적으로 해당 Background 속성을 구성하는 방식에 있으며, 바로 여기에서 디자인 선택이 시작됩니다.

프로젝트 설정 및 설치 지침은 React 프로젝트에 Spire.Doc for JavaScript 통합하기를 참조하세요. 아래 코드 예제는 WASM 모듈이 이미 초기화되어 window.wasmModule에서 사용할 수 있다고 가정합니다.

단색 배경

단색은 가장 절제된 배경 선택이며, 종종 가장 효과적입니다. 검은색 텍스트 뒤의 따뜻한 크림색이나 옅은 회색은 시선을 빼앗지 않으면서 눈의 피로를 줄여 줍니다. 계약서와 정책 문서 같은 공식 문서에서 은은한 색조는 "이 문서는 특정 조직에 속한다"는 신호를 주면서 장식으로 넘어가지 않습니다.

구현은 세 가지 명확한 단계를 따릅니다. 첫째, FetchFileToVFS를 사용하여 대상 Word 파일(및 글꼴 파일)을 WASM 가상 파일 시스템에 로드합니다. 둘째, Document를 만들고, 파일을 로드하고, Background.Type을 BackgroundType.Color로 설정한 다음, Background.Color에 기본 제공 색상을 할당합니다. 셋째, SaveToFile로 문서를 다시 VFS에 저장하고, 결과 파일을 바이트 배열로 읽고, Blob으로 감싼 다음, 다운로드를 시작합니다.

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;

Background.Color가 적용되면 문서의 모든 페이지가 선택한 기본 제공 색상으로 채워집니다. 여기서는 LightYellow입니다.

그라데이션 배경

그라데이션은 단색이 줄 수 없는 입체감을 도입합니다. 예를 들어 흰색에서 옅은 파란색으로 이어지는 위에서 아래 방향의 전환은 하늘과 개방감을 연상시키며, 인증서, 상장, 또는 약간의 격식이 어울리는 모든 문서에 유용합니다. 핵심은 절제입니다. 서로 가까운 두 색상을 선택하고 그라데이션이 조용히 제 역할을 하도록 두세요.

코드는 단색 워크플로를 그대로 따르지만, 중간 단계가 확장됩니다. Background.Type을 BackgroundType.Gradient로 설정한 후, Background.Gradient를 통해 그라데이션 개체를 가져와 네 가지 속성을 구성합니다: Color1(시작 색), Color2(끝 색), ShadingVariant(전환 방향), ShadingStyle(그라데이션의 축).

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;

Background.Gradient를 적용하면 페이지가 흰색에서 연한 파란색으로 이어지는 부드러운 가로 전환으로 채워지며, 아래쪽으로 흐릅니다.

그림 배경

그림 배경은 가장 표현력이 뛰어난 옵션입니다. 은은한 워터마크 패턴, 기업 텍스처, 또는 행사 프로그램용 장식 모티프 등 어떤 것이든, 타일로 반복되는 이미지는 색상과 그라데이션이 단순히 담을 수 없는 브랜딩 요소를 전달할 수 있습니다. 대신 파일 무게가 늘어납니다. 이미지를 문서와 함께 VFS에 로드해야 하므로, 시각적 효과가 추가 리소스를 정당화하는 템플릿에 이 접근법을 사용하세요.

설정은 이전 두 방법과 한 가지 중요한 점에서 다릅니다. 배경 이미지도 참조하기 전에 FetchFileToVFS를 사용하여 VFS에 로드해야 합니다. 문서와 이미지가 모두 VFS에 있으면 Background.Type을 BackgroundType.Picture로 설정하고, 이미지의 VFS 경로를 사용하여 Background.SetPicture를 호출합니다. 그러면 이미지가 모든 페이지에 배경으로 타일링됩니다.

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;

Background.SetPicture를 호출하면 지정한 이미지가 문서 배경으로 전체 페이지 표면에 타일링됩니다.

인쇄 시 고려 사항

많은 개발자를 당황하게 하는 실용적인 주의 사항이 하나 있습니다: Microsoft Word는 기본적으로 페이지 배경을 인쇄하지 않습니다. 이것은 코드의 버그나 Spire.Doc의 제한이 아닙니다. 배경은 문서에 올바르게 저장되며 화면에서는 정상적으로 표시됩니다. Word는 명시적으로 설정하지 않는 한 인쇄 출력에서 이를 생략할 뿐입니다.

인쇄본에 배경이 나타나게 하려면 최종 사용자가 Word 클라이언트에서 특정 설정을 활성화해야 합니다:

1. Microsoft Word에서 문서를 엽니다.
2. 파일 > 옵션 > 표시로 이동합니다.
3. 배경색 및 이미지 인쇄를 선택합니다.
4. 평소처럼 인쇄합니다.

독자의 Word 설정과 관계없이 모든 출력 환경에서 배경이 렌더링되도록 해야 한다면, 대체 접근법을 고려하세요. 문서 머리글에 전체 페이지 도형을 배치하거나 워터마크를 사용하여 배경 효과를 시뮬레이션하는 것입니다. 이러한 기법은 페이지 서식이 아니라 콘텐츠로 처리되므로 모든 구성에서 안정적으로 인쇄됩니다.

자주 묻는 질문

문서를 인쇄할 때 배경이 표시되지 않는 이유는 무엇인가요?

이는 예상된 동작입니다. Word는 기본적으로 인쇄 출력에서 페이지 배경을 숨깁니다. 설정은 올바르게 저장되고 화면에서는 렌더링되지만, Word 클라이언트의 인쇄 옵션이 이를 걸러냅니다. 배경이 사라진 것이 아니라 단순히 인쇄 스트림에 포함되지 않았을 뿐입니다.

이 문제를 해결하려면 인쇄하기 전에 Word에서 파일 > 옵션 > 표시 아래의 배경색 및 이미지 인쇄를 활성화하세요. 독자의 인쇄 설정을 제어할 수 없는 환경에서는 머리글에 전체 페이지 도형을 넣거나 워터마크를 사용하여 시각 효과를 복제하세요. 이러한 요소는 인쇄 가능한 콘텐츠로 처리되기 때문입니다.

그림 배경이 효과가 없는 이유는 무엇인가요?

일반적으로 두 가지 이유 중 하나로 발생합니다. SetPicture를 호출하기 전에 Background.Type을 BackgroundType.Picture로 설정하지 않았거나, 이미지 파일이 FetchFileToVFS를 통해 VFS에 로드되지 않아 SetPicture가 해당 파일을 찾을 수 없는 경우입니다.

먼저 배경 유형을 설정하고, 이미 가상 파일 시스템에 로드된 이미지의 정확한 파일 이름을 전달해야 합니다:

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

참고 항목

• React 프로젝트에 Spire.Doc for JavaScript를 통합하는 방법
• Spire.Doc for JavaScript로 Word 워터마크 설정하기
• Spire.Doc for JavaScript로 Word 문서 속성 설정하기
• Spire.Doc for JavaScript로 Word 페이지 여백 설정하기

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

Documentos do Word são frequentemente o ponto de partida para conteúdo web — artigos, especificações de produtos e documentos de conformidade, todos precisam eventualmente estar em um site. Passar de .docx para HTML limpo sem um serviço de conversão em backend é o desafio. O Spire.Doc for JavaScript torna isso possível ao executar um mecanismo completo de processamento de documentos em WebAssembly, lendo o arquivo do Word por meio de um sistema de arquivos virtual (VFS), realizando a conversão localmente e permitindo que você baixe o HTML resultante — tudo no lado do cliente, sem ida e volta ao servidor.

Duas estratégias de exportação dominam o fluxo de trabalho, e escolher entre elas é a verdadeira decisão:

• O modo Incorporado agrupa CSS e imagens diretamente no arquivo HTML, produzindo um único documento autocontido que abre em qualquer lugar.
• O modo Externo grava CSS e imagens em arquivos separados, resultando em um HTML menor, folhas de estilo reutilizáveis e recursos de imagem individuais que você pode gerenciar de forma independente.

Este artigo percorre ambas as abordagens em um projeto React e as compara lado a lado. Para configuração, consulte Integrando o Spire.Doc for JavaScript em um Projeto React. Os exemplos abaixo pressupõem que o Spire.Doc está instalado e o módulo WebAssembly está inicializado.

Conversão Básica: Incorpore Tudo em Um Único Arquivo

A maneira mais simples de publicar um documento do Word como página web é produzir um único arquivo HTML que contenha tudo — marcação, estilos e imagens — em um pacote autocontido. Isso é ideal quando você precisa de um artefato portátil que seja renderizado corretamente onde quer que seja aberto, sem referências a arquivos ausentes ou links quebrados.

A conversão segue três etapas. Primeiro, carregue o arquivo de fonte e o documento de origem do Word no sistema de arquivos virtual do WASM usando FetchFileToVFS. Segundo, crie uma instância de Document, carregue o arquivo, configure HtmlExportOptions para incorporar tanto o CSS quanto as imagens e chame SaveToFile para gravar o HTML. Terceiro, leia o arquivo gerado de volta do VFS, envolva-o em um Blob e dispare o download pelo navegador.

function App() {
  const wordToHtml = async () => {
    // Get the Spire.Doc WASM module
    const docModule = window.wasmModule?.spiredoc;

    // Check if the module is ready
    if (!docModule) {
      alert('Spire.Doc is not ready yet');
      return;
    }

    // Load fonts and the Word file into VFS
    await window.spire.FetchFileToVFS('ARIALUNI.TTF', '/Library/Fonts/', `${process.env.PUBLIC_URL}/static/font/`);
    const inputFileName = 'ToHtml.docx';
    await window.spire.FetchFileToVFS(inputFileName, '', `${process.env.PUBLIC_URL}/static/data/`);

    // Load the Word document
    const wordDocument = new docModule.Document();
    wordDocument.LoadFromFile(inputFileName);

    // Embed the CSS styles into the HTML and embed images as Base64
    wordDocument.HtmlExportOptions.CssStyleSheetType = docModule.CssStyleSheetType.Internal;
    wordDocument.HtmlExportOptions.ImageEmbedded = true;

    // Convert the document to HTML
    const outputFileName = 'ToHtml-result.html';
    wordDocument.SaveToFile({ fileName: outputFileName, fileFormat: docModule.FileFormat.Html });

    // Read the converted file from VFS and trigger download
    const fileArray = window.dotnetRuntime.Module.FS.readFile(outputFileName);
    const blob = new Blob([fileArray], { type: 'text/html;charset=utf-8' });
    const url = URL.createObjectURL(blob);
    const a = window.document.createElement('a');
    a.href = url;
    a.download = outputFileName;
    a.click();
    URL.revokeObjectURL(url);

    // Release resources
    wordDocument.Dispose();
  };

  return (
    <div style={{ textAlign: 'center', height: '300px' }}>
      <h1>Convert Word To HTML</h1>
      <button onClick={wordToHtml}>
        Generate
      </button>
    </div>
  );
}

export default App;

Página HTML gerada a partir de um documento do Word via SaveToFile

Opções de Exportação: CSS e Imagens Separados

Incorporar tudo em um único arquivo é conveniente, mas tem suas desvantagens. Um documento grande com muitas imagens gera um arquivo HTML muito grande, e cada página que compartilha o mesmo estilo carrega sua própria cópia duplicada do CSS. Quando você quer manter estilos de forma centralizada, reutilizar recursos de imagem entre páginas ou manter o payload do HTML pequeno para uma renderização inicial mais rápida, deve exportar o CSS e as imagens como arquivos separados.

HtmlExportOptions oferece controle refinado sobre como cada tipo de recurso é gravado. Você pode direcionar o CSS para um arquivo de folha de estilo nomeado, enviar imagens para um diretório dedicado e até controlar como os campos de formulário são serializados. O resultado não é mais um único arquivo, mas uma estrutura de diretórios contendo o HTML, a folha de estilo e os arquivos de imagem.

O fluxo de trabalho espelha a abordagem incorporada, com dois acréscimos. Antes da conversão, crie um diretório de saída no VFS e use CssStyleSheetFileName e ImagesPath para informar ao Spire.Doc onde gravar cada tipo de recurso. Após a conversão, leia todo o diretório de saída recursivamente, empacote tudo em um arquivo zip usando JSZip e baixe-o em uma única operação.

import JSZip from 'jszip';

function App() {
  const wordToHtmlWithOptions = async () => {
    // Get the Spire.Doc WASM module
    const docModule = window.wasmModule?.spiredoc;

    // Check if the module is ready
    if (!docModule) {
      alert('Spire.Doc is not ready yet');
      return;
    }

    // Load fonts and the Word file into VFS
    await window.spire.FetchFileToVFS('ARIALUNI.TTF', '/Library/Fonts/', `${process.env.PUBLIC_URL}/static/font/`);
    const inputFileName = 'ToHtml.docx';
    await window.spire.FetchFileToVFS(inputFileName, '', `${process.env.PUBLIC_URL}/static/data/`);

    // Create the output directory in VFS
    const outputDirectoryName = 'ToHTMLFolder/';
    window.dotnetRuntime.Module.FS.mkdirTree(outputDirectoryName);

    // Load the Word document
    const wordDocument = new docModule.Document();
    wordDocument.LoadFromFile(inputFileName);

    // Export the CSS styles to a separate file
    wordDocument.HtmlExportOptions.CssStyleSheetFileName = outputDirectoryName + 'sample.css';
    wordDocument.HtmlExportOptions.CssStyleSheetType = docModule.CssStyleSheetType.External;

    // Export images to a separate directory
    wordDocument.HtmlExportOptions.ImageEmbedded = false;
    wordDocument.HtmlExportOptions.ImagesPath = outputDirectoryName + 'Demo/';

    // Export form fields as plain text
    wordDocument.HtmlExportOptions.IsTextInputFormFieldAsText = true;

    // Convert the document to HTML
    const outputFileName = 'ToHtmlExportOption-out.html';
    wordDocument.SaveToFile({ fileName: outputFileName, fileFormat: docModule.FileFormat.Html });

    // Release resources
    wordDocument.Dispose();

    // Read the output directory recursively and write each level of files into the zip
    const zip = new JSZip();
    const addFilesToZip = async (folderPath, zipFolder) => {
      let items = await window.dotnetRuntime.Module.FS.readdir(folderPath);
      items = items.filter((item) => item !== '.' && item !== '..');
      for (const item of items) {
        const itemPath = `${folderPath}/${item}`;
        try {
          const fileData = await window.dotnetRuntime.Module.FS.readFile(itemPath);
          zipFolder.file(item, fileData);
        } catch (error) {
          const zipSubFolder = zipFolder.folder(item);
          await addFilesToZip(itemPath, zipSubFolder);
        }
      }
    };

    // Package the HTML file together with the resource directory
    zip.file(outputFileName, window.dotnetRuntime.Module.FS.readFile(outputFileName));
    await addFilesToZip(outputDirectoryName, zip);
    const zipBlob = await zip.generateAsync({ type: 'blob' });
    const url = URL.createObjectURL(zipBlob);

    // Trigger download
    const a = window.document.createElement('a');
    a.href = url;
    a.download = 'ToHTMLFolder.zip';
    a.click();
    URL.revokeObjectURL(url);
  };

  return (
    <div style={{ textAlign: 'center', height: '300px' }}>
      <h1>Convert Word To HTML With Export Options</h1>
      <button onClick={wordToHtmlWithOptions}>
        Generate
      </button>
    </div>
  );
}

export default App;

Arquivos HTML, CSS e de imagem gerados após configurar as opções de exportação

Um detalhe que vale a pena observar: o Spire.Doc não coloca as imagens diretamente no diretório especificado por ImagesPath. Em vez disso, ele cria uma subpasta external_images dentro desse diretório para armazenar os arquivos de imagem. A estrutura resultante se parece com Demo/external_images/*.png, e é por isso que addFilesToZip percorre a árvore de diretórios recursivamente em vez de ler uma lista simples de arquivos.

Incorporado vs. Externo: Escolhendo a Estratégia Certa

Ambos os modos de exportação produzem HTML válido a partir do mesmo documento do Word, mas atendem a necessidades de publicação diferentes. A tabela abaixo resume as principais diferenças para ajudá-lo a decidir qual abordagem se encaixa no seu fluxo de trabalho.

Guia de decisão rápida:

• Escolha o modo incorporado quando precisar de um artefato único e portátil — por exemplo, gerar uma pré-visualização que o usuário baixa e abre offline, ou anexar um documento convertido a um e-mail.
• Escolha o modo externo quando estiver publicando em uma plataforma web onde vários documentos compartilham o mesmo sistema de design, onde você deseja armazenar imagens em cache ou carregá-las sob demanda, ou onde o tamanho do arquivo HTML importa para o desempenho.

Perguntas Frequentes

As fontes no HTML exportado não correspondem ao documento original

Se as fontes no HTML convertido parecerem diferentes do arquivo Word de origem, a causa é quase sempre a ausência de dados de fonte no sistema de arquivos virtual do WASM. O Spire.Doc depende de fontes carregadas no VFS para realizar cálculos precisos de layout e resolução de nomes de fontes durante a conversão. Quando uma fonte necessária não está disponível, o mecanismo substitui por uma fonte alternativa, e as declarações font-family no CSS de saída não corresponderão ao que o documento original especifica. Para documentos que usam fontes de símbolos, como Wingdings, os caracteres afetados também podem ser renderizados como texto ilegível.

A correção é simples: pré-carregue os arquivos de fonte necessários no VFS via FetchFileToVFS antes de executar a conversão. Para documentos que contêm texto em chinês, japonês ou coreano, use uma fonte com ampla cobertura Unicode, como ARIALUNI.TTF:

await window.spire.FetchFileToVFS(
  'ARIALUNI.TTF', '/Library/Fonts/', '/'
);

O HTML exportado perde seus estilos e imagens ao ser aberto

Quando você usa o modo externo (CssStyleSheetType.External com ImageEmbedded = false), os arquivos CSS e de imagem são gravados em locais separados, e o HTML os referencia por meio de caminhos relativos. Se você baixar apenas o arquivo HTML sem seus recursos acompanhantes, o navegador não conseguirá resolver esses caminhos e a página será exibida como texto simples sem estilo e com imagens quebradas.

Para evitar isso, sempre empacote o HTML junto com seu diretório de recursos — a abordagem addFilesToZip mostrada na seção de opções de exportação faz isso agrupando tudo em um único download zip. Como alternativa, se você não precisa realmente de arquivos de recursos separados, mude para o modo incorporado para que tudo permaneça em um único arquivo HTML autocontido:

wordDocument.HtmlExportOptions.CssStyleSheetType = docModule.CssStyleSheetType.Internal;
wordDocument.HtmlExportOptions.ImageEmbedded = true;

Veja Também

• Integrando o Spire.Doc for JavaScript em um Projeto React
• Converter Word para PDF com Spire.Doc for JavaScript
• Converter Word para Imagem com Spire.Doc for JavaScript
• Visão Geral do Spire.Doc for JavaScript

Word 문서는 종종 웹 콘텐츠의 출발점입니다 — 기사, 제품 사양, 규정 준수 문서 등은 결국 웹사이트에 있어야 합니다. 백엔드 변환 서비스 없이 .docx에서 깔끔한 HTML로 변환하는 것이 과제입니다. Spire.Doc for JavaScript는 WebAssembly에서 전체 문서 처리 엔진을 실행하고, 가상 파일 시스템(VFS)을 통해 Word 파일을 읽고, 로컬에서 변환을 수행하며, 결과 HTML을 다운로드할 수 있게 함으로써 이를 가능하게 합니다 — 모두 클라이언트 측에서 서버 왕복 없이 이루어집니다.

워크플로우를 지배하는 두 가지 내보내기 전략이 있으며, 이 중에서 선택하는 것이 실제 결정입니다:

• 내장 모드는 CSS와 이미지를 HTML 파일에 직접 묶어 어디서나 열리는 단일 자체 포함 문서를 생성합니다.
• 외부 모드는 CSS와 이미지를 별도 파일에 기록하여 더 작은 HTML, 재사용 가능한 스타일시트, 독립적으로 관리할 수 있는 개별 이미지 자산을 제공합니다.

이 문서에서는 React 프로젝트에서 두 접근 방식을 모두 살펴보고 나란히 비교합니다. 설정에 대해서는 React 프로젝트에 Spire.Doc for JavaScript 통합을 참조하세요. 아래 예제는 Spire.Doc이 설치되어 있고 WebAssembly 모듈이 초기화되었다고 가정합니다.

기본 변환: 모든 것을 하나의 파일에 포함

Word 문서를 웹 페이지로 게시하는 가장 간단한 방법은 마크업, 스타일, 이미지 등 모든 것을 하나의 자체 포함 패키지로 포함하는 단일 HTML 파일을 생성하는 것입니다. 이는 파일 누락 참조나 깨진 링크 없이 어디서든 올바르게 렌더링되는 휴대용 아티팩트가 필요할 때 이상적입니다.

변환은 세 단계를 따릅니다. 먼저, FetchFileToVFS를 사용하여 글꼴 파일과 원본 Word 문서를 WASM 가상 파일 시스템에 로드합니다. 둘째, Document 인스턴스를 생성하고, 파일을 로드하고, HtmlExportOptions를 구성하여 CSS와 이미지를 모두 포함하도록 설정하고, SaveToFile을 호출하여 HTML을 작성합니다. 셋째, 생성된 파일을 VFS에서 다시 읽어 Blob으로 감싸고 브라우저 다운로드를 트리거합니다.

function App() {
  const wordToHtml = async () => {
    // Get the Spire.Doc WASM module
    const docModule = window.wasmModule?.spiredoc;

    // Check if the module is ready
    if (!docModule) {
      alert('Spire.Doc is not ready yet');
      return;
    }

    // Load fonts and the Word file into VFS
    await window.spire.FetchFileToVFS('ARIALUNI.TTF', '/Library/Fonts/', `${process.env.PUBLIC_URL}/static/font/`);
    const inputFileName = 'ToHtml.docx';
    await window.spire.FetchFileToVFS(inputFileName, '', `${process.env.PUBLIC_URL}/static/data/`);

    // Load the Word document
    const wordDocument = new docModule.Document();
    wordDocument.LoadFromFile(inputFileName);

    // Embed the CSS styles into the HTML and embed images as Base64
    wordDocument.HtmlExportOptions.CssStyleSheetType = docModule.CssStyleSheetType.Internal;
    wordDocument.HtmlExportOptions.ImageEmbedded = true;

    // Convert the document to HTML
    const outputFileName = 'ToHtml-result.html';
    wordDocument.SaveToFile({ fileName: outputFileName, fileFormat: docModule.FileFormat.Html });

    // Read the converted file from VFS and trigger download
    const fileArray = window.dotnetRuntime.Module.FS.readFile(outputFileName);
    const blob = new Blob([fileArray], { type: 'text/html;charset=utf-8' });
    const url = URL.createObjectURL(blob);
    const a = window.document.createElement('a');
    a.href = url;
    a.download = outputFileName;
    a.click();
    URL.revokeObjectURL(url);

    // Release resources
    wordDocument.Dispose();
  };

  return (
    <div style={{ textAlign: 'center', height: '300px' }}>
      <h1>Convert Word To HTML</h1>
      <button onClick={wordToHtml}>
        Generate
      </button>
    </div>
  );
}

export default App;

SaveToFile을 통해 Word 문서에서 생성된 HTML 페이지

내보내기 옵션: CSS와 이미지 분리

모든 것을 하나의 파일에 포함하는 것은 편리하지만 장단점이 있습니다. 이미지가 많은 큰 문서는 매우 큰 HTML 파일을 생성하며, 동일한 스타일을 공유하는 모든 페이지는 자체 CSS 복사본을 중복으로 포함합니다. 스타일을 중앙에서 유지 관리하거나, 여러 페이지에서 이미지 자산을 재사용하거나, 초기 렌더링 속도를 위해 HTML 페이로드를 작게 유지하려면 CSS와 이미지를 별도 파일로 내보내야 합니다.

HtmlExportOptions는 각 리소스 유형이 작성되는 방식을 세밀하게 제어할 수 있습니다. CSS를 명명된 스타일시트 파일로 보내고, 이미지를 전용 디렉터리로 보내고, 양식 필드가 직렬화되는 방식까지 제어할 수 있습니다. 결과는 더 이상 단일 파일이 아니라 HTML, 스타일시트 및 이미지 파일을 포함하는 디렉터리 구조입니다.

워크플로우는 내장 접근 방식을 따르며 두 가지가 추가됩니다. 변환 전에 VFS에 출력 디렉터리를 생성하고 CssStyleSheetFileName 및 ImagesPath를 사용하여 각 리소스 유형을 어디에 작성할지 Spire.Doc에 알립니다. 변환 후에는 전체 출력 디렉터리를 재귀적으로 읽고 JSZip을 사용하여 모든 것을 zip 아카이브로 패키징한 다음 한 번의 작업으로 다운로드합니다.

import JSZip from 'jszip';

function App() {
  const wordToHtmlWithOptions = async () => {
    // Get the Spire.Doc WASM module
    const docModule = window.wasmModule?.spiredoc;

    // Check if the module is ready
    if (!docModule) {
      alert('Spire.Doc is not ready yet');
      return;
    }

    // Load fonts and the Word file into VFS
    await window.spire.FetchFileToVFS('ARIALUNI.TTF', '/Library/Fonts/', `${process.env.PUBLIC_URL}/static/font/`);
    const inputFileName = 'ToHtml.docx';
    await window.spire.FetchFileToVFS(inputFileName, '', `${process.env.PUBLIC_URL}/static/data/`);

    // Create the output directory in VFS
    const outputDirectoryName = 'ToHTMLFolder/';
    window.dotnetRuntime.Module.FS.mkdirTree(outputDirectoryName);

    // Load the Word document
    const wordDocument = new docModule.Document();
    wordDocument.LoadFromFile(inputFileName);

    // Export the CSS styles to a separate file
    wordDocument.HtmlExportOptions.CssStyleSheetFileName = outputDirectoryName + 'sample.css';
    wordDocument.HtmlExportOptions.CssStyleSheetType = docModule.CssStyleSheetType.External;

    // Export images to a separate directory
    wordDocument.HtmlExportOptions.ImageEmbedded = false;
    wordDocument.HtmlExportOptions.ImagesPath = outputDirectoryName + 'Demo/';

    // Export form fields as plain text
    wordDocument.HtmlExportOptions.IsTextInputFormFieldAsText = true;

    // Convert the document to HTML
    const outputFileName = 'ToHtmlExportOption-out.html';
    wordDocument.SaveToFile({ fileName: outputFileName, fileFormat: docModule.FileFormat.Html });

    // Release resources
    wordDocument.Dispose();

    // Read the output directory recursively and write each level of files into the zip
    const zip = new JSZip();
    const addFilesToZip = async (folderPath, zipFolder) => {
      let items = await window.dotnetRuntime.Module.FS.readdir(folderPath);
      items = items.filter((item) => item !== '.' && item !== '..');
      for (const item of items) {
        const itemPath = `${folderPath}/${item}`;
        try {
          const fileData = await window.dotnetRuntime.Module.FS.readFile(itemPath);
          zipFolder.file(item, fileData);
        } catch (error) {
          const zipSubFolder = zipFolder.folder(item);
          await addFilesToZip(itemPath, zipSubFolder);
        }
      }
    };

    // Package the HTML file together with the resource directory
    zip.file(outputFileName, window.dotnetRuntime.Module.FS.readFile(outputFileName));
    await addFilesToZip(outputDirectoryName, zip);
    const zipBlob = await zip.generateAsync({ type: 'blob' });
    const url = URL.createObjectURL(zipBlob);

    // Trigger download
    const a = window.document.createElement('a');
    a.href = url;
    a.download = 'ToHTMLFolder.zip';
    a.click();
    URL.revokeObjectURL(url);
  };

  return (
    <div style={{ textAlign: 'center', height: '300px' }}>
      <h1>Convert Word To HTML With Export Options</h1>
      <button onClick={wordToHtmlWithOptions}>
        Generate
      </button>
    </div>
  );
}

export default App;

내보내기 옵션을 구성한 후 생성된 HTML, CSS 및 이미지 파일

주목할 만한 세부 사항: Spire.Doc은 ImagesPath로 지정된 디렉터리에 이미지를 직접 배치하지 않습니다. 대신 해당 디렉터리 안에 external_images 하위 폴더를 만들어 이미지 파일을 보관합니다. 결과 구조는 Demo/external_images/*.png와 같이 되며, 이것이 addFilesToZip이 단순 파일 목록을 읽는 대신 디렉터리 트리를 재귀적으로 순회하는 이유입니다.

내장형 vs. 외부형: 올바른 전략 선택

두 내보내기 모드 모두 동일한 Word 문서에서 유효한 HTML을 생성하지만 서로 다른 게시 요구 사항을 충족합니다. 아래 표는 주요 차이점을 요약하여 워크플로우에 맞는 접근 방식을 결정하는 데 도움을 줍니다.

빠른 결정 가이드:

• 단일하고 휴대 가능한 아티팩트가 필요할 때 내장형을 선택하세요 — 예를 들어 사용자가 다운로드하여 오프라인에서 열 수 있는 미리보기를 생성하거나 변환된 문서를 이메일에 첨부하는 경우입니다.
• 여러 문서가 동일한 디자인 시스템을 공유하는 웹 플랫폼에 게시하거나, 이미지를 캐시 또는 지연 로드하려는 경우, 또는 HTML 파일 크기가 성능에 중요한 경우 외부형을 선택하세요.

자주 묻는 질문

내보낸 HTML의 글꼴이 원본 문서와 일치하지 않음

변환된 HTML의 글꼴이 원본 Word 파일과 다르게 보이는 경우, 원인은 거의 항상 WASM 가상 파일 시스템에 글꼴 데이터가 없기 때문입니다. Spire.Doc은 변환 중 정확한 레이아웃 계산과 글꼴 이름 확인을 수행하기 위해 VFS에 로드된 글꼴에 의존합니다. 필요한 글꼴을 사용할 수 없으면 엔진이 대체 글꼴을 사용하며, 출력 CSS의 font-family 선언이 원본 문서에서 지정한 것과 일치하지 않습니다. Wingdings와 같은 기호 글꼴을 사용하는 문서의 경우 영향을 받는 문자가 깨진 텍스트로 렌더링될 수도 있습니다.

해결 방법은 간단합니다: 변환을 실행하기 전에 FetchFileToVFS를 통해 필요한 글꼴 파일을 VFS에 미리 로드하세요. 중국어, 일본어 또는 한국어 텍스트가 포함된 문서의 경우 ARIALUNI.TTF와 같이 유니코드 범위가 넓은 글꼴을 사용하세요:

await window.spire.FetchFileToVFS(
  'ARIALUNI.TTF', '/Library/Fonts/', '/'
);

열 때 내보낸 HTML의 스타일과 이미지가 손실됨

외부 모드(CssStyleSheetType.External 및 ImageEmbedded = false)를 사용하면 CSS 및 이미지 파일이 별도 위치에 작성되고 HTML은 상대 경로를 통해 이를 참조합니다. 해당 리소스 없이 HTML 파일만 다운로드하면 브라우저가 이러한 경로를 확인할 수 없어 페이지가 스타일이 지정되지 않은 일반 텍스트와 깨진 이미지로 대체됩니다.

이를 방지하려면 항상 HTML을 해당 리소스 디렉터리와 함께 패키징하세요 — 내보내기 옵션 섹션에 표시된 addFilesToZip 접근 방식은 모든 것을 단일 zip 다운로드로 묶어 이를 처리합니다. 또는 별도의 리소스 파일이 실제로 필요하지 않은 경우 내장 모드로 전환하여 모든 것이 하나의 자체 포함 HTML 파일에 유지되도록 하세요:

wordDocument.HtmlExportOptions.CssStyleSheetType = docModule.CssStyleSheetType.Internal;
wordDocument.HtmlExportOptions.ImageEmbedded = true;

참고 항목

• React 프로젝트에 Spire.Doc for JavaScript 통합
• Spire.Doc for JavaScript로 Word를 PDF로 변환
• Spire.Doc for JavaScript로 Word를 이미지로 변환
• Spire.Doc for JavaScript 개요

I documenti Word sono spesso il punto di partenza per i contenuti web: articoli, specifiche di prodotto e documenti di conformità devono prima o poi finire su un sito web. Passare da .docx a HTML pulito senza un servizio di conversione lato backend è la vera sfida. Spire.Doc for JavaScript lo rende possibile eseguendo un motore completo di elaborazione dei documenti su WebAssembly, leggendo il file Word attraverso un file system virtuale (VFS), eseguendo la conversione localmente e permettendoti di scaricare l'HTML risultante — tutto lato client, senza alcun passaggio al server.

Due strategie di esportazione dominano il flusso di lavoro, e scegliere tra esse è la vera decisione:

• Modalità incorporata: raggruppa CSS e immagini direttamente nel file HTML, producendo un unico documento autonomo che si apre ovunque.
• Modalità esterna: scrive CSS e immagini in file separati, offrendoti un HTML più leggero, fogli di stile riutilizzabili e singoli asset immagine che puoi gestire in modo indipendente.

Questo articolo illustra entrambi gli approcci in un progetto React e li confronta fianco a fianco. Per la configurazione, fai riferimento a Integrare Spire.Doc for JavaScript in un progetto React. Gli esempi seguenti presuppongono che Spire.Doc sia installato e che il modulo WebAssembly sia inizializzato.

Conversione di base: incorporare tutto in un unico file

Il modo più semplice per pubblicare un documento Word come pagina web è produrre un unico file HTML che contenga tutto — markup, stili e immagini — in un unico pacchetto autonomo. Questo è l'ideale quando hai bisogno di un artefatto portatile che venga visualizzato correttamente ovunque venga aperto, senza riferimenti a file mancanti o link interrotti.

La conversione segue tre passaggi. Innanzitutto, carica il file dei font e il documento Word di origine nel file system virtuale WASM usando FetchFileToVFS. In secondo luogo, crea un'istanza Document, carica il file, configura HtmlExportOptions per incorporare sia il CSS sia le immagini e chiama SaveToFile per scrivere l'HTML. In terzo luogo, rileggi il file generato dal VFS, avvolgilo in un Blob e attiva il download dal browser.

function App() {
  const wordToHtml = async () => {
    // Get the Spire.Doc WASM module
    const docModule = window.wasmModule?.spiredoc;

    // Check if the module is ready
    if (!docModule) {
      alert('Spire.Doc is not ready yet');
      return;
    }

    // Load fonts and the Word file into VFS
    await window.spire.FetchFileToVFS('ARIALUNI.TTF', '/Library/Fonts/', `${process.env.PUBLIC_URL}/static/font/`);
    const inputFileName = 'ToHtml.docx';
    await window.spire.FetchFileToVFS(inputFileName, '', `${process.env.PUBLIC_URL}/static/data/`);

    // Load the Word document
    const wordDocument = new docModule.Document();
    wordDocument.LoadFromFile(inputFileName);

    // Embed the CSS styles into the HTML and embed images as Base64
    wordDocument.HtmlExportOptions.CssStyleSheetType = docModule.CssStyleSheetType.Internal;
    wordDocument.HtmlExportOptions.ImageEmbedded = true;

    // Convert the document to HTML
    const outputFileName = 'ToHtml-result.html';
    wordDocument.SaveToFile({ fileName: outputFileName, fileFormat: docModule.FileFormat.Html });

    // Read the converted file from VFS and trigger download
    const fileArray = window.dotnetRuntime.Module.FS.readFile(outputFileName);
    const blob = new Blob([fileArray], { type: 'text/html;charset=utf-8' });
    const url = URL.createObjectURL(blob);
    const a = window.document.createElement('a');
    a.href = url;
    a.download = outputFileName;
    a.click();
    URL.revokeObjectURL(url);

    // Release resources
    wordDocument.Dispose();
  };

  return (
    <div style={{ textAlign: 'center', height: '300px' }}>
      <h1>Convert Word To HTML</h1>
      <button onClick={wordToHtml}>
        Generate
      </button>
    </div>
  );
}

export default App;

Pagina HTML generata da un documento Word tramite SaveToFile

Opzioni di esportazione: CSS e immagini separati

Incorporare tutto in un unico file è comodo, ma presenta dei compromessi. Un documento di grandi dimensioni con molte immagini produce un file HTML molto pesante, e ogni pagina che condivide lo stesso stile porta con sé una copia duplicata del CSS. Quando vuoi mantenere gli stili in modo centralizzato, riutilizzare gli asset immagine tra più pagine o mantenere il payload HTML ridotto per un rendering iniziale più rapido, è invece preferibile esportare CSS e immagini come file separati.

HtmlExportOptions ti offre un controllo granulare su come viene scritto ciascun tipo di risorsa. Puoi indirizzare il CSS verso un file di foglio di stile denominato, inviare le immagini in una directory dedicata e persino controllare come vengono serializzati i campi modulo. Il risultato non è più un singolo file ma una struttura di directory contenente l'HTML, il foglio di stile e i file immagine.

Il flusso di lavoro rispecchia l'approccio incorporato, con due aggiunte. Prima della conversione, crea una directory di output nel VFS e usa CssStyleSheetFileName e ImagesPath per indicare a Spire.Doc dove scrivere ciascun tipo di risorsa. Dopo la conversione, leggi ricorsivamente l'intera directory di output, impacchetta tutto in un archivio zip usando JSZip e scaricalo con un'unica operazione.

import JSZip from 'jszip';

function App() {
  const wordToHtmlWithOptions = async () => {
    // Get the Spire.Doc WASM module
    const docModule = window.wasmModule?.spiredoc;

    // Check if the module is ready
    if (!docModule) {
      alert('Spire.Doc is not ready yet');
      return;
    }

    // Load fonts and the Word file into VFS
    await window.spire.FetchFileToVFS('ARIALUNI.TTF', '/Library/Fonts/', `${process.env.PUBLIC_URL}/static/font/`);
    const inputFileName = 'ToHtml.docx';
    await window.spire.FetchFileToVFS(inputFileName, '', `${process.env.PUBLIC_URL}/static/data/`);

    // Create the output directory in VFS
    const outputDirectoryName = 'ToHTMLFolder/';
    window.dotnetRuntime.Module.FS.mkdirTree(outputDirectoryName);

    // Load the Word document
    const wordDocument = new docModule.Document();
    wordDocument.LoadFromFile(inputFileName);

    // Export the CSS styles to a separate file
    wordDocument.HtmlExportOptions.CssStyleSheetFileName = outputDirectoryName + 'sample.css';
    wordDocument.HtmlExportOptions.CssStyleSheetType = docModule.CssStyleSheetType.External;

    // Export images to a separate directory
    wordDocument.HtmlExportOptions.ImageEmbedded = false;
    wordDocument.HtmlExportOptions.ImagesPath = outputDirectoryName + 'Demo/';

    // Export form fields as plain text
    wordDocument.HtmlExportOptions.IsTextInputFormFieldAsText = true;

    // Convert the document to HTML
    const outputFileName = 'ToHtmlExportOption-out.html';
    wordDocument.SaveToFile({ fileName: outputFileName, fileFormat: docModule.FileFormat.Html });

    // Release resources
    wordDocument.Dispose();

    // Read the output directory recursively and write each level of files into the zip
    const zip = new JSZip();
    const addFilesToZip = async (folderPath, zipFolder) => {
      let items = await window.dotnetRuntime.Module.FS.readdir(folderPath);
      items = items.filter((item) => item !== '.' && item !== '..');
      for (const item of items) {
        const itemPath = `${folderPath}/${item}`;
        try {
          const fileData = await window.dotnetRuntime.Module.FS.readFile(itemPath);
          zipFolder.file(item, fileData);
        } catch (error) {
          const zipSubFolder = zipFolder.folder(item);
          await addFilesToZip(itemPath, zipSubFolder);
        }
      }
    };

    // Package the HTML file together with the resource directory
    zip.file(outputFileName, window.dotnetRuntime.Module.FS.readFile(outputFileName));
    await addFilesToZip(outputDirectoryName, zip);
    const zipBlob = await zip.generateAsync({ type: 'blob' });
    const url = URL.createObjectURL(zipBlob);

    // Trigger download
    const a = window.document.createElement('a');
    a.href = url;
    a.download = 'ToHTMLFolder.zip';
    a.click();
    URL.revokeObjectURL(url);
  };

  return (
    <div style={{ textAlign: 'center', height: '300px' }}>
      <h1>Convert Word To HTML With Export Options</h1>
      <button onClick={wordToHtmlWithOptions}>
        Generate
      </button>
    </div>
  );
}

export default App;

File HTML, CSS e immagini generati dopo la configurazione delle opzioni di esportazione

Un dettaglio da notare: Spire.Doc non inserisce le immagini direttamente nella directory specificata da ImagesPath. Crea invece una sottocartella external_images all'interno di quella directory per contenere i file immagine. La struttura risultante è simile a Demo/external_images/*.png, ed è per questo che addFilesToZip percorre l'albero delle directory in modo ricorsivo anziché leggere un elenco piatto di file.

Incorporato vs. esterno: scegliere la strategia giusta

Entrambe le modalità di esportazione producono HTML valido dallo stesso documento Word, ma rispondono a diverse esigenze di pubblicazione. La tabella seguente riassume le differenze principali per aiutarti a decidere quale approccio si adatta al tuo flusso di lavoro.

Guida rapida alla scelta:

• Scegli la modalità incorporata quando hai bisogno di un unico artefatto portatile — ad esempio, per generare un'anteprima che l'utente scarica e apre offline, o per allegare un documento convertito a un'email.
• Scegli la modalità esterna quando pubblichi su una piattaforma web in cui più documenti condividono lo stesso design system, quando vuoi memorizzare le immagini nella cache o caricarle in modo lazy, o quando la dimensione del file HTML influisce sulle prestazioni.

Domande frequenti

I font nell'HTML esportato non corrispondono al documento originale

Se i font nell'HTML convertito appaiono diversi dal file Word di origine, la causa è quasi sempre la mancanza dei dati dei font nel file system virtuale WASM. Spire.Doc si affida ai font caricati nel VFS per eseguire calcoli accurati del layout e la risoluzione dei nomi dei font durante la conversione. Quando un font richiesto non è disponibile, il motore sostituisce un font di fallback e le dichiarazioni font-family nel CSS di output non corrisponderanno a quelle specificate nel documento originale. Per i documenti che utilizzano font simbolici come Wingdings, i caratteri interessati possono anche essere visualizzati come testo illeggibile.

La soluzione è semplice: precarica i file dei font necessari nel VFS tramite FetchFileToVFS prima di eseguire la conversione. Per i documenti contenenti testo cinese, giapponese o coreano, usa un font con ampia copertura Unicode come ARIALUNI.TTF:

await window.spire.FetchFileToVFS(
  'ARIALUNI.TTF', '/Library/Fonts/', '/'
);

L'HTML esportato perde gli stili e le immagini quando viene aperto

Quando usi la modalità esterna (CssStyleSheetType.External con ImageEmbedded = false), i file CSS e immagine vengono scritti in posizioni separate e l'HTML li referenzia tramite percorsi relativi. Se scarichi solo il file HTML senza le risorse che lo accompagnano, il browser non può risolvere quei percorsi e la pagina ricade su testo semplice senza stile con immagini mancanti.

Per evitarlo, impacchetta sempre l'HTML insieme alla sua directory di risorse — l'approccio addFilesToZip mostrato nella sezione delle opzioni di esportazione lo gestisce raggruppando tutto in un unico download zip. In alternativa, se in realtà non hai bisogno di file di risorse separati, passa alla modalità incorporata in modo che tutto rimanga in un unico file HTML autonomo:

wordDocument.HtmlExportOptions.CssStyleSheetType = docModule.CssStyleSheetType.Internal;
wordDocument.HtmlExportOptions.ImageEmbedded = true;

Vedi anche

• Integrare Spire.Doc for JavaScript in un progetto React
• Convertire Word in PDF con Spire.Doc for JavaScript
• Convertire Word in immagine con Spire.Doc for JavaScript
• Panoramica di Spire.Doc for JavaScript

Les documents Word sont souvent le point de départ du contenu web — articles, spécifications produit et documents de conformité doivent tous finir par vivre sur un site web. Passer d'un fichier .docx à un HTML propre sans service de conversion côté serveur, voilà le défi. Spire.Doc for JavaScript rend cela possible en exécutant un moteur complet de traitement de documents sur WebAssembly, en lisant le fichier Word via un système de fichiers virtuel (VFS), en effectuant la conversion localement et en vous permettant de télécharger le HTML obtenu — le tout côté client, sans aller-retour vers un serveur.

Deux stratégies d'exportation dominent le flux de travail, et c'est le choix entre elles qui constitue la véritable décision :

• Le mode intégré regroupe le CSS et les images directement dans le fichier HTML, produisant un document unique et autonome qui s'ouvre partout.
• Le mode externe écrit le CSS et les images dans des fichiers séparés, ce qui donne un HTML plus léger, des feuilles de style réutilisables et des ressources d'images individuelles que vous pouvez gérer indépendamment.

Cet article présente les deux approches dans un projet React et les compare côte à côte. Pour l'installation, reportez-vous à Intégrer Spire.Doc for JavaScript dans un projet React. Les exemples ci-dessous supposent que Spire.Doc est installé et que le module WebAssembly est initialisé.

Conversion de base : tout intégrer dans un seul fichier

La façon la plus simple de publier un document Word sous forme de page web consiste à produire un seul fichier HTML contenant tout — balisage, styles et images — dans un ensemble autonome. C'est idéal lorsque vous avez besoin d'un artefact portable qui s'affiche correctement où qu'il soit ouvert, sans références de fichiers manquants ni liens brisés.

La conversion se déroule en trois étapes. Premièrement, chargez le fichier de police et le document Word source dans le système de fichiers virtuel WASM à l'aide de FetchFileToVFS. Deuxièmement, créez une instance Document, chargez le fichier, configurez HtmlExportOptions pour intégrer à la fois le CSS et les images, puis appelez SaveToFile pour écrire le HTML. Troisièmement, relisez le fichier généré depuis le VFS, encapsulez-le dans un Blob et déclenchez un téléchargement dans le navigateur.

function App() {
  const wordToHtml = async () => {
    // Get the Spire.Doc WASM module
    const docModule = window.wasmModule?.spiredoc;

    // Check if the module is ready
    if (!docModule) {
      alert('Spire.Doc is not ready yet');
      return;
    }

    // Load fonts and the Word file into VFS
    await window.spire.FetchFileToVFS('ARIALUNI.TTF', '/Library/Fonts/', `${process.env.PUBLIC_URL}/static/font/`);
    const inputFileName = 'ToHtml.docx';
    await window.spire.FetchFileToVFS(inputFileName, '', `${process.env.PUBLIC_URL}/static/data/`);

    // Load the Word document
    const wordDocument = new docModule.Document();
    wordDocument.LoadFromFile(inputFileName);

    // Embed the CSS styles into the HTML and embed images as Base64
    wordDocument.HtmlExportOptions.CssStyleSheetType = docModule.CssStyleSheetType.Internal;
    wordDocument.HtmlExportOptions.ImageEmbedded = true;

    // Convert the document to HTML
    const outputFileName = 'ToHtml-result.html';
    wordDocument.SaveToFile({ fileName: outputFileName, fileFormat: docModule.FileFormat.Html });

    // Read the converted file from VFS and trigger download
    const fileArray = window.dotnetRuntime.Module.FS.readFile(outputFileName);
    const blob = new Blob([fileArray], { type: 'text/html;charset=utf-8' });
    const url = URL.createObjectURL(blob);
    const a = window.document.createElement('a');
    a.href = url;
    a.download = outputFileName;
    a.click();
    URL.revokeObjectURL(url);

    // Release resources
    wordDocument.Dispose();
  };

  return (
    <div style={{ textAlign: 'center', height: '300px' }}>
      <h1>Convert Word To HTML</h1>
      <button onClick={wordToHtml}>
        Generate
      </button>
    </div>
  );
}

export default App;

Page HTML générée à partir d'un document Word via SaveToFile

Options d'exportation : séparer le CSS et les images

Tout intégrer dans un seul fichier est pratique, mais cela présente des compromis. Un document volumineux contenant de nombreuses images produit un fichier HTML très lourd, et chaque page qui partage le même style transporte sa propre copie dupliquée du CSS. Lorsque vous souhaitez maintenir les styles de manière centralisée, réutiliser les ressources d'images entre les pages ou garder la charge utile HTML réduite pour un rendu initial plus rapide, vous devriez plutôt exporter le CSS et les images dans des fichiers séparés.

HtmlExportOptions vous offre un contrôle précis sur la manière dont chaque type de ressource est écrit. Vous pouvez diriger le CSS vers un fichier de feuille de style nommé, envoyer les images vers un répertoire dédié et même contrôler la façon dont les champs de formulaire sont sérialisés. Le résultat n'est plus un fichier unique mais une structure de répertoires contenant le HTML, la feuille de style et les fichiers d'images.

Le flux de travail reprend celui de l'approche intégrée, avec deux ajouts. Avant la conversion, créez un répertoire de sortie dans le VFS et utilisez CssStyleSheetFileName et ImagesPath pour indiquer à Spire.Doc où écrire chaque type de ressource. Après la conversion, lisez l'intégralité du répertoire de sortie de manière récursive, empaquetez le tout dans une archive zip à l'aide de JSZip, puis téléchargez-la en une seule opération.

import JSZip from 'jszip';

function App() {
  const wordToHtmlWithOptions = async () => {
    // Get the Spire.Doc WASM module
    const docModule = window.wasmModule?.spiredoc;

    // Check if the module is ready
    if (!docModule) {
      alert('Spire.Doc is not ready yet');
      return;
    }

    // Load fonts and the Word file into VFS
    await window.spire.FetchFileToVFS('ARIALUNI.TTF', '/Library/Fonts/', `${process.env.PUBLIC_URL}/static/font/`);
    const inputFileName = 'ToHtml.docx';
    await window.spire.FetchFileToVFS(inputFileName, '', `${process.env.PUBLIC_URL}/static/data/`);

    // Create the output directory in VFS
    const outputDirectoryName = 'ToHTMLFolder/';
    window.dotnetRuntime.Module.FS.mkdirTree(outputDirectoryName);

    // Load the Word document
    const wordDocument = new docModule.Document();
    wordDocument.LoadFromFile(inputFileName);

    // Export the CSS styles to a separate file
    wordDocument.HtmlExportOptions.CssStyleSheetFileName = outputDirectoryName + 'sample.css';
    wordDocument.HtmlExportOptions.CssStyleSheetType = docModule.CssStyleSheetType.External;

    // Export images to a separate directory
    wordDocument.HtmlExportOptions.ImageEmbedded = false;
    wordDocument.HtmlExportOptions.ImagesPath = outputDirectoryName + 'Demo/';

    // Export form fields as plain text
    wordDocument.HtmlExportOptions.IsTextInputFormFieldAsText = true;

    // Convert the document to HTML
    const outputFileName = 'ToHtmlExportOption-out.html';
    wordDocument.SaveToFile({ fileName: outputFileName, fileFormat: docModule.FileFormat.Html });

    // Release resources
    wordDocument.Dispose();

    // Read the output directory recursively and write each level of files into the zip
    const zip = new JSZip();
    const addFilesToZip = async (folderPath, zipFolder) => {
      let items = await window.dotnetRuntime.Module.FS.readdir(folderPath);
      items = items.filter((item) => item !== '.' && item !== '..');
      for (const item of items) {
        const itemPath = `${folderPath}/${item}`;
        try {
          const fileData = await window.dotnetRuntime.Module.FS.readFile(itemPath);
          zipFolder.file(item, fileData);
        } catch (error) {
          const zipSubFolder = zipFolder.folder(item);
          await addFilesToZip(itemPath, zipSubFolder);
        }
      }
    };

    // Package the HTML file together with the resource directory
    zip.file(outputFileName, window.dotnetRuntime.Module.FS.readFile(outputFileName));
    await addFilesToZip(outputDirectoryName, zip);
    const zipBlob = await zip.generateAsync({ type: 'blob' });
    const url = URL.createObjectURL(zipBlob);

    // Trigger download
    const a = window.document.createElement('a');
    a.href = url;
    a.download = 'ToHTMLFolder.zip';
    a.click();
    URL.revokeObjectURL(url);
  };

  return (
    <div style={{ textAlign: 'center', height: '300px' }}>
      <h1>Convert Word To HTML With Export Options</h1>
      <button onClick={wordToHtmlWithOptions}>
        Generate
      </button>
    </div>
  );
}

export default App;

Fichiers HTML, CSS et images générés après configuration des options d'exportation

Un détail mérite d'être signalé : Spire.Doc ne place pas les images directement dans le répertoire spécifié par ImagesPath. Il crée à la place un sous-dossier external_images dans ce répertoire pour y stocker les fichiers d'images. La structure obtenue ressemble à Demo/external_images/*.png, ce qui explique pourquoi addFilesToZip parcourt l'arborescence des répertoires de manière récursive plutôt que de lire une liste plate de fichiers.

Intégré ou externe : choisir la bonne stratégie

Les deux modes d'exportation produisent un HTML valide à partir du même document Word, mais ils répondent à des besoins de publication différents. Le tableau ci-dessous résume les principales différences pour vous aider à déterminer quelle approche convient à votre flux de travail.

Guide de décision rapide :

• Choisissez le mode intégré lorsque vous avez besoin d'un artefact unique et portable — par exemple, générer un aperçu qu'un utilisateur télécharge et ouvre hors ligne, ou joindre un document converti à un e-mail.
• Choisissez le mode externe lorsque vous publiez sur une plateforme web où plusieurs documents partagent le même système de design, où vous souhaitez mettre en cache ou charger à la demande les images, ou lorsque la taille du fichier HTML importe pour les performances.

FAQ

Les polices du HTML exporté ne correspondent pas au document d'origine

Si les polices de votre HTML converti semblent différentes de celles du fichier Word source, la cause est presque toujours l'absence de données de police dans le système de fichiers virtuel WASM. Spire.Doc s'appuie sur les polices chargées dans le VFS pour effectuer des calculs de mise en page précis et la résolution des noms de polices lors de la conversion. Lorsqu'une police requise n'est pas disponible, le moteur la remplace par une police de secours, et les déclarations font-family dans le CSS de sortie ne correspondront pas à ce que spécifie le document d'origine. Pour les documents qui utilisent des polices symboliques telles que Wingdings, les caractères concernés peuvent également s'afficher sous forme de texte illisible.

La solution est simple : préchargez les fichiers de polices nécessaires dans le VFS via FetchFileToVFS avant de lancer la conversion. Pour les documents contenant du texte chinois, japonais ou coréen, utilisez une police à large couverture Unicode telle qu'ARIALUNI.TTF :

await window.spire.FetchFileToVFS(
  'ARIALUNI.TTF', '/Library/Fonts/', '/'
);

Le HTML exporté perd ses styles et ses images à l'ouverture

Lorsque vous utilisez le mode externe (CssStyleSheetType.External avec ImageEmbedded = false), les fichiers CSS et d'images sont écrits à des emplacements séparés, et le HTML y fait référence via des chemins relatifs. Si vous ne téléchargez que le fichier HTML sans les ressources qui l'accompagnent, le navigateur ne peut pas résoudre ces chemins et la page retombe sur du texte brut sans style, avec des images brisées.

Pour éviter cela, empaquetez toujours le HTML avec son répertoire de ressources — l'approche addFilesToZip présentée dans la section sur les options d'exportation s'en charge en regroupant le tout dans un seul téléchargement zip. Sinon, si vous n'avez pas réellement besoin de fichiers de ressources séparés, passez en mode intégré pour que tout reste dans un seul fichier HTML autonome :

wordDocument.HtmlExportOptions.CssStyleSheetType = docModule.CssStyleSheetType.Internal;
wordDocument.HtmlExportOptions.ImageEmbedded = true;

Voir aussi

• Intégrer Spire.Doc for JavaScript dans un projet React
• Convertir Word en PDF avec Spire.Doc for JavaScript
• Convertir Word en image avec Spire.Doc for JavaScript
• Présentation de Spire.Doc for JavaScript

Los documentos de Word suelen ser el punto de partida para el contenido web: artículos, especificaciones de productos y documentos de cumplimiento, todo ello necesita eventualmente estar en un sitio web. Pasar de .docx a HTML limpio sin un servicio de conversión de backend es el desafío. Spire.Doc for JavaScript lo hace posible ejecutando un motor completo de procesamiento de documentos sobre WebAssembly, leyendo el archivo de Word a través de un sistema de archivos virtual (VFS), realizando la conversión localmente y permitiéndote descargar el HTML resultante, todo del lado del cliente, sin ida y vuelta al servidor.

Dos estrategias de exportación dominan el flujo de trabajo, y elegir entre ellas es la verdadera decisión:

• Modo integrado empaqueta CSS e imágenes directamente en el archivo HTML, produciendo un único documento autocontenido que se abre en cualquier lugar.
• Modo externo escribe CSS e imágenes en archivos separados, lo que te ofrece un HTML más pequeño, hojas de estilo reutilizables y recursos de imagen individuales que puedes gestionar de forma independiente.

Este artículo recorre ambos enfoques en un proyecto de React y los compara lado a lado. Para la configuración, consulta Integrar Spire.Doc for JavaScript en un proyecto de React. Los ejemplos a continuación asumen que Spire.Doc está instalado y que el módulo WebAssembly está inicializado.

Conversión básica: incrustar todo en un solo archivo

La forma más sencilla de publicar un documento de Word como página web es producir un único archivo HTML que contenga todo (marcado, estilos e imágenes) en un paquete autocontenido. Esto es ideal cuando necesitas un artefacto portátil que se represente correctamente sin importar dónde se abra, sin referencias a archivos faltantes ni enlaces rotos.

La conversión sigue tres pasos. Primero, carga el archivo de fuente y el documento de Word de origen en el sistema de archivos virtual de WASM usando FetchFileToVFS. Segundo, crea una instancia de Document, carga el archivo, configura HtmlExportOptions para incrustar tanto CSS como imágenes, y llama a SaveToFile para escribir el HTML. Tercero, lee el archivo generado desde VFS, envuélvelo en un Blob y activa una descarga del navegador.

function App() {
  const wordToHtml = async () => {
    // Get the Spire.Doc WASM module
    const docModule = window.wasmModule?.spiredoc;

    // Check if the module is ready
    if (!docModule) {
      alert('Spire.Doc is not ready yet');
      return;
    }

    // Load fonts and the Word file into VFS
    await window.spire.FetchFileToVFS('ARIALUNI.TTF', '/Library/Fonts/', `${process.env.PUBLIC_URL}/static/font/`);
    const inputFileName = 'ToHtml.docx';
    await window.spire.FetchFileToVFS(inputFileName, '', `${process.env.PUBLIC_URL}/static/data/`);

    // Load the Word document
    const wordDocument = new docModule.Document();
    wordDocument.LoadFromFile(inputFileName);

    // Embed the CSS styles into the HTML and embed images as Base64
    wordDocument.HtmlExportOptions.CssStyleSheetType = docModule.CssStyleSheetType.Internal;
    wordDocument.HtmlExportOptions.ImageEmbedded = true;

    // Convert the document to HTML
    const outputFileName = 'ToHtml-result.html';
    wordDocument.SaveToFile({ fileName: outputFileName, fileFormat: docModule.FileFormat.Html });

    // Read the converted file from VFS and trigger download
    const fileArray = window.dotnetRuntime.Module.FS.readFile(outputFileName);
    const blob = new Blob([fileArray], { type: 'text/html;charset=utf-8' });
    const url = URL.createObjectURL(blob);
    const a = window.document.createElement('a');
    a.href = url;
    a.download = outputFileName;
    a.click();
    URL.revokeObjectURL(url);

    // Release resources
    wordDocument.Dispose();
  };

  return (
    <div style={{ textAlign: 'center', height: '300px' }}>
      <h1>Convert Word To HTML</h1>
      <button onClick={wordToHtml}>
        Generate
      </button>
    </div>
  );
}

export default App;

Página HTML generada a partir de un documento de Word mediante SaveToFile

Opciones de exportación: CSS e imágenes separados

Incrustar todo en un solo archivo es cómodo, pero tiene ventajas y desventajas. Un documento grande con muchas imágenes produce un archivo HTML muy grande, y cada página que comparte el mismo estilo lleva su propia copia duplicada del CSS. Cuando quieres mantener los estilos de forma centralizada, reutilizar recursos de imagen en varias páginas o mantener pequeño el contenido HTML para una representación inicial más rápida, deberías exportar CSS e imágenes como archivos separados en su lugar.

HtmlExportOptions te ofrece un control detallado sobre cómo se escribe cada tipo de recurso. Puedes dirigir el CSS a un archivo de hoja de estilos con nombre, enviar las imágenes a un directorio dedicado e incluso controlar cómo se serializan los campos de formulario. El resultado ya no es un solo archivo, sino una estructura de directorios que contiene el HTML, la hoja de estilos y los archivos de imagen.

El flujo de trabajo es similar al del enfoque integrado, con dos añadidos. Antes de la conversión, crea un directorio de salida en VFS y usa CssStyleSheetFileName y ImagesPath para indicarle a Spire.Doc dónde escribir cada tipo de recurso. Después de la conversión, lee todo el directorio de salida de forma recursiva, empaqueta todo en un archivo zip usando JSZip y descárgalo en una sola operación.

import JSZip from 'jszip';

function App() {
  const wordToHtmlWithOptions = async () => {
    // Get the Spire.Doc WASM module
    const docModule = window.wasmModule?.spiredoc;

    // Check if the module is ready
    if (!docModule) {
      alert('Spire.Doc is not ready yet');
      return;
    }

    // Load fonts and the Word file into VFS
    await window.spire.FetchFileToVFS('ARIALUNI.TTF', '/Library/Fonts/', `${process.env.PUBLIC_URL}/static/font/`);
    const inputFileName = 'ToHtml.docx';
    await window.spire.FetchFileToVFS(inputFileName, '', `${process.env.PUBLIC_URL}/static/data/`);

    // Create the output directory in VFS
    const outputDirectoryName = 'ToHTMLFolder/';
    window.dotnetRuntime.Module.FS.mkdirTree(outputDirectoryName);

    // Load the Word document
    const wordDocument = new docModule.Document();
    wordDocument.LoadFromFile(inputFileName);

    // Export the CSS styles to a separate file
    wordDocument.HtmlExportOptions.CssStyleSheetFileName = outputDirectoryName + 'sample.css';
    wordDocument.HtmlExportOptions.CssStyleSheetType = docModule.CssStyleSheetType.External;

    // Export images to a separate directory
    wordDocument.HtmlExportOptions.ImageEmbedded = false;
    wordDocument.HtmlExportOptions.ImagesPath = outputDirectoryName + 'Demo/';

    // Export form fields as plain text
    wordDocument.HtmlExportOptions.IsTextInputFormFieldAsText = true;

    // Convert the document to HTML
    const outputFileName = 'ToHtmlExportOption-out.html';
    wordDocument.SaveToFile({ fileName: outputFileName, fileFormat: docModule.FileFormat.Html });

    // Release resources
    wordDocument.Dispose();

    // Read the output directory recursively and write each level of files into the zip
    const zip = new JSZip();
    const addFilesToZip = async (folderPath, zipFolder) => {
      let items = await window.dotnetRuntime.Module.FS.readdir(folderPath);
      items = items.filter((item) => item !== '.' && item !== '..');
      for (const item of items) {
        const itemPath = `${folderPath}/${item}`;
        try {
          const fileData = await window.dotnetRuntime.Module.FS.readFile(itemPath);
          zipFolder.file(item, fileData);
        } catch (error) {
          const zipSubFolder = zipFolder.folder(item);
          await addFilesToZip(itemPath, zipSubFolder);
        }
      }
    };

    // Package the HTML file together with the resource directory
    zip.file(outputFileName, window.dotnetRuntime.Module.FS.readFile(outputFileName));
    await addFilesToZip(outputDirectoryName, zip);
    const zipBlob = await zip.generateAsync({ type: 'blob' });
    const url = URL.createObjectURL(zipBlob);

    // Trigger download
    const a = window.document.createElement('a');
    a.href = url;
    a.download = 'ToHTMLFolder.zip';
    a.click();
    URL.revokeObjectURL(url);
  };

  return (
    <div style={{ textAlign: 'center', height: '300px' }}>
      <h1>Convert Word To HTML With Export Options</h1>
      <button onClick={wordToHtmlWithOptions}>
        Generate
      </button>
    </div>
  );
}

export default App;

Archivos HTML, CSS e imágenes generados después de configurar las opciones de exportación

Un detalle que vale la pena señalar: Spire.Doc no coloca las imágenes directamente en el directorio especificado por ImagesPath. En su lugar, crea una subcarpeta external_images dentro de ese directorio para contener los archivos de imagen. La estructura resultante es similar a Demo/external_images/*.png, y es por eso que addFilesToZip recorre el árbol de directorios de forma recursiva en lugar de leer una lista plana de archivos.

Integrado vs. externo: elegir la estrategia adecuada

Ambos modos de exportación producen HTML válido a partir del mismo documento de Word, pero responden a necesidades de publicación diferentes. La siguiente tabla resume las diferencias clave para ayudarte a decidir qué enfoque se adapta a tu flujo de trabajo.

Guía rápida de decisión:

• Elige el modo integrado cuando necesites un artefacto único y portátil; por ejemplo, generar una vista previa que un usuario descargue y abra sin conexión, o adjuntar un documento convertido a un correo electrónico.
• Elige el modo externo cuando publiques en una plataforma web donde varios documentos compartan el mismo sistema de diseño, donde quieras almacenar en caché o cargar de forma diferida las imágenes, o donde el tamaño del archivo HTML sea importante para el rendimiento.

Preguntas frecuentes

Las fuentes en el HTML exportado no coinciden con el documento original

Si las fuentes en tu HTML convertido se ven diferentes del archivo de Word de origen, la causa casi siempre son datos de fuente faltantes en el sistema de archivos virtual de WASM. Spire.Doc depende de las fuentes cargadas en VFS para realizar cálculos precisos de diseño y resolución de nombres de fuentes durante la conversión. Cuando una fuente requerida no está disponible, el motor sustituye una fuente de reserva, y las declaraciones font-family en el CSS de salida no coincidirán con lo que especifica el documento original. En documentos que usan fuentes de símbolos como Wingdings, los caracteres afectados también pueden mostrarse como texto ilegible.

La solución es sencilla: precarga los archivos de fuente necesarios en VFS mediante FetchFileToVFS antes de ejecutar la conversión. Para documentos que contienen texto en chino, japonés o coreano, usa una fuente con amplia cobertura Unicode, como ARIALUNI.TTF:

await window.spire.FetchFileToVFS(
  'ARIALUNI.TTF', '/Library/Fonts/', '/'
);

El HTML exportado pierde sus estilos e imágenes al abrirlo

Cuando usas el modo externo (CssStyleSheetType.External con ImageEmbedded = false), los archivos CSS e imágenes se escriben en ubicaciones separadas, y el HTML los referencia mediante rutas relativas. Si descargas solo el archivo HTML sin sus recursos acompañantes, el navegador no puede resolver esas rutas y la página recurre a texto sin formato sin estilo con imágenes rotas.

Para evitar esto, empaqueta siempre el HTML junto con su directorio de recursos; el enfoque addFilesToZip que se muestra en la sección de opciones de exportación se encarga de esto al empaquetar todo en una única descarga zip. Como alternativa, si en realidad no necesitas archivos de recursos separados, cambia al modo integrado para que todo permanezca en un único archivo HTML autocontenido:

wordDocument.HtmlExportOptions.CssStyleSheetType = docModule.CssStyleSheetType.Internal;
wordDocument.HtmlExportOptions.ImageEmbedded = true;

Ver también

• Integrar Spire.Doc for JavaScript en un proyecto de React
• Convertir Word a PDF con Spire.Doc for JavaScript
• Convertir Word a imagen con Spire.Doc for JavaScript
• Descripción general de Spire.Doc for JavaScript

Word-Dokumente sind oft der Ausgangspunkt für Webinhalte – Artikel, Produktspezifikationen und Compliance-Dokumente müssen irgendwann auf einer Website verfügbar sein. Der Weg von .docx zu sauberem HTML ohne einen Backend-Konvertierungsdienst ist die eigentliche Herausforderung. Spire.Doc for JavaScript macht dies möglich, indem eine vollständige Dokumentverarbeitungs-Engine auf WebAssembly ausgeführt wird, die Word-Datei über ein virtuelles Dateisystem (VFS) gelesen wird, die Konvertierung lokal erfolgt und Sie das resultierende HTML herunterladen können – alles clientseitig, ohne Server-Roundtrip.

Zwei Exportstrategien dominieren den Workflow, und die Entscheidung zwischen ihnen ist die eigentliche Wahl:

• Eingebetteter Modus bündelt CSS und Bilder direkt in der HTML-Datei und erzeugt ein einziges, in sich geschlossenes Dokument, das überall geöffnet werden kann.
• Externer Modus schreibt CSS und Bilder in separate Dateien und liefert Ihnen kleineres HTML, wiederverwendbare Stylesheets und einzelne Bild-Assets, die Sie unabhängig verwalten können.

Dieser Artikel führt durch beide Ansätze in einem React-Projekt und vergleicht sie direkt miteinander. Zur Einrichtung lesen Sie Spire.Doc for JavaScript in ein React-Projekt integrieren. Die folgenden Beispiele setzen voraus, dass Spire.Doc installiert und das WebAssembly-Modul initialisiert ist.

Grundlegende Konvertierung: Alles in eine Datei einbetten

Der einfachste Weg, ein Word-Dokument als Webseite zu veröffentlichen, besteht darin, eine einzelne HTML-Datei zu erzeugen, die alles enthält – Markup, Stile und Bilder – in einem in sich geschlossenen Paket. Das ist ideal, wenn Sie ein portables Artefakt benötigen, das unabhängig vom Ort des Öffnens korrekt gerendert wird, ohne fehlende Dateiverweise oder fehlerhafte Links.

Die Konvertierung erfolgt in drei Schritten. Zuerst laden Sie die Schriftdatei und das Word-Quelldokument mit FetchFileToVFS in das virtuelle Dateisystem von WASM. Zweitens erstellen Sie eine Document-Instanz, laden die Datei, konfigurieren HtmlExportOptions so, dass sowohl CSS als auch Bilder eingebettet werden, und rufen SaveToFile auf, um das HTML zu schreiben. Drittens lesen Sie die erzeugte Datei aus dem VFS zurück, verpacken sie in ein Blob und lösen einen Browser-Download aus.

function App() {
  const wordToHtml = async () => {
    // Get the Spire.Doc WASM module
    const docModule = window.wasmModule?.spiredoc;

    // Check if the module is ready
    if (!docModule) {
      alert('Spire.Doc is not ready yet');
      return;
    }

    // Load fonts and the Word file into VFS
    await window.spire.FetchFileToVFS('ARIALUNI.TTF', '/Library/Fonts/', `${process.env.PUBLIC_URL}/static/font/`);
    const inputFileName = 'ToHtml.docx';
    await window.spire.FetchFileToVFS(inputFileName, '', `${process.env.PUBLIC_URL}/static/data/`);

    // Load the Word document
    const wordDocument = new docModule.Document();
    wordDocument.LoadFromFile(inputFileName);

    // Embed the CSS styles into the HTML and embed images as Base64
    wordDocument.HtmlExportOptions.CssStyleSheetType = docModule.CssStyleSheetType.Internal;
    wordDocument.HtmlExportOptions.ImageEmbedded = true;

    // Convert the document to HTML
    const outputFileName = 'ToHtml-result.html';
    wordDocument.SaveToFile({ fileName: outputFileName, fileFormat: docModule.FileFormat.Html });

    // Read the converted file from VFS and trigger download
    const fileArray = window.dotnetRuntime.Module.FS.readFile(outputFileName);
    const blob = new Blob([fileArray], { type: 'text/html;charset=utf-8' });
    const url = URL.createObjectURL(blob);
    const a = window.document.createElement('a');
    a.href = url;
    a.download = outputFileName;
    a.click();
    URL.revokeObjectURL(url);

    // Release resources
    wordDocument.Dispose();
  };

  return (
    <div style={{ textAlign: 'center', height: '300px' }}>
      <h1>Convert Word To HTML</h1>
      <button onClick={wordToHtml}>
        Generate
      </button>
    </div>
  );
}

export default App;

Über SaveToFile aus einem Word-Dokument erzeugte HTML-Seite

Exportoptionen: CSS und Bilder separat

Alles in eine Datei einzubetten ist praktisch, hat aber Nachteile. Ein großes Dokument mit vielen Bildern erzeugt eine sehr große HTML-Datei, und jede Seite, die dasselbe Styling verwendet, trägt ihre eigene Kopie des CSS mit sich. Wenn Sie Stile zentral pflegen, Bild-Assets seitenübergreifend wiederverwenden oder die HTML-Nutzlast klein halten möchten, um ein schnelleres erstes Rendering zu erreichen, sollten Sie CSS und Bilder stattdessen als separate Dateien exportieren.

HtmlExportOptions gibt Ihnen eine feingranulare Kontrolle darüber, wie jeder Ressourcentyp geschrieben wird. Sie können das CSS in eine benannte Stylesheet-Datei leiten, Bilder in ein eigenes Verzeichnis schreiben und sogar steuern, wie Formularfelder serialisiert werden. Das Ergebnis ist keine einzelne Datei mehr, sondern eine Verzeichnisstruktur mit dem HTML, dem Stylesheet und den Bilddateien.

Der Workflow entspricht dem eingebetteten Ansatz, mit zwei Ergänzungen. Erstellen Sie vor der Konvertierung ein Ausgabeverzeichnis im VFS und legen Sie mit CssStyleSheetFileName und ImagesPath fest, wohin Spire.Doc jeden Ressourcentyp schreiben soll. Lesen Sie nach der Konvertierung das gesamte Ausgabeverzeichnis rekursiv ein, packen Sie alles mit JSZip in ein Zip-Archiv und laden Sie es in einem Vorgang herunter.

import JSZip from 'jszip';

function App() {
  const wordToHtmlWithOptions = async () => {
    // Get the Spire.Doc WASM module
    const docModule = window.wasmModule?.spiredoc;

    // Check if the module is ready
    if (!docModule) {
      alert('Spire.Doc is not ready yet');
      return;
    }

    // Load fonts and the Word file into VFS
    await window.spire.FetchFileToVFS('ARIALUNI.TTF', '/Library/Fonts/', `${process.env.PUBLIC_URL}/static/font/`);
    const inputFileName = 'ToHtml.docx';
    await window.spire.FetchFileToVFS(inputFileName, '', `${process.env.PUBLIC_URL}/static/data/`);

    // Create the output directory in VFS
    const outputDirectoryName = 'ToHTMLFolder/';
    window.dotnetRuntime.Module.FS.mkdirTree(outputDirectoryName);

    // Load the Word document
    const wordDocument = new docModule.Document();
    wordDocument.LoadFromFile(inputFileName);

    // Export the CSS styles to a separate file
    wordDocument.HtmlExportOptions.CssStyleSheetFileName = outputDirectoryName + 'sample.css';
    wordDocument.HtmlExportOptions.CssStyleSheetType = docModule.CssStyleSheetType.External;

    // Export images to a separate directory
    wordDocument.HtmlExportOptions.ImageEmbedded = false;
    wordDocument.HtmlExportOptions.ImagesPath = outputDirectoryName + 'Demo/';

    // Export form fields as plain text
    wordDocument.HtmlExportOptions.IsTextInputFormFieldAsText = true;

    // Convert the document to HTML
    const outputFileName = 'ToHtmlExportOption-out.html';
    wordDocument.SaveToFile({ fileName: outputFileName, fileFormat: docModule.FileFormat.Html });

    // Release resources
    wordDocument.Dispose();

    // Read the output directory recursively and write each level of files into the zip
    const zip = new JSZip();
    const addFilesToZip = async (folderPath, zipFolder) => {
      let items = await window.dotnetRuntime.Module.FS.readdir(folderPath);
      items = items.filter((item) => item !== '.' && item !== '..');
      for (const item of items) {
        const itemPath = `${folderPath}/${item}`;
        try {
          const fileData = await window.dotnetRuntime.Module.FS.readFile(itemPath);
          zipFolder.file(item, fileData);
        } catch (error) {
          const zipSubFolder = zipFolder.folder(item);
          await addFilesToZip(itemPath, zipSubFolder);
        }
      }
    };

    // Package the HTML file together with the resource directory
    zip.file(outputFileName, window.dotnetRuntime.Module.FS.readFile(outputFileName));
    await addFilesToZip(outputDirectoryName, zip);
    const zipBlob = await zip.generateAsync({ type: 'blob' });
    const url = URL.createObjectURL(zipBlob);

    // Trigger download
    const a = window.document.createElement('a');
    a.href = url;
    a.download = 'ToHTMLFolder.zip';
    a.click();
    URL.revokeObjectURL(url);
  };

  return (
    <div style={{ textAlign: 'center', height: '300px' }}>
      <h1>Convert Word To HTML With Export Options</h1>
      <button onClick={wordToHtmlWithOptions}>
        Generate
      </button>
    </div>
  );
}

export default App;

HTML-, CSS- und Bilddateien, die nach der Konfiguration der Exportoptionen erzeugt wurden

Ein erwähnenswertes Detail: Spire.Doc legt Bilder nicht direkt in dem durch ImagesPath angegebenen Verzeichnis ab. Stattdessen erstellt es in diesem Verzeichnis einen Unterordner external_images, der die Bilddateien enthält. Die resultierende Struktur sieht wie Demo/external_images/*.png aus, weshalb addFilesToZip den Verzeichnisbaum rekursiv durchläuft, anstatt eine flache Dateiliste zu lesen.

Eingebettet vs. extern: Die richtige Strategie wählen

Beide Exportmodi erzeugen gültiges HTML aus demselben Word-Dokument, dienen aber unterschiedlichen Anforderungen an die Veröffentlichung. Die folgende Tabelle fasst die wichtigsten Unterschiede zusammen, damit Sie entscheiden können, welcher Ansatz zu Ihrem Workflow passt.

Kurzer Entscheidungsleitfaden:

• Wählen Sie eingebettet, wenn Sie ein einzelnes, portables Artefakt benötigen – zum Beispiel, um eine Vorschau zu erzeugen, die ein Benutzer herunterlädt und offline öffnet, oder um ein konvertiertes Dokument an eine E-Mail anzuhängen.
• Wählen Sie extern, wenn Sie auf einer Webplattform veröffentlichen, auf der mehrere Dokumente dasselbe Designsystem verwenden, wenn Sie Bilder zwischenspeichern oder lazy laden möchten oder wenn die HTML-Dateigröße für die Performance relevant ist.

FAQ

Schriftarten im exportierten HTML stimmen nicht mit dem Originaldokument überein

Wenn die Schriftarten in Ihrem konvertierten HTML anders aussehen als in der Word-Quelldatei, liegt die Ursache fast immer in fehlenden Schriftdaten im virtuellen Dateisystem von WASM. Spire.Doc ist auf die in das VFS geladenen Schriftarten angewiesen, um während der Konvertierung präzise Layoutberechnungen und die Auflösung von Schriftartnamen durchzuführen. Wenn eine erforderliche Schriftart nicht verfügbar ist, ersetzt die Engine sie durch eine Ausweichschrift, und die font-family-Deklarationen im ausgegebenen CSS stimmen nicht mit denen des Originaldokuments überein. Bei Dokumenten, die Symbolschriftarten wie Wingdings verwenden, können die betroffenen Zeichen außerdem als unleserlicher Text dargestellt werden.

Die Lösung ist unkompliziert: Laden Sie die erforderlichen Schriftdateien vor der Konvertierung über FetchFileToVFS in das VFS vor. Verwenden Sie für Dokumente mit chinesischem, japanischem oder koreanischem Text eine Schriftart mit breiter Unicode-Abdeckung wie ARIALUNI.TTF:

await window.spire.FetchFileToVFS(
  'ARIALUNI.TTF', '/Library/Fonts/', '/'
);

Exportiertes HTML verliert beim Öffnen seine Stile und Bilder

Wenn Sie den externen Modus verwenden (CssStyleSheetType.External mit ImageEmbedded = false), werden die CSS- und Bilddateien an separaten Orten gespeichert, und das HTML verweist über relative Pfade darauf. Wenn Sie nur die HTML-Datei ohne die zugehörigen Ressourcen herunterladen, kann der Browser diese Pfade nicht auflösen, und die Seite fällt auf unformatierten Klartext mit defekten Bildern zurück.

Um dies zu vermeiden, sollten Sie das HTML immer zusammen mit seinem Ressourcenverzeichnis paketieren – der im Abschnitt zu den Exportoptionen gezeigte addFilesToZip-Ansatz erledigt dies, indem alles in einen einzigen Zip-Download gebündelt wird. Wenn Sie keine separaten Ressourcendateien benötigen, wechseln Sie alternativ in den eingebetteten Modus, damit alles in einer einzigen, in sich geschlossenen HTML-Datei bleibt:

wordDocument.HtmlExportOptions.CssStyleSheetType = docModule.CssStyleSheetType.Internal;
wordDocument.HtmlExportOptions.ImageEmbedded = true;

Siehe auch

• Spire.Doc for JavaScript in ein React-Projekt integrieren
• Word mit Spire.Doc for JavaScript in PDF konvertieren
• Word mit Spire.Doc for JavaScript in ein Bild konvertieren
• Überblick über Spire.Doc for JavaScript

Документы Word часто являются отправной точкой для веб-контента — статьи, спецификации продуктов и нормативные документы рано или поздно должны быть размещены на веб-сайте. Задача — преобразовать .docx в чистый HTML без серверной службы конвертации. Spire.Doc for JavaScript делает это возможным, запуская полноценный движок обработки документов на WebAssembly, читая файл Word через виртуальную файловую систему (VFS), выполняя преобразование локально и позволяя скачать полученный HTML — всё на стороне клиента, без обращения к серверу.

В рабочем процессе преобладают две стратегии экспорта, и выбор между ними — это главное решение:

• Встроенный режим объединяет CSS и изображения непосредственно в HTML-файле, создавая единый самодостаточный документ, который открывается где угодно.
• Внешний режим записывает CSS и изображения в отдельные файлы, что даёт меньший размер HTML, переиспользуемые таблицы стилей и отдельные графические ресурсы, которыми можно управлять независимо.

В этой статье рассматриваются оба подхода в проекте React и проводится их сравнение. Для настройки обратитесь к разделу Интеграция Spire.Doc for JavaScript в проект React. Примеры ниже предполагают, что Spire.Doc установлен, а модуль WebAssembly инициализирован.

Базовое преобразование: встраивание всего в один файл

Самый простой способ опубликовать документ Word как веб-страницу — создать один HTML-файл, который содержит всё — разметку, стили и изображения — в одном самодостаточном пакете. Это идеально подходит, когда нужен переносимый артефакт, который корректно отображается независимо от того, где он открыт, без ссылок на отсутствующие файлы или неработающих ссылок.

Преобразование состоит из трёх шагов. Во-первых, загрузите файл шрифта и исходный документ Word в виртуальную файловую систему WASM с помощью FetchFileToVFS. Во-вторых, создайте экземпляр Document, загрузите файл, настройте HtmlExportOptions для встраивания как CSS, так и изображений, и вызовите SaveToFile для записи HTML. В-третьих, прочитайте созданный файл из VFS, оберните его в Blob и инициируйте загрузку в браузере.

function App() {
  const wordToHtml = async () => {
    // Get the Spire.Doc WASM module
    const docModule = window.wasmModule?.spiredoc;

    // Check if the module is ready
    if (!docModule) {
      alert('Spire.Doc is not ready yet');
      return;
    }

    // Load fonts and the Word file into VFS
    await window.spire.FetchFileToVFS('ARIALUNI.TTF', '/Library/Fonts/', `${process.env.PUBLIC_URL}/static/font/`);
    const inputFileName = 'ToHtml.docx';
    await window.spire.FetchFileToVFS(inputFileName, '', `${process.env.PUBLIC_URL}/static/data/`);

    // Load the Word document
    const wordDocument = new docModule.Document();
    wordDocument.LoadFromFile(inputFileName);

    // Embed the CSS styles into the HTML and embed images as Base64
    wordDocument.HtmlExportOptions.CssStyleSheetType = docModule.CssStyleSheetType.Internal;
    wordDocument.HtmlExportOptions.ImageEmbedded = true;

    // Convert the document to HTML
    const outputFileName = 'ToHtml-result.html';
    wordDocument.SaveToFile({ fileName: outputFileName, fileFormat: docModule.FileFormat.Html });

    // Read the converted file from VFS and trigger download
    const fileArray = window.dotnetRuntime.Module.FS.readFile(outputFileName);
    const blob = new Blob([fileArray], { type: 'text/html;charset=utf-8' });
    const url = URL.createObjectURL(blob);
    const a = window.document.createElement('a');
    a.href = url;
    a.download = outputFileName;
    a.click();
    URL.revokeObjectURL(url);

    // Release resources
    wordDocument.Dispose();
  };

  return (
    <div style={{ textAlign: 'center', height: '300px' }}>
      <h1>Convert Word To HTML</h1>
      <button onClick={wordToHtml}>
        Generate
      </button>
    </div>
  );
}

export default App;

HTML-страница, созданная из документа Word с помощью SaveToFile

Параметры экспорта: отдельные CSS и изображения

Встраивание всего в один файл удобно, но у него есть компромиссы. Большой документ с множеством изображений создаёт очень большой HTML-файл, и каждая страница, использующая одинаковое оформление, несёт собственную дублирующую копию CSS. Если вы хотите централизованно управлять стилями, повторно использовать графические ресурсы на разных страницах или уменьшить размер HTML для более быстрой первоначальной отрисовки, вместо этого следует экспортировать CSS и изображения в отдельные файлы.

HtmlExportOptions предоставляет детальный контроль над тем, как записывается каждый тип ресурсов. Вы можете направить CSS в именованный файл таблицы стилей, отправлять изображения в выделенный каталог и даже управлять сериализацией полей форм. Результатом становится уже не один файл, а структура каталогов, содержащая HTML, таблицу стилей и файлы изображений.

Рабочий процесс повторяет встроенный подход с двумя дополнениями. Перед преобразованием создайте выходной каталог в VFS и используйте CssStyleSheetFileName и ImagesPath, чтобы указать Spire.Doc, куда записывать каждый тип ресурсов. После преобразования рекурсивно прочитайте весь выходной каталог, упакуйте всё в zip-архив с помощью JSZip и скачайте его одной операцией.

import JSZip from 'jszip';

function App() {
  const wordToHtmlWithOptions = async () => {
    // Get the Spire.Doc WASM module
    const docModule = window.wasmModule?.spiredoc;

    // Check if the module is ready
    if (!docModule) {
      alert('Spire.Doc is not ready yet');
      return;
    }

    // Load fonts and the Word file into VFS
    await window.spire.FetchFileToVFS('ARIALUNI.TTF', '/Library/Fonts/', `${process.env.PUBLIC_URL}/static/font/`);
    const inputFileName = 'ToHtml.docx';
    await window.spire.FetchFileToVFS(inputFileName, '', `${process.env.PUBLIC_URL}/static/data/`);

    // Create the output directory in VFS
    const outputDirectoryName = 'ToHTMLFolder/';
    window.dotnetRuntime.Module.FS.mkdirTree(outputDirectoryName);

    // Load the Word document
    const wordDocument = new docModule.Document();
    wordDocument.LoadFromFile(inputFileName);

    // Export the CSS styles to a separate file
    wordDocument.HtmlExportOptions.CssStyleSheetFileName = outputDirectoryName + 'sample.css';
    wordDocument.HtmlExportOptions.CssStyleSheetType = docModule.CssStyleSheetType.External;

    // Export images to a separate directory
    wordDocument.HtmlExportOptions.ImageEmbedded = false;
    wordDocument.HtmlExportOptions.ImagesPath = outputDirectoryName + 'Demo/';

    // Export form fields as plain text
    wordDocument.HtmlExportOptions.IsTextInputFormFieldAsText = true;

    // Convert the document to HTML
    const outputFileName = 'ToHtmlExportOption-out.html';
    wordDocument.SaveToFile({ fileName: outputFileName, fileFormat: docModule.FileFormat.Html });

    // Release resources
    wordDocument.Dispose();

    // Read the output directory recursively and write each level of files into the zip
    const zip = new JSZip();
    const addFilesToZip = async (folderPath, zipFolder) => {
      let items = await window.dotnetRuntime.Module.FS.readdir(folderPath);
      items = items.filter((item) => item !== '.' && item !== '..');
      for (const item of items) {
        const itemPath = `${folderPath}/${item}`;
        try {
          const fileData = await window.dotnetRuntime.Module.FS.readFile(itemPath);
          zipFolder.file(item, fileData);
        } catch (error) {
          const zipSubFolder = zipFolder.folder(item);
          await addFilesToZip(itemPath, zipSubFolder);
        }
      }
    };

    // Package the HTML file together with the resource directory
    zip.file(outputFileName, window.dotnetRuntime.Module.FS.readFile(outputFileName));
    await addFilesToZip(outputDirectoryName, zip);
    const zipBlob = await zip.generateAsync({ type: 'blob' });
    const url = URL.createObjectURL(zipBlob);

    // Trigger download
    const a = window.document.createElement('a');
    a.href = url;
    a.download = 'ToHTMLFolder.zip';
    a.click();
    URL.revokeObjectURL(url);
  };

  return (
    <div style={{ textAlign: 'center', height: '300px' }}>
      <h1>Convert Word To HTML With Export Options</h1>
      <button onClick={wordToHtmlWithOptions}>
        Generate
      </button>
    </div>
  );
}

export default App;

HTML, CSS и файлы изображений, созданные после настройки параметров экспорта

Одна деталь, которую стоит отметить: Spire.Doc не размещает изображения непосредственно в каталоге, указанном в ImagesPath. Вместо этого он создаёт подпапку external_images внутри этого каталога для хранения файлов изображений. Полученная структура выглядит как Demo/external_images/*.png, и именно поэтому addFilesToZip рекурсивно обходит дерево каталогов, а не читает плоский список файлов.

Встроенный или внешний: выбор правильной стратегии

Оба режима экспорта создают корректный HTML из одного и того же документа Word, но служат разным задачам публикации. В таблице ниже приведены ключевые различия, которые помогут вам решить, какой подход подходит для вашего рабочего процесса.

Краткое руководство по выбору:

• Выбирайте встроенный режим, когда вам нужен единый портируемый артефакт — например, для создания предпросмотра, который пользователь скачивает и открывает офлайн, или для прикрепления преобразованного документа к электронному письму.
• Выбирайте внешний режим, когда вы публикуете на веб-платформе, где несколько документов используют одну и ту же систему дизайна, где вы хотите кэшировать или лениво загружать изображения, или где размер HTML-файла важен для производительности.

Часто задаваемые вопросы

Шрифты в экспортированном HTML не совпадают с исходным документом

Если шрифты в преобразованном HTML выглядят иначе, чем в исходном файле Word, причина почти всегда в отсутствии данных о шрифтах в виртуальной файловой системе WASM. Spire.Doc полагается на шрифты, загруженные в VFS, для точных расчётов макета и разрешения имён шрифтов во время преобразования. Когда требуемый шрифт недоступен, движок подставляет резервный шрифт, и объявления font-family в выходном CSS не будут соответствовать тому, что указано в исходном документе. Для документов, использующих символьные шрифты, такие как Wingdings, затронутые символы также могут отображаться как искажённый текст.

Решение простое: предварительно загрузите необходимые файлы шрифтов в VFS с помощью FetchFileToVFS перед запуском преобразования. Для документов, содержащих текст на китайском, японском или корейском языках, используйте шрифт с широким покрытием Unicode, например ARIALUNI.TTF:

await window.spire.FetchFileToVFS(
  'ARIALUNI.TTF', '/Library/Fonts/', '/'
);

Экспортированный HTML теряет стили и изображения при открытии

Когда вы используете внешний режим (CssStyleSheetType.External с ImageEmbedded = false), файлы CSS и изображений записываются в отдельные места, а HTML ссылается на них через относительные пути. Если вы скачаете только HTML-файл без сопутствующих ресурсов, браузер не сможет разрешить эти пути, и страница отобразится как неоформленный простой текст с неработающими изображениями.

Чтобы избежать этого, всегда упаковывайте HTML вместе с его каталогом ресурсов — подход addFilesToZip, показанный в разделе параметров экспорта, делает это, объединяя всё в одну загрузку zip-архива. В качестве альтернативы, если вам действительно не нужны отдельные файлы ресурсов, переключитесь на встроенный режим, чтобы всё оставалось в одном самодостаточном HTML-файле:

wordDocument.HtmlExportOptions.CssStyleSheetType = docModule.CssStyleSheetType.Internal;
wordDocument.HtmlExportOptions.ImageEmbedded = true;

См. также

• Интеграция Spire.Doc for JavaScript в проект React
• Преобразование Word в PDF с помощью Spire.Doc for JavaScript
• Преобразование Word в изображение с помощью Spire.Doc for JavaScript
• Обзор Spire.Doc for JavaScript

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é.

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:

1. Apri il documento in Microsoft Word.
2. Vai su File > Opzioni > Visualizza.
3. Seleziona Stampa colori e immagini di sfondo.
4. 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");

Vedi anche

• Come integrare Spire.Doc per JavaScript in un progetto React
• Impostare filigrane di Word con Spire.Doc per JavaScript
• Impostare le proprietà di un documento Word con Spire.Doc per JavaScript
• Impostare i margini di pagina di Word con Spire.Doc per JavaScript