flutter_synckit 0.0.3

一款集成 WebDAV 的轻量级 Flutter 同步库，支持断点续传、离线优先、冲突处理等高级功能。

Flutter Sync Kit

一款集成 WebDAV 的轻量级 Flutter 同步库，支持断点续传、离线优先、冲突处理等高级功能。

特性

• 多协议兼容：原生支持 WebDAV，可一键接入 Nextcloud、OwnCloud 及任意标准 WebDAV 服务
• 断点续传：
  • 智能分块：大文件自动切片，内存占用极低
  • 状态持久化：实时记录分片进度，网络中断后秒级续传，零重复流量
• 离线优先：SQLite + SharedPreferences 双缓存，离线读写无感；网络恢复静默同步，数据不丢一步
• 冲突处理：自动检测版本冲突，提供「本地优先」「远程优先」「智能合并」三种策略，一键决策
• 完整校验：上传前 SHA-256 预校验，下载后二次比对，100% 确保文件一致性

极简 API

一行代码即可同步，网络细节全屏蔽

• 同步 / 上传 / 下载 单方法调用，无需关心线程、重试、鉴权
• 实时回调：上传完成、失败、进度、同步结束……全程事件推送，业务逻辑随心定制
• 精准异常：错误码 + 详细描述 + 最佳实践提示，三分钟定位问题根源

安装

dependencies:
  flutter_synckit: ^1.0.0

快速开始

1. 初始化

import 'package:flutter_synckit/flutter_synckit.dart';

final syncKit = FlutterSyncKit();

await syncKit.initialize(
  SyncConfig(
    serverUrl: 'https://your-webdav-server.com',
    username: 'your-username',
    password: 'your-password',
    localDirectory: '/path/to/local/dir',
    conflictStrategy: ConflictStrategy.smartMerge,
  ),
);

2. 执行同步

// 完整同步
final result = await syncKit.sync();
print('同步完成: ${result.successCount}/${result.totalFiles}');

// 上传单个文件
await syncKit.upload('/local/path/file.txt', remotePath: '/remote/path/file.txt');

// 下载单个文件
await syncKit.download('/remote/path/file.txt', localPath: '/local/path/file.txt');

3. 监听事件

syncKit.eventStream.listen((event) {
  switch (event.type) {
    case SyncEventType.syncStarted:
      print('同步开始');
      break;
    case SyncEventType.taskProgress:
      print('进度: ${event.progress}%');
      break;
    case SyncEventType.syncCompleted:
      print('同步完成');
      break;
    case SyncEventType.conflictDetected:
      print('检测到冲突: ${event.file?.name}');
      break;
    default:
      break;
  }
});

配置选项

SyncConfig(
  serverUrl: 'https://your-webdav-server.com',  // WebDAV 服务器地址
  username: 'user',                              // 用户名
  password: 'pass',                              // 密码
  localDirectory: '/path/to/local',              // 本地同步目录
  remoteDirectory: '/',                          // 远程同步目录
  conflictStrategy: ConflictStrategy.smartMerge, // 冲突解决策略
  chunkSize: 1024 * 1024,                        // 分块大小（默认 1MB）
  maxConcurrentTasks: 3,                         // 最大并发任务数
  maxRetries: 3,                                 // 最大重试次数
  enableChecksum: true,                          // 启用校验
  autoSync: false,                               // 自动同步
  syncOnWifiOnly: true,                          // 仅 WiFi 下同步
)

冲突解决策略

• ConflictStrategy.localFirst - 本地优先，本地版本覆盖远程
• ConflictStrategy.remoteFirst - 远程优先，远程版本覆盖本地
• ConflictStrategy.smartMerge - 智能合并，根据时间戳自动选择（默认）

错误处理

try {
  await syncKit.sync();
} on SyncException catch (e) {
  print('错误代码: ${e.code}');
  print('错误信息: ${e.message}');
  print('解决建议: ${e.suggestion}');
}

平台支持

平台	支持
Android	✅
iOS	✅
macOS	✅
Windows	✅
Linux	✅

完整示例

查看 example 目录获取完整的示例应用。

许可证

MIT License