wangyang

yx_only_office_flutter

Fork 0

6.8 KiB

Raw Permalink Blame History

插件重构总结

概述

根据 ONLYOFFICE Docs API 官方文档和官方移动应用（Android、iOS）的实现，对 yx_only_office_flutter 插件进行了全面重构。

主要改进

1. 完整的编辑支持 ✨

之前： 仅支持只读查看模式

现在： 完整支持查看和编辑两种模式

// 查看模式
YxOnlyOfficeViewer.create(
  serverUrl: 'https://server.com',
  fileUrl: 'https://example.com/doc.docx',
  mode: 'view',
)

// 编辑模式
YxOnlyOfficeViewer.create(
  serverUrl: 'https://server.com',
  fileUrl: 'https://example.com/doc.docx',
  mode: 'edit',
  user: OnlyOfficeUser(id: 'user1', name: '张三'),
)

2. 标准化配置结构 🔧

之前： 配置结构不完全符合官方规范

现在： 完全遵循 ONLYOFFICE Docs API 配置规范

正确的 documentType 值（word, cell, slide）
完整的 document 和 editorConfig 结构
支持所有官方配置选项

3. 丰富的事件桥接 📡

之前： 仅支持 3 个基础事件

现在： 支持 9+ 个事件，覆盖所有常用场景

事件	用途
`onError`	错误处理
`onAppClose`	关闭请求
`onDownloadAs`	下载完成
`onRequestSaveAs`	✨ 另存为请求
`onRequestInsertImage`	✨ 插入图片请求
`onDocumentStateChange`	✨ 文档状态变化
`onMetaChange`	✨ 元数据变化
`onMakeActionLink`	✨ 创建操作链接
`onEvent`	✨ 通用事件处理器

4. 新的工厂类 🏭

之前： OnlyOfficeViewConfigFactory（仅支持查看）

现在： OnlyOfficeConfigFactory（支持查看和编辑）

final config = OnlyOfficeConfigFactory.create(
  fileUrl: 'https://example.com/doc.docx',
  mode: 'edit',  // 支持编辑模式
  user: OnlyOfficeUser(id: 'user1', name: '张三'),
  customization: OnlyOfficeCustomization(compactToolbar: true),
  tokenFactory: OnlyOfficeJwtSigner('secret'),
);

之前： YxOnlyOfficeViewer.view()（仅查看）

现在： YxOnlyOfficeViewer.create()（查看+编辑）

YxOnlyOfficeViewer.create(
  serverUrl: 'https://server.com',
  fileUrl: 'https://example.com/doc.docx',
  mode: 'edit',  // 可切换模式
  onDocumentStateChange: (data) {
    // 跟踪文档修改状态
  },
)

6. 内置 JWT 签名 🔐

之前： 需要外部实现 JWT 签名

现在： 内置 OnlyOfficeJwtSigner 类

final signer = OnlyOfficeJwtSigner('your-secret-key');
final token = signer.sign(config.toJson());

7. 完善的文档 📚

新增文档：

✅ 详细的 README.md
✅ CHANGELOG.md
✅ 快速开始指南 (docs/QUICK_START.md)
✅ API 参考文档 (docs/API_REFERENCE.md)
✅ 示例说明 (example/README.md)

8. 改进的示例应用 💡

之前： 简单的查看示例

现在： 完整的功能演示

✅ 查看/编辑模式切换
✅ 权限控制演示
✅ 事件处理演示
✅ 文档状态跟踪
✅ JWT 签名集成
✅ 友好的配置提示

技术细节

HTML 桥接增强

之前：

var bridgeEvents = {
  "onError": ...,
  "onRequestClose": ...,
  "onDownloadAs": ...
};

现在：

var bridgeEvents = {
  "onError": ...,
  "onRequestClose": ...,
  "onDownloadAs": ...,
  "onRequestSaveAs": ...,        // 新增
  "onRequestInsertImage": ...,   // 新增
  "onDocumentStateChange": ...,  // 新增
  "onMetaChange": ...,           // 新增
  "onMakeActionLink": ...        // 新增
};

配置结构对比

之前：

OnlyOfficeViewConfigFactory.fromUrl(
  fileUrl: url,
  // 仅支持查看模式
  allowDownload: true,
)

现在：

OnlyOfficeConfigFactory.create(
  fileUrl: url,
  mode: 'edit',           // 支持编辑
  lang: 'zh-CN',          // 可配置语言
  key: 'custom-key',      // 可自定义 key
  user: user,             // 用户信息
  customization: custom,  // UI 定制
  tokenFactory: signer,   // JWT 签名
)

向后兼容性 ✅

所有旧代码仍可正常工作：

// 旧代码 - 仍然有效
YxOnlyOfficeViewer.view(
  serverUrl: serverUrl,
  fileUrl: fileUrl,
  allowDownload: true,
)

// 新代码 - 推荐使用
YxOnlyOfficeViewer.create(
  serverUrl: serverUrl,
  fileUrl: fileUrl,
  mode: 'view',
  allowDownload: true,
)

已废弃但保留的 API：

OnlyOfficeViewConfigFactory.fromUrl() → 使用 OnlyOfficeConfigFactory.create()
YxOnlyOfficeViewer.view() → 使用 YxOnlyOfficeViewer.create()

文件变更清单

核心文件

✅ lib/src/onlyoffice_config.dart - 重构配置类
✅ lib/src/onlyoffice_html_builder.dart - 增强事件桥接
✅ lib/src/onlyoffice_viewer.dart - 新增编辑支持

文档文件

✅ README.md - 完整重写
✅ CHANGELOG.md - 新增
✅ docs/QUICK_START.md - 新增
✅ docs/API_REFERENCE.md - 新增

示例文件

✅ example/lib/main.dart - 完整重写
✅ example/README.md - 更新

测试验证

代码质量

✅ No linter errors found
✅ All files pass static analysis

功能验证

✅ 查看模式正常工作
✅ 编辑模式正常工作
✅ 事件回调正确触发
✅ JWT 签名正确生成
✅ 配置结构符合官方规范

使用建议

新项目

直接使用新 API：

YxOnlyOfficeViewer.create(
  serverUrl: 'https://server.com',
  fileUrl: 'https://example.com/doc.docx',
  mode: 'edit',
  user: OnlyOfficeUser(id: 'user1', name: '张三'),
  onDocumentStateChange: (data) {
    // 处理文档状态变化
  },
)

现有项目

可以继续使用旧 API，或逐步迁移到新 API：

// 旧代码
YxOnlyOfficeViewer.view(...)

// 迁移到新代码
YxOnlyOfficeViewer.create(mode: 'view', ...)

参考资源

总结

本次重构完全基于官方文档和官方移动应用的实现，确保了：

✅ 功能完整性 - 支持查看和编辑
✅ 标准合规性 - 完全遵循官方 API 规范
✅ 向后兼容性 - 旧代码仍可正常工作
✅ 易用性 - 提供便捷的工厂方法
✅ 可扩展性 - 支持自定义配置和事件
✅ 文档完善 - 提供详细的使用说明

插件现在已经是一个功能完整、符合官方规范的 ONLYOFFICE Flutter 集成方案！🎉

6.8 KiB Raw Permalink Blame History Unescape Escape