wangyang
/
yx_only_office_flutter
1
0
Fork 0
Code Pull Requests Actions Releases Activity
yx_only_office_flutter/docs/QUICK_START.md

5.5 KiB
Raw Blame History

快速参考指南

基本用法

1. 查看文档（最简单）

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. 编辑文档

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

3. 使用 JWT 签名

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

常用配置

权限控制

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

UI 定制

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

用户信息

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

事件处理

基础事件

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

编辑相关事件

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('用户请求插入图片');
    // 打开图片选择器
  },
)

通用事件处理

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

高级配置

手动构建配置

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,
)

完全自定义配置

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: 如何判断文档是否被修改？

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

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

方式 1：服务端回调（推荐）

OnlyOfficeEditorConfig(
  callbackUrl: 'https://your-server.com/callback',
)

方式 2：客户端下载

onDownloadAs: (fileType, url) {
  // 下载 url 指向的文档
}

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

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

Q: 如何处理错误？

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 获取完整的可运行示例。

更多信息