@builder6/onlyoffice

v4.0.0

Published

2 months ago

Builder6 OnlyOffice 模块为 Builder6 平台提供 OnlyOffice 文档编辑器集成，支持在线协作编辑 Word、Excel、PowerPoint 等 Office 文档。

0High
0Medium
0Low

steedos-zhuangjianguo

steedos-baozhoutao

yinlianghui

steedos-sunhaolin

Builder6 OnlyOffice Module

Builder6 OnlyOffice 模块为 Builder6 平台提供 OnlyOffice 文档编辑器集成，支持在线协作编辑 Word、Excel、PowerPoint 等 Office 文档。

功能特性

在线文档编辑: 支持 Word、Excel、PowerPoint 文档在线编辑
实时协作: 多用户同时编辑同一文档
文档预览: 支持各种文档格式的在线预览
水印支持: 可配置的文档编辑水印
JWT 安全: 使用 JWT 令牌保护文档编辑会话
回调处理: 处理文档保存和编辑状态回调
权限控制: 灵活的文档访问和编辑权限配置
版本管理: 支持文档版本历史记录

安装

npm install @builder6/onlyoffice

或

yarn add @builder6/onlyoffice

环境变量

基本配置

# 启用 OnlyOffice 集成
B6_ONLYOFFICE_ENABLED=true

# OnlyOffice Document Server URL
B6_ONLYOFFICE_URL=https://onlyoffice.steedos.cn

# JWT 密钥（用于安全通信）
B6_ONLYOFFICE_JWT_SECRET=your-secret-key

高级配置

# 启用默认编辑水印
B6_ONLYOFFICE_WATERMARK_ENABLED=true

# 水印文本
B6_ONLYOFFICE_WATERMARK_TEXT=Confidential

# 水印透明度 (0-1)
B6_ONLYOFFICE_WATERMARK_OPACITY=0.5

# 允许的文档类型（逗号分隔）
B6_ONLYOFFICE_ALLOWED_TYPES=docx,xlsx,pptx,doc,xls,ppt

# 文档保存超时（秒）
B6_ONLYOFFICE_SAVE_TIMEOUT=60

# 回调 URL 前缀
B6_ONLYOFFICE_CALLBACK_URL_PREFIX=https://your-domain.com

使用示例

在 NestJS 应用中集成

import { Module } from '@nestjs/common';
import { OnlyOfficeModule } from '@builder6/onlyoffice';

@Module({
  imports: [OnlyOfficeModule],
})
export class AppModule {}

打开文档编辑器

import { OnlyOfficeService } from '@builder6/onlyoffice';

constructor(private onlyOfficeService: OnlyOfficeService) {}

async openDocument(fileId: string, userId: string) {
  const config = await this.onlyOfficeService.getEditorConfig({
    fileId,
    userId,
    mode: 'edit', // 'edit' 或 'view'
    title: 'Document.docx',
    fileType: 'docx',
    callbackUrl: `https://your-domain.com/api/callback/${fileId}`
  });
  
  return config;
}

前端集成示例

<!DOCTYPE html>
<html>
<head>
    <title>OnlyOffice Editor</title>
    <script type="text/javascript" src="https://onlyoffice.steedos.cn/web-apps/apps/api/documents/api.js"></script>
</head>
<body>
    <div id="placeholder"></div>
    <script type="text/javascript">
        // 从后端获取配置
        fetch('/api/v6/onlyoffice/config?fileId=123')
            .then(res => res.json())
            .then(config => {
                new DocsAPI.DocEditor("placeholder", config);
            });
    </script>
</body>
</html>

处理文档保存回调

@Post('callback/:fileId')
async handleCallback(
  @Param('fileId') fileId: string,
  @Body() callbackData: any
) {
  // status: 1-编辑中, 2-准备保存, 3-保存错误, 4-关闭无变化, 6-正在编辑, 7-强制保存错误
  const { status, url, users, key } = callbackData;
  
  if (status === 2) {
    // 文档已保存，下载新版本
    await this.onlyOfficeService.downloadDocument(url, fileId);
    return { error: 0 };
  }
  
  return { error: 0 };
}

API 端点

模块提供以下主要 API 端点：

GET /api/v6/onlyoffice/config: 获取编辑器配置
- 查询参数: fileId, mode (edit/view)
GET /api/v6/onlyoffice/download/:fileId: 下载文档
POST /api/v6/onlyoffice/callback/:fileId: 接收 OnlyOffice 回调
POST /api/v6/onlyoffice/create: 创建新文档

支持的文档格式

文字处理（Word）

.docx, .doc, .odt, .rtf, .txt, .html, .htm, .mht, .pdf

电子表格（Excel）

.xlsx, .xls, .ods, .csv

演示文稿（PowerPoint）

.pptx, .ppt, .odp

编辑器模式

编辑模式 (edit)

允许用户编辑文档：

const config = {
  mode: 'edit',
  permissions: {
    edit: true,
    download: true,
    print: true,
    review: true,
    comment: true
  }
};

查看模式 (view)

只读模式，不允许编辑：

const config = {
  mode: 'view',
  permissions: {
    edit: false,
    download: true,
    print: true
  }
};

水印配置

启用水印保护文档：

const config = {
  watermark: {
    enabled: true,
    text: 'Confidential',
    diagonal: true,
    opacity: 0.5,
    color: '#FF0000'
  }
};

协作功能

实时协作

多用户同时编辑：

const config = {
  coEditing: {
    mode: 'fast', // 'fast' 或 'strict'
    change: true
  },
  user: {
    id: userId,
    name: userName,
    group: 'team-1'
  }
};

评论和审阅

const config = {
  permissions: {
    comment: true,      // 允许评论
    review: true,       // 允许审阅
    reviewGroups: ['editor', 'reviewer']
  }
};

安全性

JWT 令牌

所有与 OnlyOffice Document Server 的通信都使用 JWT 签名：

B6_ONLYOFFICE_JWT_SECRET=your-very-secret-key

回调验证

模块自动验证来自 OnlyOffice 的回调请求的 JWT 签名。

使用场景

文档协作: 团队协作编辑 Office 文档
在线办公: 无需安装 Office 即可编辑文档
文档审阅: 支持评论、修订和审阅流程
文档预览: 在线预览各种格式的文档
版本控制: 管理文档版本历史

OnlyOffice Document Server 部署

Docker 部署

docker run -i -t -d -p 80:80 \
  -e JWT_ENABLED=true \
  -e JWT_SECRET=your-secret-key \
  onlyoffice/documentserver

配置连接

B6_ONLYOFFICE_URL=http://your-server:80
B6_ONLYOFFICE_JWT_SECRET=your-secret-key

依赖项

Peer Dependencies

@builder6/core: ^3.0.10 - 核心功能模块
@builder6/files: ^3.0.10 - 文件管理模块
@nestjs/common: ^11.0.0 - NestJS 核心
@nestjs/core: ^11.0.0 - NestJS 核心
@nestjs/swagger: ^11.0.7 - API 文档

开发

构建

npm run build

监听模式

npm run build:watch

格式化代码

npm run format