为 Word 文档设置页面背景，是合同、公文与品牌宣传类文档排版中最常用的美化手段之一：一层柔和的底色，或一张与企业视觉一致的背景图，就能为整份文档建立统一的视觉基调。Spire.Doc for JavaScript 基于 WebAssembly 在浏览器端直接完成此设置，通过虚拟文件系统（VFS）管理输入输出文件，无需后端服务支持。
本文介绍三个核心功能点：
有关安装和项目配置，请参考 React 项目中集成 Spire.Doc for JavaScript。以下示例默认已安装 Spire.Doc 并完成 WebAssembly 模块初始化。
设置纯色背景
纯色背景的核心流程分为三个阶段：首先通过 FetchFileToVFS 将字体文件和目标 Word 文件载入 WASM 虚拟文件系统；然后实例化 Document 加载文件，将 Background.Type 指定为 BackgroundType.Color，并通过 Background.Color 赋值一个内置色值；最后调用 SaveToFile 将文档保存到 VFS，从 VFS 读取生成的 docx 文件，封装为 Blob 后生成下载链接。
function App() {
const SetSolidColorBackground = async () => {
const docModule = window.wasmModule?.spiredoc;
if (!docModule) {
alert('Spire.Doc is not ready yet');
return;
}
// 将示例文件加载到虚拟文件系统（VFS）中
let inputFileName = "ScienceTemplate.docx";
await window.spire.FetchFileToVFS(inputFileName, "", `${process.env.PUBLIC_URL}static/data/`);
// 创建 Word 文档
let doc = new docModule.Document();
// 加载文件
doc.LoadFromFile(inputFileName);
// 设置背景类型为颜色
doc.Background.Type = docModule.BackgroundType.Color;
// 设置背景颜色
doc.Background.Color = docModule.Color.get_LightYellow();
// 定义输出文件名
const outputFileName = "SetSolidColorBackground_out.docx";
// 将文档保存到指定路径
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>为Word文档设置纯色背景</h1>
<button onClick={SetSolidColorBackground}>开始</button>
</div>
);
}
export default App;
通过 Background.Color 设置纯色背景后生成的 Word 文档
设置渐变背景
渐变背景的核心流程与纯色背景一致，区别在于中间阶段：将 Background.Type 指定为 BackgroundType.Gradient 后，通过 Background.Gradient 获取背景渐变对象，分别设置起点色 Color1 与终点色 Color2，再通过 ShadingStyle 与 ShadingVariant 控制渐变的方向与过渡方式。
function App() {
const SetGradientBackground = async () => {
const docModule = window.wasmModule?.spiredoc;
if (!docModule) {
alert('Spire.Doc is not ready yet');
return;
}
// 将示例文件加载到虚拟文件系统（VFS）中
let inputFileName = "ScienceTemplate.docx";
await window.spire.FetchFileToVFS(inputFileName, "", `${process.env.PUBLIC_URL}static/data/`);
// 创建Word文档
let doc = new docModule.Document();
// 加载文件
doc.LoadFromFile(inputFileName);
// 设置背景类型为渐变
doc.Background.Type = docModule.BackgroundType.Gradient;
let gradient = doc.Background.Gradient;
// 设置渐变的起始颜色和结束颜色
gradient.Color1 = docModule.Color.get_White();
gradient.Color2 = docModule.Color.get_LightBlue();
// 设置渐变的着色样式和方向
gradient.ShadingVariant = docModule.GradientShadingVariant.ShadingDown;
gradient.ShadingStyle = docModule.GradientShadingStyle.Horizontal;
// 定义输出文件名
const outputFileName = "SetGradientBackground_out.docx";
// 将文档保存到指定路径
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>为Word文档设置渐变背景</h1>
<button onClick={SetGradientBackground}>开始</button>
</div>
);
}
export default App;
通过 Background.Gradient 设置渐变背景后生成的 Word 文档
设置图片背景
图片背景的核心流程与前面两种背景类似，区别在于资源准备与赋值方式：载入阶段除字体文件和目标 Word 文件外，还需将背景图片一并载入 VFS；然后将 Background.Type 指定为 BackgroundType.Picture，再调用 Background.SetPicture 传入 VFS 中的图片路径，即可将图片平铺为整页背景。
function App() {
const SetImageBackground = async () => {
const docModule = window.wasmModule?.spiredoc;
if (!docModule) {
alert('Spire.Doc is not ready yet');
return;
}
// 将示例文件加载到虚拟文件系统（VFS）中
let inputFileName1 = "ScienceTemplate.docx";
await window.spire.FetchFileToVFS(inputFileName1, "", `${process.env.PUBLIC_URL}static/data/`);
// 将背景图片加载到虚拟文件系统（VFS）中
let inputFileName2 = "Background.png";
await window.spire.FetchFileToVFS(inputFileName2, "", `${process.env.PUBLIC_URL}static/data/`);
// 加载一个Word文档
let doc = new docModule.Document();
doc.LoadFromFile(inputFileName1);
// 将背景类型设置为图片
doc.Background.Type = docModule.BackgroundType.Picture;
// 设置背景图片
doc.Background.SetPicture(inputFileName2);
// 定义输出文件名
const outputFileName = "SetImageBackground_out.docx";
// 将文档保存到指定路径
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>在 Word 文档中设置图片背景</h1>
<button onClick={SetImageBackground}>开始</button>
</div>
);
}
export default App;
通过 Background.SetPicture 设置图片背景后生成的 Word 文档
常见问题
打印时背景不显示
原因：Word 默认不打印页面背景色和背景图片，这是 Word 客户端的打印设置，并非文档中的背景设置丢失。打开文档时背景可以正常显示，只有打印输出时会被忽略。
解决：如果需要在打印稿中保留背景，可在 Word 中通过「文件 > 选项 > 显示」勾选「打印背景色和图像」后再打印。如果要求背景在任何环境下都必须输出，建议改用页眉中的整页形状或水印来模拟。
图片背景未生效
原因：调用 SetPicture 之前未将 Background.Type 设为 BackgroundType.Picture，或背景图片没有通过 FetchFileToVFS 载入 VFS，导致 SetPicture 找不到图片文件。
解决：先指定背景类型，再传入已载入 VFS 的图片文件名：
document.Background.Type = wasmModule.BackgroundType.Picture;
document.Background.SetPicture("Background.png");
获取免费许可证
如果您希望删除结果文档中的评估消息，或者摆脱功能限制，请该Email地址已收到反垃圾邮件插件保护。要显示它您需要在浏览器中启用JavaScript。获取有效期 30 天的临时许可证。
