随着企业数字化转型加速，纯前端文档处理已成为 Web 应用的核心需求之一。Angular 作为成熟的企业级前端框架，以其强类型校验、组件化架构和高效的状态管理能力，广泛应用于 OA 系统、文档平台、教育管理系统等复杂场景。
本文将详细介绍如何将 Spire.OfficeJS 集成到 Angular 项目中，实现本地文件上传、在线编辑、格式转换与下载等核心功能。
内容概览
Spire.OfficeJS 产品简介
Spire.OfficeJS 是一款企业级在线文档处理与编辑解决方案，包含 Spire.WordJS、Spire.ExcelJS、Spire.PresentationJS、Spire.PDFJS 四个模块。该产品无需依赖本地 Office 软件，也无需安装任何插件，即可在浏览器中实现 Word、Excel、PPT、PDF 等主流格式文件的在线预览、实时编辑、批注、与格式转换等功能，同时具备云原生、跨平台、高安全性等企业级特性。
核心优势包括：
- 模块化架构：四大核心模块各司其职，覆盖文档处理全场景 — Word 文档精细化编辑、Excel 数据计算与图表分析、PPT 演示文稿可视化编辑、PDF 文档快速预览。
- 纯前端渲染能力：基于 WebAssembly 自研引擎，无需后端参与文档转换，降低服务器压力，提升响应速度。
- 多格式兼容：支持 DOCX、XLSX、PPTX、PDF、WPS 等主流文件格式，支持跨格式导出（如 Word 转 PDF）。
- 安全可控：支持静态文件加密存储，保障文档数据安全。
- 轻量易集成：无缝适配 Angular、Vue、React 等主流前端框架，仅需简单配置即可快速集成。
环境准备与 Angular 项目初始化
在开始集成前，需先完成以下准备工作，确保开发环境符合要求。
1. 安装 Node.js 与 npm
- 下载安装：访问 Node.js 官方下载地址，选择对应系统版本，按默认向导完成安装。
- 版本验证：CMD 执行以下命令验证安装是否成功，若显示版本号则说明安装完成。
node -v
npm -v
2. 安装 Angular CLI 脚手架
Angular CLI 是快速构建 Angular 项目的工具，通过 npm 全局安装：
npm install -g @angular/cli
- 安装完成后，执行以下命令查看 Angular CLI 版本，确认安装成功：
ng version
3. 初始化 Angular 项目
通过 Angular CLI 创建基础项目，为后续集成 Spire.OfficeJS 搭建框架。
- 打开 CMD 命令行，切换到目标目录（示例：
F:\angular）：
- 执行以下命令创建 Angular 项目：
ng new spireOfficeJS --skip-git
- 项目创建向导配置（按如下选择确保兼容性）：
- 是否创建无 zone.js 的 "zoneless" 应用：No
- 样式表格式：CSS
- 是否启用 SSR/SSG：No
4.验证项目初始化
使用 VS Code 打开项目，在终端执行以下命令启动开发服务器：
npm run start
浏览器打开 http://localhost:4200/，若显示 “Hello, spireOfficeJS” 及 Angular 默认页面，则项目初始化成功。
集成 Spire.OfficeJS 在线编辑器
1. 部署 Spire.OfficeJS 静态资源
下载 Spire.OfficeJS 产品包，解压并运行 run_genallfonts 脚本后，需将更新后的产品包中的web 文件夹复制到 Angular 项目的静态目录中，以确保编辑器脚本可被正常访问。具体操作如下：
- 解压 Spire.OfficeJS 产品包。在 Windows 环境下，双击运行解压目录下的 run_genallfonts.bat 文件；在 Linux 环境下，执行命令 sh run_genallfonts.sh start 来运行该脚本。运行完成后，web 文件夹下会生成 fontsweb 子文件夹。
- 在项目 public 目录下创建 spire.cloud 文件夹（完整路径为：
public/spire.cloud）。
- 从更新后的 Spire.OfficeJS 产品包中找到 web 文件夹，将其整体复制到
public/spire.cloud/ 目录下。
- 确保核心脚本 SpireCloudEditor.js 的最终存放路径为：
public/spire.cloud/web/editors/spireapi/SpireCloudEditor.js。
⚠️ 注意：此路径需与后续配置的 office-js.ts 中路径完全一致，否则编辑器无法加载
2. 状态管理配置
用于同步文件上传数据（文件对象 + 二进制数据），确保编辑器组件可访问。
（1）安装依赖
使用 NgRx Signals 管理文件数据，在VS Code 终端执行以下安装命令：
npm install @ngrx/effects @ngrx/signals @ngrx/store
（2）创建状态管理 Store
- 在 src/app/ 目录下创建 store 文件夹，新建 index.ts 文件。
- 复制以下代码到 index.ts，定义文件状态与操作方法：
import { signalStore, withState, withMethods, patchState } from '@ngrx/signals';
// 定义文件状态接口
interface FileState {
file: File | null; // 上传的文件对象
fileUint8Data: Uint8Array | null; // 文件二进制数据
}
// 初始状态
const initialState: FileState = {
file: null,
fileUint8Data: null,
};
// 创建全局 Store
export const fileStore = signalStore(
{ providedIn: 'root' },
withState(initialState),
withMethods((store) => ({
// 更新文件对象
setFileData(data: File | null): void {
patchState(store, { file: data });
},
// 更新文件二进制数据
setFileUint8Data(uint8Data: Uint8Array | null): void {
patchState(store, { fileUint8Data: uint8Data });
}
}))
);
3. 核心组件开发（上传 + 编辑器）
（1）创建组件
在终端执行以下命令，创建文件上传组件和编辑器集成组件：
ng g c spire/uploadFile
ng g c spire/officeJS
执行完成后，src/app/spire/ 目录下会生成 upload-file/ 和 office-js/ 两个组件文件夹。
（2）文件上传组件（upload-file）配置
上传组件负责接收用户拖放或选择的文件，转换为二进制格式后存储到全局状态，再跳转至编辑器页面。
- 定义上传界面样式（
upload-file.css）：
:host {
display: block;
min-height: 100vh;
}
.upload-main {
min-height: 100vh;
display: flex;
justify-content: center;
align-items: center;
background-color: #f5f5f5;
}
.upload-container {
width: 80%;
max-width: 600px;
padding: 40px;
background-color: white;
border-radius: 8px;
box-shadow: 0 4px 12px rgba(0, 0, 0, 0.1);
text-align: center;
}
.drop-area {
border: 2px dashed #ccc;
border-radius: 6px;
padding: 40px;
margin-bottom: 20px;
transition: all 0.3s;
}
.drop-area.highlight {
border-color: #4CAF50;
background-color: #f0fff0;
}
button {
background-color: #4CAF50;
color: white;
border: none;
padding: 10px 20px;
border-radius: 4px;
cursor: pointer;
font-size: 16px;
margin-top: 10px;
}
button:hover {
background-color: #45a049;
}
#fileInput {
display: none; /* 隐藏原生文件选择框 */
}
- 设置上传界面结构（
upload-file.html），支持拖放上传和点击选择文件两种方式：
<main class="upload-main">
<div class="upload-container">
<h2>拖放文件上传</h2>
<div class="drop-area" id="dropArea">
<p>拖放文件到浏览器</p>
<p>或</p>
<button id="browseBtn" #browseBtn (click)="handleButtonClick($event)">选择文件</button>
<input type="file" id="fileInput" #fileInput (change)="handleDrop($event)">
</div>
</div>
</main>
- 上传逻辑实现（
upload-file.ts），处理文件拖放、选择、二进制转换与状态储存：
import { ViewChild, ElementRef, Component, AfterViewInit, inject } from '@angular/core';
import { Router } from '@angular/router';
import { fileStore } from '../../store/index';
@Component({
selector: 'app-upload-file',
imports: [],
templateUrl: './upload-file.html',
styleUrl: './upload-file.css',
})
export class UploadFile implements AfterViewInit {
constructor(private router: Router) { }
// 注入状态管理 Store
store = inject(fileStore);
// 绑定 HTML 元素
@ViewChild('browseBtn') browseBtn!: ElementRef<HTMLButtonElement>;
@ViewChild('fileInput') fileInput!: ElementRef<HTMLInputElement>;
file: File | null = null; // 上传的文件对象
fileUint8Data: Uint8Array | null = null; // 文件二进制数据
// 组件视图初始化完成后执行
ngAfterViewInit() {
this.init();
}
// 初始化拖放事件监听
init() {
// 阻止浏览器默认拖放行为
['dragenter', 'dragover', 'dragleave', 'drop'].forEach(eventName => {
document.addEventListener(eventName, this.preventDefaults, false);
});
// 监听文件拖放事件
document.addEventListener('drop', (e) => {
this.handleDrop.call(this, e);
}, false);
}
// 阻止默认事件
preventDefaults(e: Event) {
e.preventDefault();
e.stopPropagation();
}
// 点击“选择文件”按钮触发原生文件选择框
handleButtonClick(e: Event) {
e.preventDefault();
this.fileInput.nativeElement.click();
}
// 处理文件拖放/选择事件
async handleDrop(e: any) {
// 获取文件对象（拖放或点击选择）
if (e.target && e.target.files) {
this.file = e.target.files[0];
} else if (e.dataTransfer && e.dataTransfer.files) {
this.file = e.dataTransfer.files[0];
}
// 转换文件为 Uint8Array 二进制格式
this.fileUint8Data = await this.handleFile(this.file) as Uint8Array;
// 更新状态到 Store（供编辑器组件使用）
this.store.setFileData(this.file);
this.store.setFileUint8Data(this.fileUint8Data);
// 跳转到编辑器页面
this.openDocument();
}
// 将文件转换为 Uint8Array 二进制数据
handleFile(file: any) {
return new Promise((resolve, reject) => {
const reader = new FileReader();
reader.onload = () => {
const arrayBuffer = reader.result as ArrayBuffer;
const uint8Array = new Uint8Array(arrayBuffer);
resolve(uint8Array);
};
reader.onerror = (error) => reject(error);
reader.readAsArrayBuffer(file); // 以 ArrayBuffer 格式读取文件
});
}
// 跳转到编辑器页面（路由导航）
openDocument() {
this.router.navigate(['spire']);
}
}
（3） 编辑器组件（office-js）配置
编辑器组件负责加载 Spire.OfficeJS 脚本、初始化编辑器实例、配置编辑权限与功能，是核心交互模块。
- 定义编辑器容器 （
office-js.html）：
<div class="form">
<div id="iframeEditor">
</div>
</div>
- 实现编辑器脚本加载、配置初始化、文件解析与事件监听等核心逻辑（
office-js.ts）：
import { Component, AfterViewInit, inject } from '@angular/core';
import { Router } from '@angular/router';
import { fileStore } from '../../store/index';
// 声明 SpireCloudEditor 全局变量（来自产品脚本）
declare const SpireCloudEditor: any;
@Component({
selector: 'app-office-js',
imports: [],
templateUrl: './office-js.html',
styleUrl: './office-js.css',
})
export class OfficeJS implements AfterViewInit {
constructor(private router: Router) { };
// 注入状态管理 Store
store = inject(fileStore);
// 从 Store 获取文件数据
file = this.store.file() as File;
fileUint8Data = this.store.fileUint8Data() as Uint8Array;
originUrl = window.location.origin; // 当前项目域名
Editor: any; // 编辑器实例
config: any; // 编辑器配置
Api: any; // 编辑器 API
// 组件视图初始化完成后执行
ngAfterViewInit() {
this.init();
}
// 初始化校验（无文件则跳回上传页）
init() {
if (!this.file) {
this.router.navigate(['']); // 跳转到上传页面
return;
}
this.loadSrcipt(); // 加载编辑器脚本
}
// 动态加载 SpireCloudEditor.js 脚本
loadSrcipt() {
const script = document.createElement('script');
// 脚本路径需与静态资源部署路径一致
script.setAttribute('src', '/spire.cloud/web/editors/spireapi/SpireCloudEditor.js');
script.onload = () => this.initEditor(); // 脚本加载完成后初始化编辑器
document.head.appendChild(script);
}
// 初始化编辑器配置与实例
initEditor() {
const iframeId = 'iframeEditor'; // 与模板文件中容器 ID 一致
this.initConfig(); // 配置编辑器参数
// 创建编辑器实例
this.Editor = new SpireCloudEditor.OpenApi(iframeId, this.config);
this.Api = this.Editor.GetOpenApi(); // 获取编辑器 API （用于扩展功能）
this.OnWindowReSize(); // 适配窗口大小
}
// 编辑器核心配置（文件信息 + 用户权限 + 编辑器行为）
initConfig() {
this.config = {
"fileAttrs": {
"fileInfo": {
"name": this.file.name, // 文件名
"ext": this.getFileExtension(), // 文件后缀
"primary": String(new Date().getTime()), // 唯一标识（时间戳）
"creator": "",
"createTime": ""
},
"sourceUrl": `${this.originUrl}/files/__ffff_192.168.3.121/${this.file.name}`,
"createUrl": `${this.originUrl}/open`,
"mergeFolderUrl": "",
"fileChoiceUrl": "",
"templates": {}
},
"user": {
"id": "uid-1",
"name": "Jonn",
"canSave": true, // 允许保存文件
},
"editorAttrs": {
"editorMode": this.file.name.endsWith('.pdf') ? 'view' : "edit", // PDF 默认为预览模式
"editorWidth": "100%", // 编辑器宽度
"editorHeight": "100%", // 编辑器高度
"editorType": "document", // 编辑器类型（文档）
"platform": "desktop", // 平台类型（桌面端）
"viewLanguage": "zh", // 界面语言（中文）
"isReadOnly": false, // 非只读模式
"canChat": true, // 启用聊天功能
"canComment": true, // 启用批注功能
"canReview": true, // 启用审阅功能
"canDownload": true, // 允许下载文件
"canEdit": this.file.name.endsWith('.pdf') ? false : true, // PDF 禁止编辑
"canForcesave": true, // 允许强制保存
"embedded": {
"saveUrl": "",
"embedUrl": "",
"shareUrl": "",
"toolbarDocked": "top" // 工具栏置顶
},
// 启用 WebAssembly 加速（提升编辑和转换性能）
"useWebAssemblyDoc": true,
"useWebAssemblyExcel": true,
"useWebAssemblyPpt": true,
"useWebAssemblyPdf": true,
// 许可证配置（若有许可证，填写对应密钥）
"spireDocJsLicense": "",
"spireXlsJsLicense": "",
"spirePresentationJsLicense": "",
"spirePdfJsLicense": "",
"serverless": {
"useServerless": true,
"baseUrl": this.originUrl,
"fileData": this.fileUint8Data, // 核心：传入文件二进制数据
},
"events": {
"onSave": this.onFileSave // 保存回调事件
},
"plugins": {
"pluginsData": []
}
}
};
}
// 窗口大小适配
OnWindowReSize() {
const wrapEl = document.getElementsByClassName("form") as any;
if (wrapEl.length) {
wrapEl[0].style.height = window.innerHeight + "px";
window.scrollTo(0, -1);
}
}
// 获取文件后缀名
getFileExtension() {
const filename = this.file.name.split(/[\\/]/).pop() as String;
return filename.substring(filename.lastIndexOf('.') + 1).toLowerCase() || '';
}
// 自定义保存逻辑（可根据需求扩展）
onFileSave(data: any) {
console.log('保存的数据：', data);
}
}
4. 路由配置 （实现页面跳转）
为上传页面和编辑器页面配置路由，实现页面跳转。
- 修改路由规则（
app.routes.ts），配置上传页和编辑器页的路由：
import { Routes } from '@angular/router';
import { UploadFile } from './spire/upload-file/upload-file';
import { OfficeJS } from './spire/office-js/office-js';
export const routes: Routes = [
{ path: '', component: UploadFile }, // 默认路由：文件上传页
{ path: 'spire', component: OfficeJS } // 编辑器路由：/spire
];
- 注入路由配置（
app.config.ts），确保路由配置生效：
import { ApplicationConfig, provideBrowserGlobalErrorListeners, provideZoneChangeDetection } from '@angular/core';
import { provideRouter } from '@angular/router';
import { routes } from './app.routes';
export const appConfig: ApplicationConfig = {
providers: [
provideBrowserGlobalErrorListeners(),
provideZoneChangeDetection({ eventCoalescing: true }),
provideRouter(routes), // 注入路由
]
};
- 设置路由出口（
app.html），确保页面正确渲染：
<main class="app-main">
<router-outlet /> <!-- 路由出口：渲染当前路由对应的组件 -->
</main>
启动运行与功能验证
1. 启动项目
保存所有修改后，在项目根目录（F:\angular\spireOfficeJS）执行以下命令，重启开发服务器：
npm run start
2. 功能验证
- 访问上传页面：浏览器打开 http://localhost:4200/，显示 “拖放文件上传” 界面，支持两种上传方式：
- 拖放文件到浏览器指定区域；
- 点击 “选择文件” 按钮，从本地上传文档（支持 Word、Excel、PPT、PDF 等格式）。
- 下载 / 转换文档：编辑完成后，点击编辑器顶部 “文件→“下载为”，可将文档导出为PDF、TXT、RTF、HTML等多种格式。
常见问题解答
Q1：编辑器加载失败，页面空白？
- 排查路径：确认
SpireCloudEditor.js 路径与 office-js.ts 中 script.src 一致
- 浏览器兼容：升级至 Chrome 100+ 等支持 WebAssembly 的浏览器
Q2：安装 NgRx 依赖时提示 peer dependency 冲突？
- Angular 版本与 NgRx 版本存在依赖约束差异，可使用 --legacy-peer-deps 强制兼容安装：
npm install @ngrx/signals @ngrx/store --legacy-peer-deps
Q3：启动项目时，浏览器控制台报错，提示找不到 zone.js 模块？
- 原因：初始化项目时误选 “zoneless” 模式（无
zone.js 依赖），但 Spire.OfficeJS 依赖 zone.js 处理异步事件。
- 解决方案：
- 先安装 zone.js 依赖：
npm install zone.js --save
- 再打开
src/main.ts，在文件顶部添加导入：import 'zone.js';
- 最后重新启动项目，确认报错消失。
完整示例下载
下载 Angular 集成 Spire.OfficeJS 的完整示例项目，包含所有配置文件与代码，直接运行即可体验功能。
点击下载
临时许可证申请
如需去除水印或解锁全部功能，可联系我们获取 30 天临时许可证。
