当前位置： 首页 > news >正文

如何开发ONLYOFFICE协作空间插件：完整教程

news 来源：原创 2025/6/10 9:40:20

在当今这个注重效率与协作的时代，生产力工具也需不断进化。协作空间插件为用户提供了更现代化的文档管理与交互方式。在本文中，我们将以官方插件示例为基础，带你一步步创建自己的协作空间插件。

什么是 ONLYOFFICE 协作空间

ONLYOFFICE 协作空间供了一个基于房间的文档协作环境，旨在提升办公文档和其他内容的协作效率，让用户能够与同事、客户、合作伙伴、承包商、赞助商等多方人员顺畅协作。设置灵活的访问权限和用户角色设置，可支持用户对整个或单独房间的访问权限调整。

使用 ONLYOFFICE 协作空间，您可以：

  • 创建、编辑和分享文档、电子表格、演示文稿、表单、PDF 和电子书。查看多媒体文件。
  • 邀请用户进行协作：实时地对文档进行共同协作，跟踪更改，使用内置聊天工具、在文档中进行沟通。
  • 创建协作空间，为团队成员设置灵活的访问权限：查看、审阅、填写表单、编辑等，并查看所有空间内的活动记录。
  • 创建和管理自定义房间：对于不同目的和用途，可选择创建协作房间、公共房间、虚拟数据房间等多种房间类型，还可将房间设置为可重复使用的模板，便于快速生成新房间。
  • 在专用空间中存储和管理个人文档。
  • 畅享高级安全功能：备份和恢复、双因素身份验证、IP 安全、审计跟踪等；符合行业特定标准、优先访问安全和稳定性修复程序。
  • 自定义品牌选项：选择不同的颜色样式，更换logo、标题和域名，打造更适合您的公司品牌。
  • 配置集成功能：连接外部服务和存储。目前，第三方存储只能用于执行备份

对于企业来说，保证安全且高效的办公协作至关重要。因此，许多企业会选择本地部署或将 ONLYOFFICE 协作空间进行商业开发，集成到更多的平台或系统中。

关于 ONLYOFFICE 协作空间插件 SDK

ONLYOFFICE 协作空间插件 SDK 是一个基于 TypeScript 的 npm 包，提供丰富的接口，帮助您开发自定义插件并集成到协作空间门户中。插件的开发生命周期包括规划、开发、测试和部署。

为帮助您更好地理解使用方式，我们提供了一个包含示例插件的代码库。接下来，我们将以这些示例为基础，详细介绍插件开发的完整流程。

规划

明确插件的用途，思考其使用场景以及需要集成的第三方服务。

步骤 1. 安装所有必要的软件包和程序

  • ONLYOFFICE 协作空间本地安装
  • @onlyoffice/docspace-plugin-sdk npm 软件包

要全局安装 @onlyoffice/docspace-plugin-sdk npm 软件包，请使用以下命令：

 npm i -g @onlyoffice/docspace-plugin-sdk

步骤 2：设计插件的工作方式

选择允许您向协作空间添加必要功能的服务。

例如，在我们的插件示例中，我们使用：

  • AssemblyAI 将音频和视频文件中的语音转换为文本；

  • ConvertAPI 将文档、电子表格、演示文稿和表单转换为 PDF；

  • Draw.io用于创建、编辑和插入专业图表。

注意！请确保服务文档可用，并检查其许可证和API方法的可访问性。对于某些服务，用户需获取 API 密钥后才能启用插件。

考虑插件的部署位置、整体结构以及用户如何与其组件交互。根据这些需求，明确所需的插件类型和项目。如需了解更多，请参阅插件 SDK 文档中的“插件类型”和“插件项目”部分。

例如，对于语音转文本插件，我们使用以下插件接口：

  • IPlugin：每个插件必需的基础接口，包含用于将插件嵌入协作空间的 PluginStatus 变量。
  • ApiPlugin：在集成第三方服务时使用。
  • ISettingsPlugin 和 ISettings：用于添加插件的配置界面，用户可通过“设置 > 集成 > 插件”访问并调整相关参数。
  • IContextMenuPlugin 和 IContextMenuItem：用于实现上下文菜单操作。例如，在语音转文本插件中，可对音视频文件执行“转换为文本”的操作。

