210 lines
4.6 KiB
Markdown
210 lines
4.6 KiB
Markdown
# 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日
|
||
|