yx_only_office_flutter/example

ONLYOFFICE Flutter Plugin Example

本示例展示如何在 Flutter 应用中集成 ONLYOFFICE 文档查看和编辑功能。

运行示例

本示例包含两个入口文件：

基础示例 (main.dart)

简单的文档查看和编辑示例。

cd example

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

高级示例 (main_advanced.dart) 🚀

完整的高级功能演示，包括图片插入、文件下载、编辑器方法调用等。

cd example

flutter run -t lib/main_advanced.dart \
  --dart-define ONLYOFFICE_SERVER_URL=https://your-server.com \
  --dart-define ONLYOFFICE_FILE_URL=https://example.com/document.docx \
  --dart-define ONLYOFFICE_JWT_SECRET=your-secret-key \
  --dart-define UPLOAD_URL=https://your-upload-server.com/upload

📖 详细说明: 查看 HOW_TO_RUN_ADVANCED.md 了解如何运行高级示例

环境变量说明

变量	说明	必需	示例
ONLYOFFICE_SERVER_URL	ONLYOFFICE Document Server 地址	✅ 是	https://doc.example.com
ONLYOFFICE_FILE_URL	文档文件的可下载地址	✅ 是	https://example.com/document.docx
ONLYOFFICE_JWT_SECRET	JWT 签名密钥（如果服务器启用了 JWT）	❌ 否	your-secret-key
UPLOAD_URL	图片上传服务器地址（仅高级示例需要）	❌ 否	https://api.example.com/upload

功能演示

本示例应用展示了以下功能：

1. 查看模式 (View Mode)

• 只读文档查看
• 控制下载权限
• 控制打印权限
• 自定义 UI

2. 编辑模式 (Edit Mode)

• 完整的文档编辑功能
• 实时协作支持
• 文档状态跟踪（是否有未保存的修改）
• 另存为功能
• 插入图片功能

3. 事件处理

• onError: 错误处理
• onAppClose: 关闭请求
• onDownloadAs: 下载完成
• onRequestSaveAs: 另存为请求
• onRequestInsertImage: 插入图片请求
• onDocumentStateChange: 文档状态变化
• onMetaChange: 元数据变化
• onEvent: 通用事件处理

4. JWT 签名

• 自动 JWT 签名（如果提供密钥）
• 安全的配置传输

代码结构

example/
├── lib/
│   └── main.dart          # 主应用代码
├── integration_test/
│   └── viewer_test.dart   # 集成测试
└── README.md              # 本文件

主要代码片段

基础使用

YxOnlyOfficeViewer.create(
  serverUrl: 'https://your-server.com',
  fileUrl: 'https://example.com/document.docx',
  mode: 'view', // 或 'edit'
  onError: (error) => print('错误: $error'),
)

编辑模式

YxOnlyOfficeViewer.create(
  serverUrl: 'https://your-server.com',
  fileUrl: 'https://example.com/document.docx',
  mode: 'edit',
  user: OnlyOfficeUser(
    id: 'user123',
    name: '张三',
    email: 'zhangsan@example.com',
  ),
  onDocumentStateChange: (data) {
    final hasChanges = data == true;
    print('文档${hasChanges ? "已修改" : "未修改"}');
  },
)

JWT 签名

YxOnlyOfficeViewer.create(
  serverUrl: 'https://your-server.com',
  fileUrl: 'https://example.com/document.docx',
  tokenFactory: OnlyOfficeJwtSigner('your-secret-key'),
)

测试

运行集成测试：

cd example
flutter test integration_test/viewer_test.dart

常见问题

文档无法加载

1. 检查 ONLYOFFICE_SERVER_URL 是否正确
2. 检查 ONLYOFFICE_FILE_URL 是否可访问
3. 如果启用了 JWT，检查密钥是否正确
4. 查看控制台日志获取详细错误信息

编辑功能不可用

1. 确保 mode 设置为 'edit'
2. 确保文档格式支持编辑
3. 检查 Document Server 版本（需要 6.1+）

如何保存编辑后的文档

ONLYOFFICE 提供两种保存方式：

1. 服务端回调（推荐）：

   OnlyOfficeEditorConfig(
     callbackUrl: 'https://your-server.com/callback',
   )
   

2. 客户端下载：

   onDownloadAs: (fileType, url) {
     // 下载修改后的文档
   }
   

参考资源

• ONLYOFFICE Docs API 文档
• Android 官方项目
• iOS 官方项目
• 插件主页

许可证

MIT License