接口列表可能更为丰富。以 draw.io 插件为例：

  • IMainButtonPlugin 和 IMainButtonItem：用于实现主按钮操作。在 draw.io 插件中，用户可通过“我的文档”页面或选定文件夹中的“操作按钮 > 更多”菜单，创建 draw.io 图表。
  • IFilePlugin 和 IFileItem：用于与特定文件类型交互。在此示例中，即用于处理 .drawio 文件的集成与操作。

确定插件的结构，此处介绍了所有必需的文件。其余内容可根据个人偏好组织。例如，在 draw.io 插件中，每种插件类型的代码被放置在独立的文件夹内；而在语音转文本插件中，相关代码则存放于 src 文件夹中。

(no title)

为您的插件选择一个名称并撰写描述。

开发

现在所有准备工作都已完成，您可以开始开发插件了。

步骤 1. 创建插件模板

创建插件模板并配置相关设置，这些设置将在协作空间插件配置界面中显示。

要生成模板，只需在终端中运行以下 npx 命令：

 npx create-docspace-plugin

如果 npx 命令不可用，请使用以下命令全局安装 @onlyoffice/docspace-plugin-sdk npm 包：

npm i -g @onlyoffice/docspace-plugin-sdk

通过在对话框中指定设置，在终端中配置插件。此处介绍了所有设置

对于语音转文本插件，您可以使用以下值：

(no title)

您可以稍后在 package.json file 文件中更改所有指定的参数。

您还可以在任何项目中创建插件，只需将 @onlyoffice/docspace-plugin-sdk npm 包添加为依赖项，并在 package.json 文件中指定所有必要的字段即可。

步骤 2. 配置插件入口点

在模板创建步骤中，插件入口点文件 index.ts 会在 src 文件夹中自动创建。此文件是必需的。

此文件包含您在上一步中选择的插件类型的所有基本方法。您可以随时更改此文件。

如果您不使用模板自行创建插件作为插件入口点，可以使用我们现成的插件示例中的代码。它将完美运行。

步骤 3：添加插件图标

在插件根目录下创建 assets 文件夹，并将所有需要用到的图标文件放入其中。图标的数量和尺寸取决于您所开发的插件类型。以语音转文本插件为例，我们需要以下图标：

  • 默认插件类型需要一个 logo 图片，对应 package.json 文件中的 logo 字段。该徽标将显示在协作空间插件设置中。建议尺寸为 48×48 像素，若尺寸不符，系统会自动缩放至该大小

(no title)

  • 上下文菜单插件在转换为文本按钮上使用图标。所需的图标尺寸为 16×16 像素。否则，它将被压缩到此尺寸。

(no title)

此图标也可用作主按钮图标。例如，在 draw\.io 插件中，上下文菜单和主按钮菜单使用相同的图标。

draw\.io 插件还使用 .drawio 文件附近的特定文件图标，这些文件是通过文件插件类型创建的。表格格式的首选图标大小为 32×32 像素。

步骤 4. 配置插件的界面元素

例如，draw\.io 插件包含两个主要的 UI 元素——模态窗口和图表编辑器。创建用于配置每个元素的文件。为了方便起见，您可以将这些文件放在单独的 DrawIO 文件夹中。

在 Dialog.ts 文件中，配置模态窗口设置。指定用于将 draw\.io 网站嵌入模态窗口的 IFrame UI 组件：

  export const frameProps: IFrame = {width: "100%",height: "100%",name: "test-drawio",src: "",}

创建 IBox 容器以将 iframe 添加到其中：

 const body: IBox = {widthProp: "100%",heightProp: "100%",children: [{component: Components.iFrame,props: frameProps,},],}

