yx_only_office_flutter/docs/QUICK_START.md

# 快速参考指南

## 基本用法

### 1. 查看文档（最简单）

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

YxOnlyOfficeViewer.create(
  serverUrl: 'https://your-server.com',
  fileUrl: 'https://example.com/document.docx',
  mode: 'view',
)
```

### 2. 编辑文档

```dart
YxOnlyOfficeViewer.create(
  serverUrl: 'https://your-server.com',
  fileUrl: 'https://example.com/document.docx',
  mode: 'edit',
  user: OnlyOfficeUser(id: 'user1', name: '张三'),
)
```

### 3. 使用 JWT 签名

```dart
YxOnlyOfficeViewer.create(
  serverUrl: 'https://your-server.com',
  fileUrl: 'https://example.com/document.docx',
  tokenFactory: OnlyOfficeJwtSigner('your-secret-key'),
)
```

## 常用配置

### 权限控制

```dart
YxOnlyOfficeViewer.create(
  serverUrl: 'https://your-server.com',
  fileUrl: 'https://example.com/document.docx',
  allowDownload: true,   // 允许下载
  allowPrint: false,     // 禁止打印
)
```

### UI 定制

```dart
YxOnlyOfficeViewer.create(
  serverUrl: 'https://your-server.com',
  fileUrl: 'https://example.com/document.docx',
  customization: OnlyOfficeCustomization(
    compactToolbar: true,      // 紧凑工具栏
    hideRightMenu: false,      // 显示右侧菜单
    hideLeftMenu: false,       // 显示左侧菜单
  ),
)
```

### 用户信息

```dart
YxOnlyOfficeViewer.create(
  serverUrl: 'https://your-server.com',
  fileUrl: 'https://example.com/document.docx',
  user: OnlyOfficeUser(
    id: 'user123',
    name: '张三',
    email: 'zhangsan@example.com',
    group: '开发部',
  ),
)
```

## 事件处理

### 基础事件

```dart
YxOnlyOfficeViewer.create(
  serverUrl: 'https://your-server.com',
  fileUrl: 'https://example.com/document.docx',
  onError: (error) {
    print('错误: $error');
  },
  onAppClose: () {
    print('用户请求关闭');
  },
)
```

### 编辑相关事件

```dart
YxOnlyOfficeViewer.create(
  serverUrl: 'https://your-server.com',
  fileUrl: 'https://example.com/document.docx',
  mode: 'edit',
  onDocumentStateChange: (data) {
    final hasChanges = data == true;
    print('文档${hasChanges ? "已修改" : "未修改"}');
  },
  onRequestSaveAs: (data) {
    print('用户请求另存为: $data');
  },
  onRequestInsertImage: (data) {
    print('用户请求插入图片');
    // 打开图片选择器
  },
)
```

### 通用事件处理

```dart
YxOnlyOfficeViewer.create(
  serverUrl: 'https://your-server.com',
  fileUrl: 'https://example.com/document.docx',
  onEvent: (event, data) {
    print('事件: $event, 数据: $data');
  },
)
```

## 高级配置

### 手动构建配置

```dart
final config = OnlyOfficeConfigFactory.create(
  fileUrl: 'https://example.com/document.docx',
  mode: 'edit',
  title: '我的文档.docx',
  lang: 'zh-CN',
  key: 'custom-document-key', // 自定义文档 key
  user: OnlyOfficeUser(id: 'user1', name: '张三'),
  customization: OnlyOfficeCustomization(
    compactToolbar: true,
  ),
  tokenFactory: OnlyOfficeJwtSigner('secret'),
);

YxOnlyOfficeViewer(
  serverUrl: 'https://your-server.com',
  config: config,
)
```

### 完全自定义配置

```dart
final document = OnlyOfficeDocument(
  fileType: 'docx',
  key: 'unique-key-123',
  title: '文档标题.docx',
  url: 'https://example.com/document.docx',
  permissions: OnlyOfficePermissions(
    edit: true,
    download: true,
    print: false,
    review: true,
    comment: true,
  ),
);

final editorConfig = OnlyOfficeEditorConfig(
  mode: 'edit',
  lang: 'zh-CN',
  user: OnlyOfficeUser(id: 'user1', name: '张三'),
  customization: OnlyOfficeCustomization(
    compactToolbar: true,
  ),
);

final config = OnlyOfficeConfig(
  document: document,
  documentType: 'word',
  editorConfig: editorConfig,
);

YxOnlyOfficeViewer(
  serverUrl: 'https://your-server.com',
  config: config,
)
```

## 支持的文档类型

| 类型 | documentType | 扩展名 |
|------|--------------|--------|
| 文字处理 | `word` | doc, docx, odt, rtf, txt, pdf 等 |
| 电子表格 | `cell` | xls, xlsx, ods, csv 等 |
| 演示文稿 | `slide` | ppt, pptx, odp 等 |

插件会自动根据文件扩展名识别文档类型。

## 常见问题速查

### Q: 如何判断文档是否被修改？

```dart
onDocumentStateChange: (data) {
  final hasChanges = data == true;
  if (hasChanges) {
    // 显示"未保存"提示
  }
}
```

### Q: 如何保存编辑后的文档？

方式 1：服务端回调（推荐）
```dart
OnlyOfficeEditorConfig(
  callbackUrl: 'https://your-server.com/callback',
)
```

方式 2：客户端下载
```dart
onDownloadAs: (fileType, url) {
  // 下载 url 指向的文档
}
```

### Q: 如何自定义加载动画？

```dart
YxOnlyOfficeViewer.create(
  serverUrl: 'https://your-server.com',
  fileUrl: 'https://example.com/document.docx',
  loadingBuilder: (context) {
    return Center(
      child: CircularProgressIndicator(),
    );
  },
)
```

### Q: 如何处理错误？

```dart
YxOnlyOfficeViewer.create(
  serverUrl: 'https://your-server.com',
  fileUrl: 'https://example.com/document.docx',
  onError: (error) {
    // 显示错误提示
    ScaffoldMessenger.of(context).showSnackBar(
      SnackBar(content: Text('错误: $error')),
    );
  },
  errorBuilder: (context, error) {
    return Center(
      child: Text('加载失败: $error'),
    );
  },
)
```

## 完整示例

查看 `example/lib/main.dart` 获取完整的可运行示例。

## 更多信息

- [完整 README](../README.md)
- [ONLYOFFICE 官方文档](https://api.onlyoffice.com/docs/docs-api/)
- [示例说明](example/README.md)