183 lines
4.4 KiB
Markdown
183 lines
4.4 KiB
Markdown
# ONLYOFFICE Flutter Plugin Example
|
||
|
||
本示例展示如何在 Flutter 应用中集成 ONLYOFFICE 文档查看和编辑功能。
|
||
|
||
## 运行示例
|
||
|
||
本示例包含两个入口文件：
|
||
|
||
### 基础示例 (`main.dart`)
|
||
|
||
简单的文档查看和编辑示例。
|
||
|
||
```bash
|
||
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`) 🚀
|
||
|
||
完整的高级功能演示，包括图片插入、文件下载、编辑器方法调用等。
|
||
|
||
```bash
|
||
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](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 # 本文件
|
||
```
|
||
|
||
## 主要代码片段
|
||
|
||
### 基础使用
|
||
|
||
```dart
|
||
YxOnlyOfficeViewer.create(
|
||
serverUrl: 'https://your-server.com',
|
||
fileUrl: 'https://example.com/document.docx',
|
||
mode: 'view', // 或 'edit'
|
||
onError: (error) => print('错误: $error'),
|
||
)
|
||
```
|
||
|
||
### 编辑模式
|
||
|
||
```dart
|
||
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 签名
|
||
|
||
```dart
|
||
YxOnlyOfficeViewer.create(
|
||
serverUrl: 'https://your-server.com',
|
||
fileUrl: 'https://example.com/document.docx',
|
||
tokenFactory: OnlyOfficeJwtSigner('your-secret-key'),
|
||
)
|
||
```
|
||
|
||
## 测试
|
||
|
||
运行集成测试：
|
||
|
||
```bash
|
||
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. **服务端回调**（推荐）：
|
||
```dart
|
||
OnlyOfficeEditorConfig(
|
||
callbackUrl: 'https://your-server.com/callback',
|
||
)
|
||
```
|
||
|
||
2. **客户端下载**：
|
||
```dart
|
||
onDownloadAs: (fileType, url) {
|
||
// 下载修改后的文档
|
||
}
|
||
```
|
||
|
||
## 参考资源
|
||
|
||
- [ONLYOFFICE Docs API 文档](https://api.onlyoffice.com/docs/docs-api/)
|
||
- [Android 官方项目](https://github.com/ONLYOFFICE/documents-app-android)
|
||
- [iOS 官方项目](https://github.com/ONLYOFFICE/documents-app-ios)
|
||
- [插件主页](../README.md)
|
||
|
||
## 许可证
|
||
|
||
MIT License
|