# 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