414 lines
9.0 KiB
Markdown
414 lines
9.0 KiB
Markdown
# API 参考文档
|
||
|
||
## 核心类
|
||
|
||
### YxOnlyOfficeViewer
|
||
|
||
主要的 Widget，用于显示 ONLYOFFICE 文档编辑器。
|
||
|
||
#### 构造函数
|
||
|
||
##### YxOnlyOfficeViewer()
|
||
|
||
```dart
|
||
YxOnlyOfficeViewer({
|
||
required String serverUrl,
|
||
required OnlyOfficeConfig config,
|
||
Function(String)? onError,
|
||
Function()? onAppClose,
|
||
Function(String, String)? onDownloadAs,
|
||
Function(dynamic)? onRequestSaveAs,
|
||
Function(dynamic)? onRequestInsertImage,
|
||
Function(dynamic)? onDocumentStateChange,
|
||
Function(dynamic)? onMetaChange,
|
||
Function(dynamic)? onMakeActionLink,
|
||
Function(String event, dynamic data)? onEvent,
|
||
WidgetBuilder? loadingBuilder,
|
||
Widget Function(BuildContext context, Object error)? errorBuilder,
|
||
bool restrictNavigationToInitialPage = true,
|
||
})
|
||
```
|
||
|
||
##### YxOnlyOfficeViewer.create() (推荐)
|
||
|
||
```dart
|
||
YxOnlyOfficeViewer.create({
|
||
required String serverUrl,
|
||
required String fileUrl,
|
||
String mode = 'view',
|
||
String? title,
|
||
bool allowDownload = true,
|
||
bool allowPrint = false,
|
||
OnlyOfficeUser? user,
|
||
OnlyOfficeCustomization? customization,
|
||
OnlyOfficeJwtSigner? tokenFactory,
|
||
Map<String, dynamic>? extra,
|
||
// ... 所有事件回调
|
||
})
|
||
```
|
||
|
||
#### 参数说明
|
||
|
||
| 参数 | 类型 | 必需 | 说明 |
|
||
|------|------|------|------|
|
||
| `serverUrl` | String | ✅ | ONLYOFFICE Document Server 地址 |
|
||
| `config` | OnlyOfficeConfig | ✅ | 完整配置对象 |
|
||
| `fileUrl` | String | ✅ | 文档文件 URL（仅 create） |
|
||
| `mode` | String | ❌ | 模式：'view' 或 'edit' |
|
||
| `onError` | Function(String)? | ❌ | 错误回调 |
|
||
| `onAppClose` | Function()? | ❌ | 关闭请求回调 |
|
||
| `onDownloadAs` | Function(String, String)? | ❌ | 下载完成回调 |
|
||
| `onRequestSaveAs` | Function(dynamic)? | ❌ | 另存为请求回调 |
|
||
| `onRequestInsertImage` | Function(dynamic)? | ❌ | 插入图片请求回调 |
|
||
| `onDocumentStateChange` | Function(dynamic)? | ❌ | 文档状态变化回调 |
|
||
| `onMetaChange` | Function(dynamic)? | ❌ | 元数据变化回调 |
|
||
| `onMakeActionLink` | Function(dynamic)? | ❌ | 创建操作链接回调 |
|
||
| `onEvent` | Function(String, dynamic)? | ❌ | 通用事件回调 |
|
||
| `loadingBuilder` | WidgetBuilder? | ❌ | 自定义加载组件 |
|
||
| `errorBuilder` | Widget Function(...)? | ❌ | 自定义错误组件 |
|
||
| `restrictNavigationToInitialPage` | bool | ❌ | 是否限制导航（默认 true） |
|
||
|
||
---
|
||
|
||
## 配置类
|
||
|
||
### OnlyOfficeConfig
|
||
|
||
顶层配置对象。
|
||
|
||
```dart
|
||
OnlyOfficeConfig({
|
||
required OnlyOfficeDocument document,
|
||
required String documentType,
|
||
required OnlyOfficeEditorConfig editorConfig,
|
||
String type = 'mobile',
|
||
String? token,
|
||
Map<String, dynamic>? extra,
|
||
})
|
||
```
|
||
|
||
#### 属性
|
||
|
||
- `document`: 文档信息
|
||
- `documentType`: 文档类型（'word', 'cell', 'slide'）
|
||
- `editorConfig`: 编辑器配置
|
||
- `type`: 客户端类型（默认 'mobile'）
|
||
- `token`: JWT 令牌
|
||
- `extra`: 额外配置
|
||
|
||
---
|
||
|
||
### OnlyOfficeDocument
|
||
|
||
文档元数据。
|
||
|
||
```dart
|
||
OnlyOfficeDocument({
|
||
required String fileType,
|
||
required String key,
|
||
required String title,
|
||
required String url,
|
||
OnlyOfficePermissions? permissions,
|
||
Map<String, dynamic>? info,
|
||
Map<String, dynamic>? extra,
|
||
})
|
||
```
|
||
|
||
#### 属性
|
||
|
||
- `fileType`: 文件扩展名（如 'docx'）
|
||
- `key`: 文档唯一标识
|
||
- `title`: 文档标题
|
||
- `url`: 文档下载地址
|
||
- `permissions`: 文档权限
|
||
- `info`: 文档信息
|
||
- `extra`: 额外字段
|
||
|
||
#### 静态方法
|
||
|
||
```dart
|
||
static String generateKeyFromUrl(String url)
|
||
```
|
||
根据 URL 生成唯一的文档 key（使用 SHA256）。
|
||
|
||
---
|
||
|
||
### OnlyOfficeEditorConfig
|
||
|
||
编辑器配置。
|
||
|
||
```dart
|
||
OnlyOfficeEditorConfig({
|
||
String mode = 'view',
|
||
String lang = 'zh-CN',
|
||
String? region,
|
||
String? callbackUrl,
|
||
OnlyOfficeUser? user,
|
||
OnlyOfficePermissions? permissions,
|
||
OnlyOfficeCustomization? customization,
|
||
Map<String, dynamic>? extra,
|
||
})
|
||
```
|
||
|
||
#### 属性
|
||
|
||
- `mode`: 编辑器模式（'view' 或 'edit'）
|
||
- `lang`: 界面语言（默认 'zh-CN'）
|
||
- `region`: 地区设置
|
||
- `callbackUrl`: 服务端回调地址
|
||
- `user`: 用户信息
|
||
- `permissions`: 编辑器权限
|
||
- `customization`: UI 定制
|
||
- `extra`: 额外配置
|
||
|
||
---
|
||
|
||
### OnlyOfficePermissions
|
||
|
||
权限配置。
|
||
|
||
```dart
|
||
OnlyOfficePermissions({
|
||
bool? edit,
|
||
bool? download,
|
||
bool? print,
|
||
bool? review,
|
||
bool? comment,
|
||
bool? copy,
|
||
bool? fillForms,
|
||
Map<String, dynamic>? extra,
|
||
})
|
||
```
|
||
|
||
#### 属性
|
||
|
||
| 属性 | 类型 | 说明 |
|
||
|------|------|------|
|
||
| `edit` | bool? | 是否允许编辑 |
|
||
| `download` | bool? | 是否允许下载 |
|
||
| `print` | bool? | 是否允许打印 |
|
||
| `review` | bool? | 是否允许审阅 |
|
||
| `comment` | bool? | 是否允许评论 |
|
||
| `copy` | bool? | 是否允许复制 |
|
||
| `fillForms` | bool? | 是否允许填写表单 |
|
||
|
||
---
|
||
|
||
### OnlyOfficeUser
|
||
|
||
用户信息。
|
||
|
||
```dart
|
||
OnlyOfficeUser({
|
||
required String id,
|
||
required String name,
|
||
String? group,
|
||
String? email,
|
||
Map<String, dynamic>? extra,
|
||
})
|
||
```
|
||
|
||
#### 属性
|
||
|
||
- `id`: 用户 ID（必需）
|
||
- `name`: 用户名称（必需）
|
||
- `group`: 用户组
|
||
- `email`: 用户邮箱
|
||
- `extra`: 额外字段
|
||
|
||
---
|
||
|
||
### OnlyOfficeCustomization
|
||
|
||
UI 定制选项。
|
||
|
||
```dart
|
||
OnlyOfficeCustomization({
|
||
bool? hideRightMenu,
|
||
bool? hideLeftMenu,
|
||
bool? hideRulers,
|
||
bool? compactToolbar,
|
||
bool? toolbarNoTabs,
|
||
bool? showReviewChanges,
|
||
Map<String, dynamic>? extra,
|
||
})
|
||
```
|
||
|
||
#### 属性
|
||
|
||
| 属性 | 类型 | 说明 |
|
||
|------|------|------|
|
||
| `hideRightMenu` | bool? | 隐藏右侧菜单 |
|
||
| `hideLeftMenu` | bool? | 隐藏左侧菜单 |
|
||
| `hideRulers` | bool? | 隐藏标尺 |
|
||
| `compactToolbar` | bool? | 紧凑工具栏 |
|
||
| `toolbarNoTabs` | bool? | 工具栏无标签页 |
|
||
| `showReviewChanges` | bool? | 显示审阅更改 |
|
||
|
||
---
|
||
|
||
## 工厂类
|
||
|
||
### OnlyOfficeConfigFactory
|
||
|
||
配置工厂类，用于快速创建配置。
|
||
|
||
#### 静态方法
|
||
|
||
```dart
|
||
static OnlyOfficeConfig create({
|
||
required String fileUrl,
|
||
String mode = 'view',
|
||
String? title,
|
||
bool allowDownload = true,
|
||
bool allowPrint = false,
|
||
OnlyOfficeUser? user,
|
||
OnlyOfficeCustomization? customization,
|
||
OnlyOfficeJwtSigner? tokenFactory,
|
||
Map<String, dynamic>? extra,
|
||
String lang = 'zh-CN',
|
||
String? key,
|
||
})
|
||
```
|
||
|
||
创建一个完整的 `OnlyOfficeConfig` 对象。
|
||
|
||
---
|
||
|
||
## 工具类
|
||
|
||
### OnlyOfficeJwtSigner
|
||
|
||
JWT 签名工具。
|
||
|
||
```dart
|
||
OnlyOfficeJwtSigner(String secret)
|
||
```
|
||
|
||
#### 方法
|
||
|
||
```dart
|
||
String sign(Map<String, dynamic> payload)
|
||
```
|
||
|
||
使用 HMAC-SHA256 算法签名配置对象。
|
||
|
||
**示例：**
|
||
|
||
```dart
|
||
final signer = OnlyOfficeJwtSigner('your-secret-key');
|
||
final token = signer.sign(config.toJson());
|
||
```
|
||
|
||
---
|
||
|
||
## 事件类型
|
||
|
||
### 事件回调签名
|
||
|
||
| 事件 | 回调签名 | 说明 |
|
||
|------|----------|------|
|
||
| `onError` | `Function(String error)` | 错误发生 |
|
||
| `onAppClose` | `Function()` | 用户请求关闭 |
|
||
| `onDownloadAs` | `Function(String fileType, String url)` | 下载完成 |
|
||
| `onRequestSaveAs` | `Function(dynamic data)` | 请求另存为 |
|
||
| `onRequestInsertImage` | `Function(dynamic data)` | 请求插入图片 |
|
||
| `onDocumentStateChange` | `Function(dynamic data)` | 文档状态变化 |
|
||
| `onMetaChange` | `Function(dynamic data)` | 元数据变化 |
|
||
| `onMakeActionLink` | `Function(dynamic data)` | 创建操作链接 |
|
||
| `onEvent` | `Function(String event, dynamic data)` | 通用事件 |
|
||
|
||
---
|
||
|
||
## 废弃的 API
|
||
|
||
### OnlyOfficeViewConfigFactory (已废弃)
|
||
|
||
使用 `OnlyOfficeConfigFactory` 替代。
|
||
|
||
```dart
|
||
@Deprecated('Use OnlyOfficeConfigFactory instead')
|
||
class OnlyOfficeViewConfigFactory {
|
||
static OnlyOfficeConfig fromUrl({...})
|
||
}
|
||
```
|
||
|
||
### YxOnlyOfficeViewer.view (已废弃)
|
||
|
||
使用 `YxOnlyOfficeViewer.create` 替代。
|
||
|
||
```dart
|
||
@Deprecated('Use YxOnlyOfficeViewer.create with mode="view" instead')
|
||
factory YxOnlyOfficeViewer.view({...})
|
||
```
|
||
|
||
---
|
||
|
||
## 常量
|
||
|
||
### 文档类型
|
||
|
||
- `'word'`: 文字处理文档
|
||
- `'cell'`: 电子表格
|
||
- `'slide'`: 演示文稿
|
||
|
||
### 编辑器模式
|
||
|
||
- `'view'`: 只读模式
|
||
- `'edit'`: 编辑模式
|
||
|
||
### 客户端类型
|
||
|
||
- `'desktop'`: 桌面端
|
||
- `'mobile'`: 移动端（默认）
|
||
- `'embedded'`: 嵌入式
|
||
|
||
---
|
||
|
||
## 完整示例
|
||
|
||
```dart
|
||
import 'package:flutter/material.dart';
|
||
import 'package:yx_only_office_flutter/yx_only_office_flutter.dart';
|
||
|
||
class MyDocumentViewer extends StatelessWidget {
|
||
@override
|
||
Widget build(BuildContext context) {
|
||
return Scaffold(
|
||
appBar: AppBar(title: Text('文档查看')),
|
||
body: YxOnlyOfficeViewer.create(
|
||
serverUrl: 'https://your-server.com',
|
||
fileUrl: 'https://example.com/document.docx',
|
||
mode: 'edit',
|
||
user: OnlyOfficeUser(
|
||
id: 'user123',
|
||
name: '张三',
|
||
email: 'zhangsan@example.com',
|
||
),
|
||
customization: OnlyOfficeCustomization(
|
||
compactToolbar: true,
|
||
),
|
||
tokenFactory: OnlyOfficeJwtSigner('secret'),
|
||
onDocumentStateChange: (data) {
|
||
print('文档状态: $data');
|
||
},
|
||
onError: (error) {
|
||
ScaffoldMessenger.of(context).showSnackBar(
|
||
SnackBar(content: Text('错误: $error')),
|
||
);
|
||
},
|
||
),
|
||
);
|
||
}
|
||
}
|
||
```
|
||
|
||
---
|
||
|
||
## 更多信息
|
||
|
||
- [快速开始指南](QUICK_START.md)
|
||
- [完整 README](../README.md)
|
||
- [ONLYOFFICE 官方文档](https://api.onlyoffice.com/docs/docs-api/)
|
||
|