wangyang

yx_only_office_flutter

Fork 0

8.3 KiB

Raw Blame History

yx_only_office_flutter

面向 Flutter 项目的 ONLYOFFICE 文档查看与编辑插件。基于 webview_flutter 实现，完全遵循 ONLYOFFICE Docs API 官方规范。

官方参考

功能特性

✅ 完整的查看与编辑支持：支持 view 和 edit 两种模式
✅ 标准配置结构：完全遵循官方 DocsAPI 配置规范
✅ 丰富的事件桥接：支持 onError、onAppClose、onDownloadAs、onRequestSaveAs、onRequestInsertImage、onDocumentStateChange 等事件
✅ JWT 签名支持：内置 HMAC-SHA256 JWT 签名工具
✅ 高度可定制：支持自定义 UI、权限、语言、用户信息等
✅ 跨平台支持：同时支持 Android 和 iOS

环境要求

可访问的 ONLYOFFICE Document Server（云端或自建）
能够提供可下载的文件地址（HTTP/HTTPS）
Flutter 3.3+，Dart 3.9.2+

安装

dependencies:
  yx_only_office_flutter: ^0.1.0

或使用命令：

flutter pub add yx_only_office_flutter

快速开始

1. 查看文档（只读模式）

import 'package:flutter/material.dart';
import 'package:yx_only_office_flutter/yx_only_office_flutter.dart';

class DocumentViewerPage extends StatelessWidget {
  const DocumentViewerPage({super.key});

  @override
  Widget build(BuildContext context) {
    return Scaffold(
      appBar: AppBar(title: const Text('文档查看')),
      body: YxOnlyOfficeViewer.create(
        serverUrl: 'https://your-onlyoffice-server.com',
        fileUrl: 'https://example.com/document.docx',
        mode: 'view', // 只读模式
        title: '示例文档.docx',
        allowDownload: true,
        allowPrint: false,
        user: const OnlyOfficeUser(
          id: 'user123',
          name: '张三',
        ),
        onError: (error) {
          debugPrint('文档加载错误: $error');
        },
      ),
    );
  }
}

2. 编辑文档

YxOnlyOfficeViewer.create(
  serverUrl: 'https://your-onlyoffice-server.com',
  fileUrl: 'https://example.com/document.docx',
  mode: 'edit', // 编辑模式
  title: '可编辑文档.docx',
  user: const OnlyOfficeUser(
    id: 'user123',
    name: '张三',
    email: 'zhangsan@example.com',
  ),
  onDocumentStateChange: (data) {
    // 文档状态变化（是否有未保存的修改）
    final isModified = data ?? false;
    debugPrint('文档已修改: $isModified');
  },
  onRequestSaveAs: (data) {
    // 用户点击"另存为"
    debugPrint('请求保存: $data');
  },
  onRequestInsertImage: (data) {
    // 用户请求插入图片（可以打开 Flutter 图片选择器）
    debugPrint('请求插入图片: $data');
  },
)

3. 使用 JWT 签名（推荐用于生产环境）

const jwtSecret = String.fromEnvironment('ONLYOFFICE_JWT_SECRET');

YxOnlyOfficeViewer.create(
  serverUrl: 'https://your-onlyoffice-server.com',
  fileUrl: 'https://example.com/document.docx',
  mode: 'edit',
  tokenFactory: jwtSecret.isNotEmpty 
    ? OnlyOfficeJwtSigner(jwtSecret) 
    : null,
  onError: (error) => debugPrint('错误: $error'),
)

4. 高级配置（手动构建配置）

final config = OnlyOfficeConfigFactory.create(
  fileUrl: 'https://example.com/document.docx',
  mode: 'edit',
  title: '高级配置文档.docx',
  lang: 'zh-CN',
  user: const OnlyOfficeUser(
    id: 'user123',
    name: '张三',
    email: 'zhangsan@example.com',
  ),
  customization: const OnlyOfficeCustomization(
    compactToolbar: true,
    hideRightMenu: false,
    toolbarNoTabs: false,
  ),
  tokenFactory: OnlyOfficeJwtSigner('your-secret-key'),
);

YxOnlyOfficeViewer(
  serverUrl: 'https://your-onlyoffice-server.com',
  config: config,
  onEvent: (event, data) {
    // 通用事件处理器，捕获所有事件
    debugPrint('事件: $event, 数据: $data');
  },
)

支持的文档格式

插件自动识别以下文档类型：

文字处理 (word)

doc, docx, docm, dot, dotx, dotm, odt, fodt, ott, rtf, txt, html, htm, mht, xml, pdf, djvu, fb2, epub, xps

电子表格 (cell)

xls, xlsx, xlsm, xlt, xltx, xltm, ods, fods, ots, csv

演示文稿 (slide)