配置模态窗口属性：

 export const drawIoModalDialogProps: IModalDialog = {dialogHeader: "",dialogBody: body,displayType: ModalDisplayType.modal,fullScreen: true,onClose: () => {const message: IMessage = {actions: [Actions.closeModal],}return message},onLoad: async () => {return {newDialogHeader: drawIoModalDialogProps.dialogHeader || "",newDialogBody: drawIoModalDialogProps.dialogBody,}},autoMaxHeight: true,autoMaxWidth: true,

在 Editor.ts 文件中，配置图表编辑器。使用以下参数创建 DiagramEditor 函数：

参数类型示例描述
uistring"default"定义编辑器的界面主题
darkstring"auto"定义编辑器的暗色主题
offbooleanfalse指定是否启用离线模式
libbooleanfalse指定是否启用库功能
langstring"auto"定义编辑器的语言
urlstring`https://embed.diagrams.net`定义编辑器的访问 URL
showSaveButtonbooleantrue指定是否在编辑器中显示保存按钮

然后指定使用图表的方法：

方法描述
startEditing使用给定数据启动编辑器
getData返回图表的数据
getTitle返回图表的标题
getFormat返回图表的格式
getFrameId返回编辑器的框架 ID
getFrameUrl返回 iframe 的 URL
handleMessage处理指定的消息
initializeEditor向编辑器发送 load 消息
save保存给定的数据

*DiagramEditor* 的完整代码可在此处找到

步骤 5. 创建插件类型

默认插件已准备就绪，您可以开始实现其他插件类型的代码。

每种插件类型都有对应的插件项。以上下文菜单为例，您需要定义在音频或视频文件上右键点击时显示的菜单项。

export const contextMenuItem: IContextMenuItem = {key: "speech-to-text-context-menu-item",label: "Convert to text",icon: "speech-to-text-16.png",onClick: assemblyAI.speechToText,fileType: [FilesType.video],withActiveItem: true,
}

您可以添加更多插件类型。例如，draw\.io 插件可以从主按钮菜单访问，因此我们需要指定主按钮项：

const mainButtonItem: IMainButtonItem = {key: "draw-io-main-button-item",label: "Draw.io",icon: "drawio.png",onClick: (id: number) => {drawIo.setCurrentFolderId(id)const message: IMessage = {actions: [Actions.showCreateDialogModal],createDialogProps: {title: "Create diagram",startValue: "New diagram",visible: true,isCreateDialog: true,extension: ".drawio",onSave: async (e: any, value: string) => {await drawIo.createNewFile(value)},onCancel: (e: any) => {drawIo.setCurrentFolderId(null)},onClose: (e: any) => {drawIo.setCurrentFolderId(null)},},}return message},// items: [createItem],
}

单击主按钮项时，将出现模式窗口，您可以在其中输入图表的名称并打开一个空的 .drawio 文件。

对于 draw\.io 插件，您还需要配置文件插件类型，该类型在用户打开特定的 .drawio 文件时起作用：

定义表示为具有特定扩展名（.drawio）和图标的文件的文件项：

 export const drawIoItem: IFileItem = {extension: ".drawio",fileTypeName: "Diagram",fileRowIcon: "drawio-32.svg",fileTileIcon: "drawio-32.svg",devices: [Devices.desktop],onClick,}

定义 onClick 事件，该事件将在每次打开 .drawio 文件时执行 editDiagram 方法：

  const onClick = async (item: File) => {return await drawIo.editDiagram(item.id)}

(no title)

步骤 6：创建设置插件类型

配置设置插件类型，以便为用户提供管理员设置。

创建一个用于存放插件设置的容器：

 const descriptionText: TextGroup = {component: Components.text,props: {text: "To generate API token visit https://www.assemblyai.com",color: "#A3A9AE",fontSize: "12px",fontWeight: 400,lineHeight: "16px",},}const descGroup: BoxGroup = {component: Components.box,props: {children: [descriptionText]},}const parentBox: IBox = {displayProp: "flex",flexDirection: "column",// marginProp: "16px 0 0 0",children: [tokenGroup, descGroup],}

在设置描述中，指明需要生成 API 令牌才能使用该插件。

使用 ISettings 对象配置管理员设置：

const adminSettings: ISettings = {settings: parentBox,saveButton: userButtonComponent,onLoad: async () => {assemblyAI.fetchAPIToken()tokenInput.value = assemblyAI.apiTokenif (!assemblyAI.apiToken) {return {settings: parentBox,}}plugin.setAdminPluginSettings(adminSettings)return {settings: parentBox}}

指定 onLoad 事件，该事件定义加载设置块时将显示哪些插件设置。

每个设置项都在单独的文件（按钮、令牌）中确定。

步骤 7：创建主插件代码文件

在 src 文件夹中创建一个包含主插件代码的文件。此文件是必需的。请参考第三方服务的文档来编写此代码。

让我们看看 AssemblyAI.ts 文件的详细结构：

定义 AssemblyAI 类，并包含所有必要的变量和方法：

  • 变量及其说明：

apiURL

定义 API URL。

apiURL = ""

currentFileId
定义当前文件 ID。

const currentFileId: numbernull | number = null

apiToken
定义 API 令牌。

 apiToken = ""
  • 方法及其描述

createAPIUrl
创建 API URL。

 createAPIUrl = () => {const api = plugin.getAPI()this.apiURL = api.origin.replace(/\/+$/, "")const params = [api.proxy, api.prefix]if (this.apiURL) {for (const part of params) {if (!part) {continue}const newPart = part.trim().replace(/^\/+/, "")if (newPart) {if (this.apiURL.length !== 0 && this.apiURL[this.apiURL.length - 1] === "/") {this.apiURL += newPart} else {this.apiURL += `/${newPart}`}}}}}

setAPIUrl
设置 API URL。

 setAPIUrl = (url: string) => {this.apiURL = url}

getAPIUrl
返回 API URL。

 getAPIUrl = () => {return this.apiURL}

setAPIToken
设置 API 令牌。

   setAPIToken = (apiToken: string) => {this.apiToken = apiToken}

getAPIToken

返回 API 令牌。

   getAPIToken = () => {return this.apiToken}

fetchAPIToken
获取 API 令牌。

   fetchAPIToken = async () => {const apiToken = localStorage.getItem("speech-to-text-api-token")if (!apiToken) {return}this.setAPIToken(apiToken)plugin.updateStatus(PluginStatus.active)}

saveAPIToken
保存 API 令牌。

   saveAPIToken = (apiToken: string) => {localStorage.setItem("speech-to-text-api-token", apiToken)let statusif (apiToken) {status = PluginStatus.active} else {status = PluginStatus.hide}plugin.updateStatus(status)}

saveAPIToken
保存 API 令牌。

 setCurrentFileId = (id: number | null) => {this.currentFileId = id}

uploadFile
上传将被转录的文件。

uploadFile = async (apiToken: string, path: string, data: Blob) => {console.log(`Uploading file: ${path}`)const url = "https://api.assemblyai.com/v2/upload"try {const response = await fetch(url, {method: "POST",body: data,headers: {"Content-Type": "application/octet-stream","Authorization": apiToken,},})if (response.status === 200) {const responseData = await response.json()return responseData["upload_url"]}console.error(`Error: ${response.status} - ${response.statusText}`)return null} catch (error) {console.error(`Error: ${error}`)return null}}

transcribeAudio
转录音频文件。

transcribeAudio = async (apiToken: string, audioUrl: string) => {console.log("Transcribing audio... This might take a moment.")const headers = {"authorization": apiToken,"content-type": "application/json",}const response = await fetch("https://api.assemblyai.com/v2/transcript", {method: "POST",body: JSON.stringify({audioUrl}),headers,})const responseData = await response.json()const transcriptId = responseData.idconst pollingEndpoint = `https://api.assemblyai.com/v2/transcript/${transcriptId}`while (true) {const pollingResponse = await fetch(pollingEndpoint, {headers})const transcriptionResult = await pollingResponse.json()if (transcriptionResult.status === "completed") {return transcriptionResult} else if (transcriptionResult.status === "error") {throw new Error(`Transcription failed: ${transcriptionResult.error}`)} else {await new Promise((resolve) => {setTimeout(resolve, 3000)})}}}

speechToText
实现插件功能。

speechToText = async (id: number) => {if (!this.apiToken) {return}this.setCurrentFileId(null)if (!this.apiURL) {this.createAPIUrl()}const response = await fetch(`${this.apiURL}/files/file/${id}`)const data = await response.json()const {viewUrl, title, folderId, fileExst} = data.responseconst file = await fetch(viewUrl)const fileBlob = await file.blob()const uploadUrl = await this.uploadFile(this.apiToken, viewUrl, fileBlob)const transcript = await this.transcribeAudio(this.apiToken, uploadUrl)const blob = new Blob([transcript.text], {type: "text/plain;charset=UTF-8",})const newFile = new File([blob], "blob", {type: "",lastModified: Date.now(),})const formData = new FormData()formData.append("file", newFile)const newTitle = `${title.replaceAll(fileExst, "")} text`try {const sessionRes = await fetch(`${this.apiURL}/files/${folderId}/upload/create_session`,{method: "POST",headers: {"Content-Type": "application/json;charset=utf-8",},body: JSON.stringify({createOn: new Date(),fileName: `${newTitle}.txt`,fileSize: newFile.size,relativePath: "",}),},)const response = await sessionRes.json()const sessionData = response.response.dataconst data = await fetch(`${sessionData.location}`, {method: "POST",body: formData,})const jsonData = await data.json()const {id: fileId} = jsonData.datareturn fileId} catch (e) {console.log(e)}return {actions: [Actions.showToast],toastProps: [{type: ToastType.success, title: ""}],} as IMessage}

声明 AssemblyAI 类实例：

const assemblyAI = new AssemblyAI()

导出创建的插件实例：

export default assemblyAI

测试

要检查插件的功能并修复任何潜在错误，请测试插件：

  • 按照此处的说明构建准备好的插件

dist 文件夹将在插件根文件夹中创建，插件存档将放置在其中。此存档是完整的插件，可以上传到协作空间门户。

  • 将您的插件上传到协作空间门户，并彻底测试其外观和功能。

请注意！您只能在服务器协作空间版本中上传自己的插件。

如果出现任何错误，请修复插件的源代码，然后重复构建和测试的过程。

现在您的插件已经过测试并正常运行，您可以将其添加到协作空间服务器版本并开始使用。

协作空间插件为文档管理和团队协作提供了高效且便捷的解决方案。通过与用户常用平台的集成，它能有效消除协作障碍，提升各类工作流程的效率。如果您在使用协作空间插件时有任何疑问，欢迎前往 ONLYOFFICE 论坛向我们的开发团队提问。您也可以通过 GitHub 提交问题，反馈功能需求或报告错误。

获取 ONLYOFFICE 协作空间

本地部署ONLYOFFICE 协作空间，即可开始创建插件：

下载供企业内部使用的 ONLYOFFICE 服务器解决方案 | ONLYOFFICEhttps://www.onlyoffice.com/zh/download.aspx#docspace-enterprise

相关链接

协作空间插件入门：https://api.onlyoffice.com/docspace/plugins-sdk/get-started/

GitHub 上的 ONLYOFFICE：https://github.com/ONLYOFFICE

本地 ONLYOFFICE 协作空间：https://www.onlyoffice.com/zh/download.aspx

协作空间社区：https://helpcenter.onlyoffice.com/docspace/installation/community

相关文章：

  • 大学生职业发展与就业创业指导教学评价
  • Cloudflare 从 Nginx 到 Pingora：性能、效率与安全的全面升级
  • std::ratio 简单使用举例
  • Cell的复用及自定义Cell
  • 【Zephyr 系列 16】构建 BLE + LoRa 协同通信系统：网关转发与混合调度实战
  • EasyImage实战：结合内网穿透技术实现私有图床部署过程
  • 创客匠人：赋能创始人IP打造，破局知识变现的黄金路径
  • Android实践：查看远程文档
  • 接口自动化测试-效果展示
  • 2025年文化交流与创新教育国际会议（ICCEIE 2025）
  • 合成来源图以在入侵检测系统中进行数据增强
  • RAG质量评估
  • 【易飞】通过信息传递触发时机复制生成品号实现复制品号自动带出原自定义字段数据
  • 马克思主义与社会科学方法论通俗版
  • MeanFlow：何凯明新作，单步去噪图像生成新SOTA
  • DAY 19 常见的特征筛选算法
  • 本周四19点，《国产网络音频传输的今天和明天》开讲！
  • 软件工程教学评价
  • 性能测试｜有限元软件分析——以Abaqus隐式静力学求解为例
  • 【JavaSE】多线程基础学习笔记
  • 网站建设综合实训/巩义网络推广公司
  • 网站建设方案多少钱/app软件开发
  • 上海网站建设百度推广公司/高端网站建设企业
  • 企业首次建设网站的策划方案/竞价如何屏蔽恶意点击
  • 论坛网站怎么做跳转/营销模式
  • 网站服务器租用还是自买/新闻软文广告