如何在 HTML 页面中嵌入 Office 文档编辑器

sales@e-iceblue.com

028-81705109

2790765778

微信扫一扫

论坛

Spire.Cloud 纯前端文档控件

帮助文档
使用配置教程
如何在 HTML 页面中嵌入 Office 文档编辑器

如何在 HTML 页面中嵌入 Office 文档编辑器

在 HTML 页面中嵌入 Web 版 Office 文档编辑器的教程

现代 Web 应用程序越来越多地需要在浏览器中直接查看和编辑 Word、Excel 和 PowerPoint 文件。相比将用户跳转到新页面或外部应用，许多开发者更倾向于将 Office 编辑器直接嵌入网页，使其成为现有界面的一部分，从而提供更加流畅的在线文档处理体验。

然而，从零开始构建一个功能完善的在线文档编辑器并不容易，通常需要处理文档渲染、格式兼容性、编辑交互以及响应式 UI 集成等复杂问题。借助 Spire.OfficeJS，开发者可以使用 JavaScript 快速将基于浏览器的 Office 编辑器集成到 HTML 页面中，而无需在客户端设备上安装 Microsoft Office 等文档处理工具。

本文将演示如何在 HTML 中嵌入文档编辑器，包括页面布局设计、编辑器初始化以及动态文档加载，并提供完整的实用示例。

为什么要在网页中嵌入 Office 编辑器？
前置条件
集成的基本页面布局
将 Office 编辑器嵌入容器
动态加载和切换文档
自定义编辑器行为
将编辑器集成到现有业务系统
框架集成（React、Vue、Angular）
常见集成问题
总结
常见问题

为什么要在网页中嵌入 Office 编辑器？

将文档编辑器作为页面布局的一部分嵌入，可以实现无缝工作流程并提升用户体验。常见应用场景包括：

文档管理系统（DMS），用户无需离开界面即可查看和编辑文件
集成文件编辑功能的 CRM 或 ERP 平台
需要实时文档编辑的在线协作工具
具有文档预览功能的内部业务仪表板

用户可以直接在当前 Web 界面中处理文档，而无需在单独的应用程序或专用页面中打开文档。

嵌入式与全屏编辑器

有两种常见的集成方式：

方式	描述
全屏编辑器	整个页面专用于文档编辑
嵌入式编辑器	编辑器作为更大 UI 的一部分集成

本教程重点介绍嵌入式方法，即文档编辑器与侧边栏、文件列表、导航菜单和其他应用程序组件协同工作。

环境准备

在集成编辑器之前，请确保具备以下条件：

配置服务器环境

下载并解压 Spire.OfficeJS

下载 Spire.OfficeJS 包并将其解压到本地目录。
启动 Spire.OfficeJS 后端服务
```
cd Spire.OfficeJS.Windows_10.11.4
run_servers.bat
```
这将在 http://localhost:8001 上启动编辑器服务
启动示例服务器（提供示例文档）示例服务器运行在 http://localhost:3000，示例文档位于 /public/samples/

如需了解如何在 JavaScript 应用程序中安装和部署 Spire.OfficeJS，请参阅：如何在 JavaScript 中部署 Spire.OfficeJS

环境要求

可从浏览器访问的文档文件
支持 WebAssembly 的现代浏览器

注意： 以下代码示例使用 localhost 地址进行本地开发和测试。在生产环境中，请将其替换为实际的服务器 URL 或域名。

集成的基本页面布局

第一步是设计一个布局，使编辑器仅占据页面的一部分。以下是带有侧边栏和编辑器区域的常见结构：

<!DOCTYPE html>
<html>
<head>
  <title>文档编辑器集成</title>
  <style>
    .app-container {
      display: flex;
      height: 100vh;
    }

    .sidebar {
      width: 250px;
      border-right: 1px solid #ddd;
      padding: 10px;
      background: #f5f5f5;
    }

    .editor-container {
      flex: 1;
      position: relative;
    }
  </style>
