跳到主要内容

DocEditor

DocsAPI.DocEditor 是 ONLYOFFICE 文档 API 的主类。它是创建、配置和管理嵌入网页的文档编辑器的入口点。

DocsAPI​

DocsAPI 是由 ONLYOFFICE 文档 API 脚本提供的全局命名空间：

<script type="text/javascript" src="https://documentserver/web-apps/apps/api/documents/api.js"></script>

其中 documentserver 是安装了 ONLYOFFICE 文档 的服务器名称。

脚本加载后，DocsAPI 对象将在 window 上可用，并公开 DocEditor 构造函数。

提示

您可以在打开文档之前预加载静态资源（HTML、CSS、JS、字体）到浏览器缓存中，以加快首次加载速度。

构造函数​

要创建编辑器实例，请使用两个参数调用 DocEditor 构造函数——编辑器将渲染到的现有 HTML 元素的 id 属性，以及配置对象：

const docEditor = new DocsAPI.DocEditor("placeholder", config);
参数类型描述
idstring编辑器将渲染到的现有 HTML 元素的 id 属性（例如，"placeholder" 对应 <div id="placeholder">）。
configobject包含文档、编辑器和事件参数的配置对象。

在 iframe 中渲染​

构造函数不会在占位符元素内部渲染编辑器，而是用一个从 ONLYOFFICE 文档 服务器加载编辑器的 <iframe> 替换该元素：

<!-- 调用构造函数之前 -->
<div id="placeholder"></div>

<!-- 编辑器加载之后 -->
<iframe name="frameEditor" width="100%" height="100%" frameborder="0" allowfullscreen
        allow="autoplay; camera; microphone; display-capture; clipboard-write;"
        src="https://documentserver/web-apps/apps/documenteditor/main/index.html">
</iframe>

iframe 路径中的应用程序取决于 documentType 参数，其后的目录取决于 type 参数。

为什么使用 iframe​

  • 隔离性。 编辑器自带样式表、脚本、字体和 WebAssembly 模块。若将它们渲染到宿主页面的 DOM 中，宿主页面的 CSS 和组件框架会与编辑器的相互冲突。
  • 独立更新。 编辑器由 ONLYOFFICE 文档 提供，因此更新编辑器无需重新构建或重新部署您的应用程序。
  • 安全边界。 编辑器运行在 ONLYOFFICE 文档 的源（origin）上。同源策略使宿主页面与编辑器无法访问彼此的 DOM 和 JavaScript 上下文，跨越该边界的所有数据都通过显式的 postMessage 通道传递。

这对宿主页面意味着什么​

  • 占位符元素是被替换的，而不是被填充的。在其上设置的类、内联样式和其他属性会在编辑器加载时丢失。请将样式应用到占位符外层的包装元素上。
  • 使用 width 和 height 参数设置编辑器尺寸，或者设置包装元素的尺寸并让这两个参数保持默认值 100%。
  • 宿主页面的样式表和组件库无法作用于编辑器内部的任何内容，页面也无法读取 iframe 的 contentDocument。
  • 与编辑器的所有交互都通过方法和事件进行，API 脚本通过 postMessage 传输它们。
  • 该 iframe 创建时带有 allowfullscreen 属性和上面列出的 allow 属性。如果宿主页面本身嵌入在 iframe 中，则外层 iframe 必须委派相同的权限。
  • destroyEditor 方法会将 iframe 替换回一个空的 <div> 元素，该元素仅保留原有的 id 属性。

自定义和样式​

由于宿主页面的 CSS 无法作用于 iframe 内部，编辑器的外观通过配置对象进行配置。编辑器的布局保持不变，但您可以更改其品牌标识、颜色以及向用户显示的界面元素集合：

实例方法​

构造函数返回一个 docEditor 对象。使用它来调用在运行时控制编辑器的方法——下载文件、管理版本历史、更新共享设置等：

const docEditor = new DocsAPI.DocEditor("placeholder", config);

// 稍后，在处理事件或用户操作时：
docEditor.downloadAs("pdf");
docEditor.destroyEditor();

有关完整列表，请参阅方法。

事件​

事件是在 config.events 部分传递的函数。它们允许集成商响应编辑器操作——例如，当文档准备就绪时、当用户请求保存时或当协作更改到达时：

const config = {
  events: {
    onAppReady() {
      console.log("Editor is ready");
    },
    onDocumentStateChange(event) {
      console.log("Document modified:", event.data);
    },
  },
};

const docEditor = new DocsAPI.DocEditor("placeholder", config);

有关可用事件的完整列表，请参阅事件。

最小示例​

const config = {
  document: {
    fileType: "docx",
    key: "Khirz6zTPdfd7",
    title: "Example Document Title.docx",
    url: "https://example.com/url-to-example-document.docx",
  },
  documentType: "word",
  editorConfig: {
    callbackUrl: "https://example.com/url-to-callback",
  },
};

const docEditor = new DocsAPI.DocEditor("placeholder", config);

将 example.com 替换为您的文档存储服务的主机地址。callbackUrl 是您服务器上的端点，ONLYOFFICE 文档 会向该端点发送文档状态更新和已保存的文件。请参阅工作原理部分，了解有关 ONLYOFFICE 文档 服务客户端-服务器交互的更多信息。

有关包含所有可用部分和参数的完整配置结构，请参阅配置概述。

TypeScript 支持

安装 @onlyoffice/doceditor-types 以获取配置对象、DocEditor 方法和事件的完整 IntelliSense 和类型检查。该包的版本号与 ONLYOFFICE 文档版本号保持一致。

警告

当您的文档服务器启用了 JWT 验证（默认配置）时，config 必须包含匹配的 token。请使用您的文档服务器的 JWT 密钥对配置进行签名。