yx_only_office_flutter/example/HOW_TO_RUN_ADVANCED.md

如何运行 main_advanced.dart

快速开始

方法 1: 使用 -t 参数指定入口文件（推荐）

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

方法 2: 使用 --target 参数（等同于 -t）

cd example

flutter run --target lib/main_advanced.dart \
  --dart-define ONLYOFFICE_SERVER_URL=https://your-server.com \
  --dart-define ONLYOFFICE_FILE_URL=https://example.com/document.docx

方法 3: 在 VS Code 中运行

1. 打开 example/lib/main_advanced.dart 文件
2. 点击右上角的运行按钮（▶️）
3. 或者按 F5 键
4. 在启动配置中添加环境变量（见下方配置）

必需的环境变量

必需变量

变量名	说明	示例
ONLYOFFICE_SERVER_URL	ONLYOFFICE Document Server 地址	https://doc.example.com
ONLYOFFICE_FILE_URL	要打开的文档 URL	https://example.com/document.docx

可选变量

变量名	说明	示例
ONLYOFFICE_JWT_SECRET	JWT 签名密钥（如果服务器启用了 JWT）	your-secret-key
UPLOAD_URL	图片上传服务器地址（用于图片插入功能）	https://api.example.com/upload

完整命令示例

Windows (PowerShell)

cd example

flutter run -t lib/main_advanced.dart `
  --dart-define ONLYOFFICE_SERVER_URL=https://doc.example.com `
  --dart-define ONLYOFFICE_FILE_URL=https://example.com/document.docx `
  --dart-define ONLYOFFICE_JWT_SECRET=my-secret-key `
  --dart-define UPLOAD_URL=https://api.example.com/upload

Windows (CMD)

cd example

flutter run -t lib/main_advanced.dart ^
  --dart-define ONLYOFFICE_SERVER_URL=https://doc.example.com ^
  --dart-define ONLYOFFICE_FILE_URL=https://example.com/document.docx ^
  --dart-define ONLYOFFICE_JWT_SECRET=my-secret-key ^
  --dart-define UPLOAD_URL=https://api.example.com/upload

Linux/macOS

cd example

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

VS Code 启动配置

在 .vscode/launch.json 中添加配置：

{
  "version": "0.2.0",
  "configurations": [
    {
      "name": "OnlyOffice Advanced Demo",
      "request": "launch",
      "type": "dart",
      "program": "example/lib/main_advanced.dart",
      "args": [
        "--dart-define",
        "ONLYOFFICE_SERVER_URL=https://doc.example.com",
        "--dart-define",
        "ONLYOFFICE_FILE_URL=https://example.com/document.docx",
        "--dart-define",
        "ONLYOFFICE_JWT_SECRET=my-secret-key",
        "--dart-define",
        "UPLOAD_URL=https://api.example.com/upload"
      ]
    }
  ]
}

Android Studio / IntelliJ 配置

1. 打开 Run → Edit Configurations...
2. 点击 + → 选择 Flutter
3. 设置：
   • Name: OnlyOffice Advanced Demo
   • Dart entrypoint: example/lib/main_advanced.dart
   • Additional run args:

     --dart-define ONLYOFFICE_SERVER_URL=https://doc.example.com --dart-define ONLYOFFICE_FILE_URL=https://example.com/document.docx
     

运行前检查清单

1. 确保依赖已安装

cd example
flutter pub get

2. 检查设备连接

flutter devices

3. 权限配置（Android）

在 example/android/app/src/main/AndroidManifest.xml 中添加：

<uses-permission android:name="android.permission.INTERNET"/>
<uses-permission android:name="android.permission.CAMERA"/>
<uses-permission android:name="android.permission.READ_EXTERNAL_STORAGE"/>
<uses-permission android:name="android.permission.WRITE_EXTERNAL_STORAGE"/>

4. 权限配置（iOS）

在 example/ios/Runner/Info.plist 中添加：

<key>NSCameraUsageDescription</key>
<string>需要访问相机以插入图片到文档</string>
<key>NSPhotoLibraryUsageDescription</key>
<string>需要访问相册以插入图片到文档</string>

常见问题

Q: 提示 "Target file not found"

解决方案：

# 确保在 example 目录下
cd example

# 使用相对路径
flutter run -t lib/main_advanced.dart

Q: 环境变量未生效

解决方案：

• 检查变量名拼写是否正确
• 确保使用 --dart-define 而不是 --dart-define-from-file
• 在代码中打印变量值检查：

  print('Server URL: $_serverUrl');
  

Q: 图片选择器无法打开

解决方案：

1. 检查权限配置（见上方）
2. Android: 确保在 AndroidManifest.xml 中添加权限
3. iOS: 确保在 Info.plist 中添加权限描述

Q: 文件下载失败

解决方案：

• 检查网络连接
• 确保 UPLOAD_URL 配置正确
• 检查服务器是否支持 CORS

调试技巧

1. 查看环境变量

在 main_advanced.dart 中添加：

void main() {
  print('=== 环境变量检查 ===');
  print('Server URL: $_serverUrl');
  print('File URL: $_fileUrl');
  print('JWT Secret: ${_jwtSecret.isNotEmpty ? "已设置" : "未设置"}');
  print('Upload URL: $_uploadUrl');
  print('==================');
  
  runApp(const AdvancedDemoApp());
}

2. 启用详细日志

flutter run -t lib/main_advanced.dart --verbose

3. 热重载

运行后按 r 键进行热重载，按 R 键进行热重启。

运行不同平台

Android

flutter run -t lib/main_advanced.dart -d android \
  --dart-define ONLYOFFICE_SERVER_URL=https://...

iOS

flutter run -t lib/main_advanced.dart -d ios \
  --dart-define ONLYOFFICE_SERVER_URL=https://...

Web

flutter run -t lib/main_advanced.dart -d chrome \
  --dart-define ONLYOFFICE_SERVER_URL=https://...

快速测试（最小配置）

如果只是想快速测试，可以只设置必需变量：

cd example

flutter run -t lib/main_advanced.dart \
  --dart-define ONLYOFFICE_SERVER_URL=https://doc.example.com \
  --dart-define ONLYOFFICE_FILE_URL=https://example.com/document.docx

注意：不设置 UPLOAD_URL 时，图片插入功能会使用本地路径（仅用于演示）。

下一步

运行成功后，您可以：

1. ✅ 测试文档查看和编辑
2. ✅ 测试图片插入功能（相机/相册）
3. ✅ 测试文件下载功能
4. ✅ 测试审阅模式
5. ✅ 测试自定义 JavaScript 执行

查看 高级功能指南 了解更多功能！