</head>
<body>
  <div class="app-container">
    <div class="sidebar">
      <h3>文档列表</h3>
      <ul>
        <li onclick="openDocument('http://localhost:3000/public/samples/sample.docx', 'docx')">示例文档.docx</li>
        <li onclick="openDocument('http://localhost:3000/public/samples/sample.xlsx', 'xlsx')">示例电子表格.xlsx</li>
        <li onclick="openDocument('http://localhost:3000/public/samples/sample.pptx', 'pptx')">示例演示文稿.pptx</li>
      </ul>
    </div>

    <div class="editor-container" id="editor"></div>
  </div>
</body>
</html>

一个简单的嵌入式文档管理界面在打开文档前可能如下所示：

文档管理界面

布局说明

侧边栏显示带有可点击文档名称的文件列表
编辑器容器是一个弹性项目，将托管文档编辑器
编辑器使用 flex: 1 填充剩余空间

这种结构反映了真实世界的应用程序布局，而非简单的演示页面。

将 Office 编辑器嵌入容器

加载 Spire.OfficeJS 脚本并在指定容器内初始化编辑器：

<script src="http://localhost:8001/web/editors/spireapi/SpireCloudEditor.js"></script>

<script>
function initEditor() {
  const config = {
    user: {
      id: 'user1',
      name: '演示用户'
    },
    fileAttrs: {
      sourceUrl: "http://localhost:3000/public/samples/sample.docx",
      fileInfo: {
        ext: "docx",
        name: "示例文档.docx"
      }
    },
    editorAttrs: {
      editorType: "document",
      editorMode: "edit",
      editorWidth: "100%",
      editorHeight: "100%",
      platform: "desktop",
      viewLanguage: "zh",
      canEdit: true,
      canDownload: true,
      canForcesave: true,
      useWebAssemblyDoc: true,
      useWebAssemblyExcel: true,
      useWebAssemblyPpt: true,
      useWebAssemblyPdf: true,
      serverless: {
        useServerless: true,
        baseUrl: "http://localhost:8001"
      },
      embedded: {
        saveUrl: "",
        toolbarDocked: 'top'
      },
      events: {
        onDocumentReady: function() {
          console.log('文档已就绪');
        },
        onError: function(event) {
          console.error('编辑器错误:', event);
        },
        onSave: function(data) {
          console.log('文档已保存', data);
          if (data && data.data && data.data.length >= 2) {
            downloadFile(data.data[1], data.data[0]);
          }
        }
      }
    }
  };

  new SpireCloudEditor.OpenApi("editor", config);
}

function downloadFile(file, fileName) {
  const a = document.createElement('a');
  const url = URL.createObjectURL(file);
  a.href = url;
  a.download = fileName;
  document.body.appendChild(a);
  a.click();
  document.body.removeChild(a);
  URL.revokeObjectURL(url);
}

initEditor();
</script>

初始化后，嵌入式 Office 编辑器将直接加载到目标容器中：

嵌入式编辑器

为帮助快速入门，可以下载本文中使用的完整可运行 HTML 示例：

下载嵌入式编辑器示例

注意：在打开示例编辑器之前，请先启动 Spire.OfficeJS 服务。以上下载演示示例使用 window.location.hostname 动态检测当前主机，因此应通过 HTTP 服务器打开。如需直接在浏览器中预览文件，请将其替换为固定的主机地址。

配置详解

user：必需的用户配置，包含自定义设置
fileAttrs：文档源 URL 和文件元数据
editorAttrs：编辑器行为，包括模式、尺寸和语言

编辑器在 ID 为 "editor" 的指定容器元素内渲染，使其能够作为 UI 组件运行，而不是接管整个页面。

可以通过添加自定义字体来进一步定制编辑器体验，以支持品牌化或多语言文档。更多详情，请参阅：如何向 Office 编辑器添加自定义字体

动态加载和切换文档

在实际应用中，用户需要动态打开不同的文件。可以通过使用新配置重新初始化编辑器来实现：

let editorInstance = null;

