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

9.0 KiB
Raw Permalink Blame History

API 参考文档

核心类

YxOnlyOfficeViewer

主要的 Widget，用于显示 ONLYOFFICE 文档编辑器。

构造函数

YxOnlyOfficeViewer()
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() (推荐)
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

顶层配置对象。

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

文档元数据。

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: 额外字段

静态方法

static String generateKeyFromUrl(String url)

根据 URL 生成唯一的文档 key（使用 SHA256）。

OnlyOfficeEditorConfig

编辑器配置。

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

权限配置。

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

用户信息。

OnlyOfficeUser({
  required String id,
  required String name,
  String? group,
  String? email,
  Map<String, dynamic>? extra,
})

属性

  • id: 用户 ID（必需）
  • name: 用户名称（必需）
  • group: 用户组
  • email: 用户邮箱
  • extra: 额外字段

OnlyOfficeCustomization

UI 定制选项。

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

配置工厂类，用于快速创建配置。

静态方法

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 签名工具。

OnlyOfficeJwtSigner(String secret)

方法

String sign(Map<String, dynamic> payload)

使用 HMAC-SHA256 算法签名配置对象。

示例：

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 替代。

@Deprecated('Use OnlyOfficeConfigFactory instead')
class OnlyOfficeViewConfigFactory {
  static OnlyOfficeConfig fromUrl({...})
}

YxOnlyOfficeViewer.view (已废弃)

使用 YxOnlyOfficeViewer.create 替代。

@Deprecated('Use YxOnlyOfficeViewer.create with mode="view" instead')
factory YxOnlyOfficeViewer.view({...})

常量

文档类型

  • 'word': 文字处理文档
  • 'cell': 电子表格
  • 'slide': 演示文稿

编辑器模式

  • 'view': 只读模式
  • 'edit': 编辑模式

客户端类型

  • 'desktop': 桌面端
  • 'mobile': 移动端（默认）
  • 'embedded': 嵌入式

完整示例

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')),
          );
        },
      ),
    );
  }
}

更多信息