Каждый договор, официальное письмо и элемент фирменного стиля несёт неявную визуальную идентичность. Обычная белая страница выполняет свою задачу, но ничего не говорит об организации, стоящей за ней. Как только вы добавляете мягкий оттенок, тонкий двухцветный градиент или мозаичное фоновое изображение, весь документ превращается из безликого файла в узнаваемый брендированный артефакт — и читатели это замечают, даже если не могут объяснить почему.
Spire.Doc for JavaScript привносит это визуальное оформление прямо в браузер через WebAssembly. Здесь нет обращения к серверу, зависимости от автоматизации Office или необходимости устанавливать настольную программу. Вы загружаете файл Word в виртуальную файловую систему WASM (VFS), выбираете один из трёх режимов фона и экспортируете оформленный документ — всё на стороне клиента в приложении React.
Это руководство рассматривает каждый из трёх вариантов фона не как каталог API, а как набор дизайнерских решений. Мы начнём с краткого сравнения, чтобы вы могли подобрать подходящую технику для своего сценария, а затем перейдём к деталям реализации каждого варианта.
Три подхода к фону: краткий обзор
Прежде чем писать код, полезно понять, что каждый тип фона даёт с точки зрения дизайна. В таблице ниже обобщены визуальный результат, объём необходимой настройки и сценарии, в которых каждый подход особенно хорош.
| Подход | Визуальный эффект | Трудоёмкость настройки | Лучше всего подходит для |
|---|---|---|---|
| Сплошной цвет | Один однородный цвет заполняет каждую страницу | Низкая — установите BackgroundType.Color и назначьте один цвет |
Договоры, внутренние служебные записки, официальные письма, которым нужен чистый профессиональный базовый тон |
| Градиент | Двухцветное направленное смешение по всей странице | Средняя — задайте Color1, Color2, а также ShadingStyle и ShadingVariant
|
Титульные страницы, сертификаты, маркетинговые шаблоны, которым нужна тонкая глубина |
| Изображение | Фоновое изображение, мозаично заполняющее всю страницу | Средняя — загрузите изображение в VFS, затем вызовите SetPicture
|
Брендированные фирменные бланки, бланки с декоративными элементами, тематические шаблоны документов |
Все три подхода используют один и тот же общий рабочий процесс: загрузите исходный документ в VFS, настройте свойство Background у экземпляра Document, сохраните результат и запустите скачивание в браузере. Различия заключаются исключительно в том, как вы настраиваете это свойство Background — именно здесь и появляются дизайнерские решения.
Инструкции по настройке проекта и установке см. в разделе Интеграция Spire.Doc for JavaScript в проект React. Примеры кода ниже предполагают, что модуль WASM уже инициализирован и доступен в window.wasmModule.
Фон сплошного цвета
Сплошной цвет — самый сдержанный вариант фона, и часто самый эффективный. Тёплый кремовый или бледно-серый фон под чёрным текстом снижает нагрузку на глаза, не отвлекая внимание. Для официальных документов, таких как договоры и политики, лёгкий оттенок сигнализирует: «этот документ принадлежит конкретной организации», не превращаясь в украшение.
Реализация состоит из трёх чётких шагов. Сначала используйте FetchFileToVFS, чтобы загрузить целевой файл Word (и файлы шрифтов) в виртуальную файловую систему WASM. Затем создайте Document, загрузите файл, установите Background.Type в BackgroundType.Color и назначьте встроенный цвет свойству Background.Color. В-третьих, сохраните документ обратно в VFS с помощью SaveToFile, прочитайте полученный файл как массив байтов, оберните его в 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 вместе с документом, поэтому оставьте этот подход для шаблонов, где визуальный эффект оправдывает дополнительные ресурсы.
Настройка отличается от двух предыдущих методов в одном важном моменте: фоновое изображение также необходимо загрузить в VFS с помощью FetchFileToVFS, прежде чем на него можно будет ссылаться. Когда и документ, и изображение окажутся в 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;
}
// 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:
- Откройте документ в Microsoft Word.
- Перейдите в Файл > Параметры > Экран.
- Установите флажок Печатать цвета и изображения фона.
- Печатайте как обычно.
Если вам нужно, чтобы фон отображался в любой среде вывода независимо от настроек Word у читателя, рассмотрите альтернативный подход: разместите фигуру на всю страницу в колонтитуле документа или используйте водяной знак для имитации фонового эффекта. Эти приёмы считаются содержимым, а не форматированием страницы, поэтому они надёжно печатаются при любых конфигурациях.
Часто задаваемые вопросы
Почему фон не отображается при печати документа?
Это ожидаемое поведение. Word по умолчанию подавляет фон страницы при печати — настройка корректно сохраняется и отображается на экране, но параметры печати клиента Word отфильтровывают её. Фон не потерян; он просто не включается в поток печати.
Чтобы исправить это, включите Печатать цвета и изображения фона в разделе Файл > Параметры > Экран в Word перед печатью. В средах, где вы не можете управлять настройками печати читателя, используйте фигуру на всю страницу в колонтитуле или водяной знак для воспроизведения визуального эффекта, поскольку эти элементы считаются печатаемым содержимым.
Почему фоновое изображение не даёт эффекта?
Обычно это происходит по одной из двух причин: либо Background.Type не был установлен в BackgroundType.Picture перед вызовом SetPicture, либо файл изображения не был загружен в VFS через FetchFileToVFS, поэтому SetPicture не может его найти.
Убедитесь, что сначала задан тип фона, и передайте точное имя файла изображения, которое уже загружено в виртуальную файловую систему:
document.Background.Type = wasmModule.BackgroundType.Picture;
document.Background.SetPicture("Background.png");