function openDocument(sourceUrl, ext) {
  const fileName = sourceUrl.split('/').pop();
  
  if (editorInstance) {
    editorInstance.destroy();
  }
  
  const container = document.getElementById("editor");
  container.innerHTML = "";
  
  const config = {
    user: {
      id: 'user1',
      name: '演示用户'
    },
    fileAttrs: {
      sourceUrl: sourceUrl,
      fileInfo: {
        ext: ext,
        name: fileName
      }
    },
    editorAttrs: {
      editorType: getEditorType(ext),
      editorMode: "edit",
      editorWidth: "100%",
      editorHeight: "100%",
      platform: "desktop",
      viewLanguage: "zh",
      canEdit: true,
      canDownload: true,
      canForcesave: true,
      useWebAssemblyDoc: true,
      useWebAssemblyExcel: true,
      useWebAssemblyPpt: true,
      useWebAssemblyPdf: true,
      serverless: {
        useServerless: true,
        baseUrl: "http://localhost:8001"
      },
      embedded: {
        saveUrl: "",
        toolbarDocked: 'top'
      },
      events: {
        onSave: function(data) {
          if (data && data.data && data.data.length >= 2) {
            downloadFile(data.data[1], data.data[0]);
          }
        }
      }
    }
  };

  editorInstance = new SpireCloudEditor.OpenApi("editor", config);
}

function getEditorType(ext) {
  const extLower = ext.toLowerCase();
  switch (extLower) {
    case 'docx':
    case 'doc':
    case 'rtf':
    case 'txt':
    case 'odt':
      return 'document';
    case 'xlsx':
    case 'xls':
    case 'csv':
    case 'ods':
      return 'spreadsheet';
    case 'pptx':
    case 'ppt':
    case 'odp':
      return 'presentation';
    default:
      return 'document';
  }
}

工作原理

点击侧边栏中的文件会触发 openDocument，传入文件 URL 和扩展名
销毁之前的编辑器实例并清空容器
编辑器使用选定的文档重新加载
无需刷新页面，保持应用程序状态

此模式对于构建交互式文档管理系统至关重要。

文档切换的最佳实践

在动态切换文档时，正确的清理可以避免 UI 问题：

错误处理和加载状态

始终使用 try-catch 进行错误处理，并考虑添加加载指示器：

let editorInstance = null;

async function openDocument(sourceUrl, ext) {
  try {
    if (editorInstance) {
      editorInstance.destroy();
    }
    
    const container = document.getElementById("editor");
    container.innerHTML = "";
    
    const config = { /* ... 配置 ... */ };
    editorInstance = new SpireCloudEditor.OpenApi("editor", config);
  } catch (error) {
    console.error('加载文档失败:', error);
  }
}

关键点：

在创建新实例之前始终销毁旧实例
清空容器元素以防止 UI 冲突
使用 try-catch 实现健壮的错误处理

自定义编辑器行为

可以使用 editorAttrs 中的配置选项微调编辑器的行为。

只读模式

将编辑器设置为仅查看模式：

editorAttrs: {
  editorMode: "view",
  isReadOnly: true
}

控制用户权限

限制特定操作：

editorAttrs: {
  canEdit: false,
  canDownload: false,
  canComment: true,
  canPrint: true
}

更改 UI 语言

通过设置界面语言支持国际化：

editorAttrs: {
  viewLanguage: "en"
}

支持的语言包括英语（"en"）和中文（"zh"）。

配置保存功能

在无服务器模式下，保存通过 onSave 事件回调处理：

editorAttrs: {
  embedded: {
    saveUrl: "",  // 在无服务器模式下保持为空
    toolbarDocked: 'top'
  },
  events: {
    onSave: function(data) {
      console.log('文档已保存', data);
      if (data && data.data && data.data.length >= 2) {
        // data.data[0] = 文件名, data.data[1] = 文件 blob
        downloadFile(data.data[1], data.data[0]);
      }
    }
  }
}

function downloadFile(file, fileName) {
  const a = document.createElement('a');
  const url = URL.createObjectURL(file);
  a.href = url;
  a.download = fileName;
  document.body.appendChild(a);
  a.click();
  document.body.removeChild(a);
  URL.revokeObjectURL(url);
}

