# 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/)