5 分钟上手 Onlyoffice 插件开发

缘起于进行了一次在线 Office 解决方案的调研，对比了 Office365、可道云、WPS Office、PageOffice 等厂商，最终敲定了使用 Onlyoffice，故整理了一份 Onlyoffice 从零开始系列教程，这是第三篇。

本篇文章提到的代码片段和预览效果均在 demo-onlyoffice Github，克隆后对照查看会有更好的阅读体验。

Onlyoffice 具有强大的插件机制，并提供了完整的插件开发文档，可以完全根据业务定制插件。

Onlyoffice 插件基本结构

我们先来看下插件目录结构：

.
├── config.json      # 插件配置文件
├── icon.png         # 插件图标
├── [email protected]
├── index.html       # 插件入口文件
├── main.js          # 插件主程序入口文件
└── translations     # 国际化配置
    └── zh-CN.json

如上图，插件结构非常简单，里面主要是 config.json、index.html 和 main.js。

一个常规插件的 config.json 配置项如下：

{
  // 插件名称
  "name": "字体替换",
  // 插件 id，固定格式
  "guid": "asc.{11700c35-1fdb-4e37-9edb-b31637139601}",
  "variations": [
    {
      // 插件描述
      "description": "数字字体替换",
      // 这个是页面地址，外部如果不是 index.html，也需要在这里改一下
      "url": "index.html",
      // 插件图标，建议 1 倍图和 2 倍图都配置下
      "icons": [
        "icon.png",
        "[email protected]"
      ],
      // 仅预览模式时，插件是否要启用，默认值：false
      "isViewer": false,
      // 插件支持的文档类型，可选值：word、cell、slide
      "EditorsSupport": [
        "word"
      ],
      // 插件是否具有 UI 视图
      "isVisual": true,
      // 插件是否以弹框形式打开
      "isModal": false,
      // 指定要从编辑器中传递的数据类型，可选值：text、html、ole、desktop、destop-external、none
      "initDataType": "none",
      // 插件启动时从编辑器传递的数据，与 initDataType 配合使用，如果 initDataType 设置 text 则插件启动时会收到当前编辑器所选中的文本
      "initData": "",
      // 插件可使用的按钮列表
      "buttons": [],
      // 需要用到的事件需要在这里先注册
      "events" : [
        "onClick"
      ]
    }
  ]
}

一个常规插件的 index.html 结构内容如下：

<!DOCTYPE html>
<html lang="en">
  <head>
    <meta charset="utf-8" />
    <meta name="viewport" content="width=device-width, initial-scale=1" />
    <title></title>
    <!-- 可以引入外部的 js 脚本 -->
    <script src="https://ajax.googleapis.com/ajax/libs/jquery/2.2.2/jquery.min.js"></script>
    <!-- 这个是插件 js，基本是必须要引入的 -->
    <script src="https://onlyoffice.github.io/sdkjs-plugins/v1/plugins.js"></script>
    <!-- 这里的 main.js 就是插件结构里面的 main.js -->
    <script src="main.js"></script>
  </head>

  <body>
    <!-- 这里是 html 区域，H5 的标签都可以在这里使用，设置 id 然后到 main.js 里面绑定事件 -->
    <!-- 操作 -->
    <button id="button">按钮</button>
  </body>
</html>

一个常规插件的 main.js 结构内容如下：

(function(window, undefined) {
  window.Asc.plugin.init = function(initData) {
    // 自定义逻辑
    // ...

    // 在插件 iframe 之外释放鼠标按钮时调用的函数
    window.Asc.plugin.onExternalMouseUp = function() {
      var event = document.createEvent('MouseEvents')
      event.initMouseEvent('mouseup', true, true, window, 1, 0, 0, 0, 0, false, false, false, false, 0, null)
      document.dispatchEvent(event)
    }

    window.Asc.plugin.button = function(id) {
      // 被中断或关闭窗口
      if (id === -1) {
        this.executeCommand('close', '')
      }
	  }
  }
})(window, undefined)

以上是 Onlyoffice 插件的 JS 模板写法，每一个插件初始化都可以用这个结构，然后再补充自定义逻辑即可。

这里要注意，插件里面不建议直接写 ES6 的语法，可能会不兼容，除非是配置了 babel 来转换。

实现一个最简单的 Onlyoffice 插件

这里我们实现一个点击按钮向文档里面添加一个「Hello world」文本的插件。config.json、index.html 内容都比较简单，主要看下 JS 里面的实现：

(function(window, undefined) {
  window.Asc.plugin.init = function(initData) {
    var me = this
    $('#addText').click(function() {
      // 官方提供的回调函数，所有操作文档的 API 都可以在这里面使用
      me.callCommand(function() {
        try {
          // 获取文档对象
          var oDocument = Api.GetDocument()
          // 生成一个新的段落对象
          var oParagraph = Api.CreateParagraph()
          // 往段落里面添加一个字符串文本
          oParagraph.AddText('Hello world')
          // 最后往文档里面添加一个段落对象
          oDocument.Push(oParagraph)
        } catch (error) {
          console.error(error)
        }
      }, false, true, function () {
        console.log('ok')
      })
    })

    // 在插件 iframe 之外释放鼠标按钮时调用的函数
    window.Asc.plugin.onExternalMouseUp = function() {
      var event = document.createEvent('MouseEvents')
      event.initMouseEvent('mouseup', true, true, window, 1, 0, 0, 0, 0, false, false, false, false, 0, null)
      document.dispatchEvent(event)
    }

    window.Asc.plugin.button = function(id) {
      // 被中断或关闭窗口
      if (id === -1) {
        this.executeCommand('close', '')
      }
	  }
  }
})(window, undefined)

然后将插件添加到 Onlyoffice 配置项：

editorConfig.plugins = {
  autostart: [],
  pluginsData: ['http://IP/static/plugins/plugin-hello/config.json']
}

最终实现效果如下：

当前示例页面访问路径：http://127.0.0.1:3001/onlyoffice/document/plugin

Onlyoffice 插件常用 API

// 获取文档对象，几乎写插件都会用到
var oDocument = Api.GetDocument()

// 创建一个段落对象
var oParagraph = Api.CreateParagraph()

// 创建一个文本对象
var oRun = Api.CreateRun()

// 添加文本
oParagraph.AddText()
oDocument.AddText()

// 节点 Push 方法
oParagraph.Push()
oDocument.Push()

// 选中当前节点
oRun.Select()

// 字体加粗
oRun.SetBold(true)
// 设置字体
oRun.SetFontFamily('微软雅黑')
// 设置字体大小
oRun.SetFontSize(30)
// 设置背景色
oRun.SetHighlight(255, 255, 0)

// ...