# OnlyOffice Flutter 插件 - 示例运行指南

## 简单示例

这是一个使用真实 OnlyOffice 服务的简单示例，展示如何快速集成和使用插件。

### 配置信息

示例中使用的配置：

- **OnlyOffice 服务**: `https://document.23544.com/`
- **JWT Token**: `6Yr6DGoVV3ACS6GtVgdH453mXxLftd6Q`
- **示例文件**: `https://quanxue-oa.oss-cn-chengdu.aliyuncs.com/20250815/1755244744547.pptx`

### 运行简单示例

```bash
# 进入 example 目录
cd example

# 运行简单示例
flutter run -t lib/simple_example.dart
```

### 在 Android 设备上运行

```bash
# 连接 Android 设备或启动模拟器
flutter devices

# 运行
flutter run -t lib/simple_example.dart -d android
```

### 在 iOS 设备上运行

```bash
# 连接 iOS 设备或启动模拟器
flutter devices

# 运行
flutter run -t lib/simple_example.dart -d ios
```

## 高级示例

项目还包含一个功能更丰富的高级示例 `main_advanced.dart`。

### 运行高级示例（需要配置环境变量）

```bash
flutter run -t lib/main_advanced.dart \
  --dart-define ONLYOFFICE_SERVER_URL=https://document.23544.com/ \
  --dart-define ONLYOFFICE_FILE_URL=https://quanxue-oa.oss-cn-chengdu.aliyuncs.com/20250815/1755244744547.pptx \
  --dart-define ONLYOFFICE_JWT_SECRET=6Yr6DGoVV3ACS6GtVgdH453mXxLftd6Q
```

## 代码示例

### 基本用法

```dart
import 'package:yx_only_office_flutter/yx_only_office_flutter.dart';

// 在 Widget 树中使用
OnlyOfficeViewer(
  onlyOfficeServerUrl: 'https://document.23544.com/',
  fileUrl: 'https://your-file-url.com/document.pptx',
  token: 'your-jwt-token',
)
```

### 不带 Token 使用

如果你的 OnlyOffice 服务器不需要 JWT 验证：

```dart
OnlyOfficeViewer(
  onlyOfficeServerUrl: 'https://document.23544.com/',
  fileUrl: 'https://your-file-url.com/document.docx',
  // token 参数可以省略或设置为 null
)
```

### 完整页面示例

```dart
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: OnlyOfficeViewer(
        onlyOfficeServerUrl: 'https://document.23544.com/',
        fileUrl: 'https://quanxue-oa.oss-cn-chengdu.aliyuncs.com/20250815/1755244744547.pptx',
        token: '6Yr6DGoVV3ACS6GtVgdH453mXxLftd6Q',
      ),
    );
  }
}
```

## 支持的文档格式

### Word 文档
- `.doc`, `.docx` - Microsoft Word
- `.pdf` - PDF 文档
- `.txt` - 文本文件
- `.rtf` - 富文本格式
- `.odt` - OpenDocument 文本

### Excel 表格
- `.xls`, `.xlsx` - Microsoft Excel
- `.csv` - CSV 文件
- `.ods` - OpenDocument 表格

### PowerPoint 演示文稿
- `.ppt`, `.pptx` - Microsoft PowerPoint
- `.odp` - OpenDocument 演示文稿

## 常见问题

### 1. 文档无法加载

**可能原因**:
- OnlyOffice 服务器地址不正确
- 文件 URL 无法访问
- JWT Token 无效或过期
- 网络连接问题

**解决方案**:
- 检查服务器 URL 是否正确
- 确认文件 URL 可以在浏览器中访问
- 验证 JWT Token 是否有效
- 检查网络连接

### 2. Android 上网络请求被阻止

**解决方案**: 确保在 `AndroidManifest.xml` 中添加了网络权限：

```xml
<uses-permission android:name="android.permission.INTERNET" />
```

### 3. iOS 上无法加载 HTTP 内容

**解决方案**: 如果使用 HTTP（不推荐），需要在 `Info.plist` 中配置：

```xml
<key>NSAppTransportSecurity</key>
<dict>
    <key>NSAllowsArbitraryLoads</key>
    <true/>
</dict>
```

**注意**: 建议使用 HTTPS 以确保安全。

## 性能优化建议

1. **预加载文档**: 如果知道用户将要查看哪些文档，可以预先加载
2. **缓存策略**: 考虑实现文档缓存机制
3. **网络监控**: 监控网络状态，在网络不佳时给出提示
4. **错误处理**: 实现适当的错误处理和重试机制

## 调试

### 启用 WebView 调试（Android）

```dart
import 'package:webview_flutter_android/webview_flutter_android.dart';

// 在初始化时启用调试
if (Platform.isAndroid) {
  final controller = WebViewAndroidController();
  await controller.enableDebugging(true);
}
```

### 查看日志

运行应用时查看控制台输出：

```bash
flutter run -t lib/simple_example.dart -v
```

## 更多信息

- [插件 README](../README.md)
- [测试报告](../TEST_REPORT.md)
- [API 文档](../docs/API_REFERENCE.md)
- [高级功能](../docs/ADVANCED_FEATURES.md)

## 技术支持

如有问题或建议，请提交 Issue 或 Pull Request。

---

**最后更新**: 2025年12月4日