当用户点击保存时，文档将自动下载到本地计算机。

动态协议配置

为支持 HTTP 和 HTTPS 环境，使用动态协议检测：

const currentHost = window.location.hostname;
const currentProtocol = window.location.protocol;

const baseUrl = `${currentProtocol}//${currentHost}:8001`;
const exampleBaseUrl = `${currentProtocol}//${currentHost}:3000`;

这可以防止在页面通过 HTTPS 提供服务时出现混合内容错误。

上传本地文件

用户可以上传本地文档进行编辑：

<input type="file" id="fileInput" accept=".docx,.xlsx,.pptx,.doc,.xls,.ppt" 
       onchange="handleFileUpload(event)">

async function handleFileUpload(event) {
  const file = event.target.files[0];
  const fileName = file.name;
  const ext = fileName.split('.').pop().toLowerCase();
  
  const fileData = await new Promise((resolve) => {
    const reader = new FileReader();
    reader.onload = (e) => resolve(e.target.result);
    reader.readAsArrayBuffer(file);
  });
  
  const config = {
    user: {
      id: 'user1',
      name: '演示用户'
    },
    fileAttrs: {
      sourceUrl: 'upload://' + fileName,
      fileInfo: { ext, name: fileName }
    },
    editorAttrs: {
      editorType: getEditorType(ext),
      serverless: {
        useServerless: true,
        baseUrl: baseUrl,
        fileData: fileData  // 直接传递文件数据
      }
    }
  };
  
  editorInstance = new SpireCloudEditor.OpenApi("editor", config);
}

将编辑器集成到现有业务系统

在大多数实际场景中，在线文档编辑器并非整个应用程序，而是作为大型业务系统中的一个模块运行。

典型的集成模式包括：

CRM 系统，包含合同编辑和提案生成功能
ERP 系统，包含发票审查和报告修改功能
文档管理系统（DMS），包含嵌入式预览和编辑工作流
客户门户，包含可下载和可编辑的表单
内部协作平台，结合文档编辑与聊天、评论和版本控制

由于基于浏览器的 Office 编辑器挂载到标准 DOM 容器中，它可以与以下内容无缝共存：

侧边栏和导航菜单
文件树和文件夹结构
多文档编辑的标签页系统
聊天面板和评论线程
仪表板和分析小部件

这种模块化架构允许开发者构建丰富的以文档为中心的应用程序，而不会影响现有的 UI 模式或用户工作流。

框架集成（React、Vue、Angular）

虽然示例使用纯 JavaScript，但相同的概念也适用于现代框架。关键原则保持不变：在组件挂载后初始化编辑器，并将其渲染到 DOM 容器中。

React

useEffect(() => {
  new SpireCloudEditor.OpenApi("editor-container", config);
}, []);

Vue

mounted() {
  new SpireCloudEditor.OpenApi("editor-container", config);
}

Angular

ngAfterViewInit(): void {
  new SpireCloudEditor.OpenApi("editor-container", config);
}

有关完整的框架特定设置和部署说明，请参阅专门的集成指南：

常见集成问题

以下是开发者遇到的常见问题及其解决方案：

编辑器无法加载

原因：后端服务未运行或脚本 URL 不正确
解决方案：验证服务是否在端口 8001 上运行，并使用正确的脚本路径：http://localhost:8001/web/editors/spireapi/SpireCloudEditor.js

脚本加载失败（CORS 错误）

原因：直接使用 file:// 协议打开 HTML 文件
解决方案：启动本地 HTTP 服务器（python -m http.server 8080 或 npx http-server -p 8080）并通过 http://localhost:8080/your-file.html 访问

文件加载失败

原因：文档 URL 无法访问或被 CORS 阻止
解决方案：确保 sourceUrl 可通过 HTTP 公开访问。将占位符 URL（如 https://example.com/）替换为真实可访问的文档 URL

