모든 계약서, 공식 서신, 브랜드 홍보물에는 암묵적인 시각적 정체성이 담겨 있습니다. 순백의 페이지도 용도는 충분히 해내지만, 그 뒤에 있는 조직에 대해서는 아무것도 말해 주지 않습니다. 부드러운 색조, 은은한 두 가지 색 그라데이션, 또는 타일로 반복되는 배경 이미지를 추가하는 순간, 문서 전체가 일반적인 파일에서 알아볼 수 있는 브랜드 결과물로 바뀌며, 독자들은 그 이유를 설명하지 못하더라도 이를 알아차립니다.
Spire.Doc for JavaScript는 WebAssembly를 통해 이러한 시각적 스타일링을 브라우저로 직접 가져옵니다. 서버 왕복도, Office 자동화 의존성도, 데스크톱 설치 요구 사항도 없습니다. Word 파일을 WASM 가상 파일 시스템(VFS)에 로드하고, 세 가지 배경 모드 중 하나를 선택한 다음, 스타일이 적용된 문서를 내보냅니다. 이 모든 과정이 React 애플리케이션의 클라이언트 측에서 이루어집니다.
이 가이드는 세 가지 배경 옵션 각각을 API 목록이 아니라 일련의 디자인 결정으로 살펴봅니다. 먼저 빠른 비교를 통해 사용 사례에 맞는 올바른 기법을 선택할 수 있도록 한 다음, 각각의 구현 세부 사항으로 들어갑니다.
한눈에 보는 세 가지 배경 접근법
코드를 작성하기 전에, 각 배경 유형이 디자인 관점에서 어떤 가치를 제공하는지 이해하면 도움이 됩니다. 아래 표는 시각적 결과, 필요한 구성의 정도, 각 접근법이 빛을 발하는 시나리오를 요약합니다.
| 접근법 | 시각적 효과 | 구성 작업량 | 가장 적합한 용도 |
|---|---|---|---|
| 단색 | 하나의 균일한 색상이 모든 페이지를 채웁니다 | 낮음 — BackgroundType.Color를 설정하고 색상 하나를 지정합니다 |
깔끔하고 전문적인 기본 색조가 필요한 계약서, 내부 메모, 공식 서신 |
| 그라데이션 | 페이지 전체에 걸친 두 색상의 방향성 혼합 | 보통 — Color1, Color2, 그리고 ShadingStyle 및 ShadingVariant를 정의합니다 |
은은한 깊이감이 도움이 되는 표지 페이지, 인증서, 마케팅 템플릿 |
| 그림 | 전체 페이지에 타일로 반복되는 배경 이미지 | 보통 — 이미지를 VFS에 로드한 다음 SetPicture를 호출합니다 |
브랜드 문구류, 장식 요소가 있는 레터헤드, 테마 문서 템플릿 |
세 가지 모두 동일한 전체 워크플로를 공유합니다. 원본 문서를 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 클라이언트에서 특정 설정을 활성화해야 합니다:
- Microsoft Word에서 문서를 엽니다.
- 파일 > 옵션 > 표시로 이동합니다.
- 배경색 및 이미지 인쇄를 선택합니다.
- 평소처럼 인쇄합니다.
독자의 Word 설정과 관계없이 모든 출력 환경에서 배경이 렌더링되도록 해야 한다면, 대체 접근법을 고려하세요. 문서 머리글에 전체 페이지 도형을 배치하거나 워터마크를 사용하여 배경 효과를 시뮬레이션하는 것입니다. 이러한 기법은 페이지 서식이 아니라 콘텐츠로 처리되므로 모든 구성에서 안정적으로 인쇄됩니다.
자주 묻는 질문
문서를 인쇄할 때 배경이 표시되지 않는 이유는 무엇인가요?
이는 예상된 동작입니다. Word는 기본적으로 인쇄 출력에서 페이지 배경을 숨깁니다. 설정은 올바르게 저장되고 화면에서는 렌더링되지만, Word 클라이언트의 인쇄 옵션이 이를 걸러냅니다. 배경이 사라진 것이 아니라 단순히 인쇄 스트림에 포함되지 않았을 뿐입니다.
이 문제를 해결하려면 인쇄하기 전에 Word에서 파일 > 옵션 > 표시 아래의 배경색 및 이미지 인쇄를 활성화하세요. 독자의 인쇄 설정을 제어할 수 없는 환경에서는 머리글에 전체 페이지 도형을 넣거나 워터마크를 사용하여 시각 효과를 복제하세요. 이러한 요소는 인쇄 가능한 콘텐츠로 처리되기 때문입니다.
그림 배경이 효과가 없는 이유는 무엇인가요?
일반적으로 두 가지 이유 중 하나로 발생합니다. SetPicture를 호출하기 전에 Background.Type을 BackgroundType.Picture로 설정하지 않았거나, 이미지 파일이 FetchFileToVFS를 통해 VFS에 로드되지 않아 SetPicture가 해당 파일을 찾을 수 없는 경우입니다.
먼저 배경 유형을 설정하고, 이미 가상 파일 시스템에 로드된 이미지의 정확한 파일 이름을 전달해야 합니다:
document.Background.Type = wasmModule.BackgroundType.Picture;
document.Background.SetPicture("Background.png");