ppt, pptx, pptm, pps, ppsx, ppsm, pot, potx, potm, odp, fodp, otp

事件回调说明

事件	说明	回调参数
`onError`	文档加载或编辑错误	`String error`
`onAppClose`	用户请求关闭编辑器	无
`onDownloadAs`	文档下载完成	`String fileType, String url`
`onRequestSaveAs`	用户点击"另存为"	`dynamic data`
`onRequestInsertImage`	用户请求插入图片	`dynamic data`
`onDocumentStateChange`	文档修改状态变化	`dynamic data` (boolean)
`onMetaChange`	文档元数据变化	`dynamic data`
`onMakeActionLink`	创建操作链接	`dynamic data`
`onEvent`	通用事件处理器	`String event, dynamic data`

配置类说明

OnlyOfficeConfig

顶层配置对象，包含：

document: 文档元数据（OnlyOfficeDocument）
documentType: 文档类型（word/cell/slide）
editorConfig: 编辑器配置（OnlyOfficeEditorConfig）
type: 客户端类型（默认 mobile）
token: JWT 令牌（可选）

OnlyOfficeDocument

文档信息：

fileType: 文件扩展名（如 docx）
key: 文档唯一标识（自动生成或手动指定）
title: 文档标题
url: 文档下载地址
permissions: 文档权限（OnlyOfficePermissions）

OnlyOfficeEditorConfig

编辑器设置：

mode: 模式（view 或 edit）
lang: 界面语言（默认 zh-CN）
user: 用户信息（OnlyOfficeUser）
customization: UI 自定义（OnlyOfficeCustomization）
callbackUrl: 回调地址（可选，用于服务端保存）

OnlyOfficePermissions

权限控制：

edit: 是否允许编辑
download: 是否允许下载
print: 是否允许打印
review: 是否允许审阅
comment: 是否允许评论
copy: 是否允许复制
fillForms: 是否允许填写表单

OnlyOfficeCustomization

UI 定制：

compactToolbar: 紧凑工具栏
hideRightMenu: 隐藏右侧菜单
hideLeftMenu: 隐藏左侧菜单
hideRulers: 隐藏标尺
toolbarNoTabs: 工具栏无标签页
showReviewChanges: 显示审阅更改

JWT 签名

插件内置 OnlyOfficeJwtSigner 类，使用 HMAC-SHA256 算法签名配置：

const signer = OnlyOfficeJwtSigner('your-secret-key');
final token = signer.sign(config.toJson());

安全提示：

⚠️ 不要在客户端硬编码 JWT 密钥
✅ 推荐通过环境变量或服务端 API 获取签名
✅ 生产环境应在服务端完成签名

示例工程

查看 example/ 目录获取完整示例，包括：

基础查看功能
编辑模式演示
JWT 签名集成
事件处理示例
集成测试

运行示例：

cd example
flutter run \
  --dart-define ONLYOFFICE_SERVER_URL=https://your-server.com \
  --dart-define ONLYOFFICE_FILE_URL=https://example.com/doc.docx \
  --dart-define ONLYOFFICE_JWT_SECRET=your-secret

常见问题

1. 文档无法加载？

检查：

Document Server 是否可访问
文件 URL 是否可下载
JWT 签名是否正确（如果启用）
网络权限是否配置（Android/iOS）

2. 编辑模式不生效？

确保：

mode 设置为 'edit'
document.permissions.edit 为 true
用户信息已正确配置

3. 如何保存编辑后的文档？

ONLYOFFICE 支持两种保存方式：

服务端回调：配置 callbackUrl，Document Server 会将修改推送到你的服务器
客户端下载：监听 onDownloadAs 事件，获取修改后的文档 URL

兼容性

✅ Android 5.0+
✅ iOS 11.0+
✅ ONLYOFFICE Document Server 6.1+

许可证

本项目采用 MIT 许可证，详见 LICENSE 文件。

贡献

欢迎提交 Issue 和 Pull Request！

更新日志

查看 CHANGELOG.md 了解版本更新历史。

8.3 KiB Raw Blame History Unescape Escape

yx_only_office_flutter

官方参考

功能特性

环境要求

安装

快速开始

1. 查看文档（只读模式）

2. 编辑文档

3. 使用 JWT 签名（推荐用于生产环境）

4. 高级配置（手动构建配置）

支持的文档格式

文字处理 (word)

电子表格 (cell)

演示文稿 (slide)

事件回调说明

配置类说明

OnlyOfficeConfig

OnlyOfficeDocument

OnlyOfficeEditorConfig

OnlyOfficePermissions

OnlyOfficeCustomization

JWT 签名

示例工程

常见问题

1. 文档无法加载？

2. 编辑模式不生效？

3. 如何保存编辑后的文档？

兼容性

许可证

贡献

更新日志

8.3 KiB

Raw Blame History