/doc/*/c/info 端点出现 404 错误

原因：editorAttrs 中缺少 serverless 配置
解决方案：在配置中添加 serverless 和 useWebAssembly* 设置

多个编辑器重叠

原因：创建新实例之前未正确销毁旧编辑器实例
解决方案：在创建新实例之前始终调用 editorInstance.destroy()

编辑器容器空白

原因：浏览器缓存问题或缺少依赖项
解决方案：清除浏览器缓存，尝试无痕模式，或检查浏览器控制台中的错误

服务连接被拒绝

原因：所需端口被阻止或服务未启动
解决方案：确保端口 8001 已打开且 Spire.OfficeJS 服务正在运行

编辑器溢出容器

原因：宽度/高度设置不正确
解决方案：将 editorWidth 和 editorHeight 设置为 "100%"，并确保容器具有定义的尺寸

总结

本文演示了如何使用 Spire.OfficeJS 将基于 Web 的 Office 文档编辑器嵌入现有 HTML 页面。通过将编辑器视为模块化组件，开发者可以将文档编辑功能直接集成到 Web 应用程序中，而无需将用户重定向到单独的页面。

这种方法能够构建丰富的文档管理界面，使编辑器与导航、文件列表和其他 UI 组件共存。通过适当的配置，嵌入式编辑器提供与全屏解决方案相同的功能强大的特性，同时保持无缝的用户体验。

Spire.OfficeJS 支持多种文档格式，包括 Word（DOCX）、Excel（XLSX）和 PowerPoint（PPTX），使其成为基于 Web 的文档处理需求的全面解决方案。

如果希望在真实项目环境中测试 Spire.OfficeJS，可以在此处申请免费临时许可证：申请临时许可证

常见问题

如何在网页中嵌入文档编辑器？

可以通过在特定的 HTML 容器元素内初始化 SpireCloudEditor.OpenApi，并配置文档源和编辑器设置来嵌入文档编辑器。

嵌入是否需要安装 Microsoft Office？

不需要。Spire.OfficeJS 使用 WebAssembly 进行浏览器端文档处理，同时依赖后端服务提供编辑器界面和相关资源。客户端计算机上无需安装 Microsoft Office。

是否可以将编辑器集成到 React 或 Vue 应用程序中？

可以。编辑器可以集成到任何 JavaScript 框架中，通过在组件生命周期（如 React 中的 useEffect 或 Vue 中的 mounted）将其挂载到 DOM 元素来实现。

支持哪些文档格式？

Spire.OfficeJS 支持 Word 文档（DOCX、DOC）、Excel 电子表格（XLSX、XLS）和 PowerPoint 演示文稿（PPTX、PPT），以及 PDF 查看。

如何处理文档保存操作？

在无服务器模式下，在 editorAttrs.events 中配置 onSave 事件回调。当用户保存时，回调接收文件数据，可以自动下载或进一步处理。

如何在 Spire.OfficeJS 前端编辑器中添加自定义字体

返回顶部

如何在 HTML 页面中嵌入 Office 文档编辑器

为什么要在网页中嵌入 Office 编辑器？

嵌入式与全屏编辑器

环境准备

配置服务器环境

环境要求

集成的基本页面布局

布局说明

将 Office 编辑器嵌入容器

配置详解

动态加载和切换文档

工作原理

文档切换的最佳实践

自定义编辑器行为

只读模式

控制用户权限

更改 UI 语言

配置保存功能

动态协议配置

上传本地文件

将编辑器集成到现有业务系统

框架集成（React、Vue、Angular）

React

Vue

Angular

常见集成问题

编辑器无法加载

脚本加载失败（CORS 错误）

文件加载失败

/doc/*/c/info 端点出现 404 错误

多个编辑器重叠

编辑器容器空白

服务连接被拒绝

编辑器溢出容器

总结

常见问题

如何在网页中嵌入文档编辑器？

嵌入是否需要安装 Microsoft Office？

是否可以将编辑器集成到 React 或 Vue 应用程序中？

支持哪些文档格式？

如何处理文档保存操作？

相关文章