Flutter 与 OpenHarmony 深度融合：实现分布式文件共享与跨设备协同编辑系统

引言

在多设备协同办公场景中，用户常面临这样的痛点：

• 手机上收到一份合同，想用平板的大屏签字；
• 在 PC 上写了一半的文档，通勤路上想用手机继续编辑；
• 家人用电视查看照片，你希望实时添加新拍的照片到相册。

OpenHarmony 提供了强大的分布式文件服务（Distributed File Service, DFS），支持跨设备文件自动同步、共享访问、协同编辑。而 Flutter 凭借其高性能 UI 能力，可构建统一的文档/媒体管理界面。

本文将带你从零开发一个“分布式协作文档中心”，实现：

• 多设备间Markdown 文档自动同步；
• 支持多人同时编辑（OT 算法基础版）；
• 文件通过分布式 URI安全共享；
• 编辑内容实时预览（Flutter + Markdown 渲染）。

这是目前社区首篇完整实现 Flutter + OpenHarmony 分布式文件协同的实战教程。

一、技术原理：DFS 如何工作？

OpenHarmony 的分布式文件系统基于分布式数据管理（DDM） + 软总线（DSoftBus），核心特性包括：

• 统一命名空间：dfs://<bundleId>/<path>可跨设备访问；
• 自动同步：文件变更后，系统自动推送到可信设备；
• 权限控制：仅同应用、同账号、已配对设备可访问；
• 断点续传：大文件传输支持中断恢复。

+------------------+ +------------------+ | 手机 (Flutter) | | 平板 (Flutter) | | - 创建 doc.md |<----->| - 实时看到更新 | +--------+---------+ DFS +--------+---------+ | | [DistributedFileManager] [DistributedFileManager] | | +---------- 共享文件 <--------+ dfs://com.example.docs/docs/doc.md

✅ 优势：开发者无需手动处理网络传输、冲突合并、权限校验。

二、整体架构设计

关键模块：

• DfsFilePlugin：封装 DFS API，提供 Dart 接口；
• DistributedFileManager：OpenHarmony 原生文件管理器；
• 协同编辑引擎：基于简易 OT（Operational Transformation）算法；
• 实时预览：使用flutter_markdown渲染。

三、原生侧：分布式文件操作封装（ArkTS）

1. 权限与配置

// module.json5{"module":{"requestPermissions":[{"name":"ohos.permission.DISTRIBUTED_DATASYNC"},{"name":"ohos.permission.READ_MEDIA"},{"name":"ohos.permission.WRITE_MEDIA"}]}}

2. 创建DfsFileManager.ets

// services/DfsFileManager.etsimportfileManagerfrom'@ohos.file.distributedFileManager';importfsfrom'@ohos.file.fs';typeFileInfo={uri:string;name:string;size:number;lastModified:number;};classDfsFileManager{privatebundleName:string;constructor(bundleName:string){this.bundleName=bundleName;}// 获取分布式根目录 URIgetDfsRootUri():string{return`dfs://${this.bundleName}/docs/`;}// 列出所有文档asynclistFiles():Promise<FileInfo[]>{constrootUri=this.getDfsRootUri();try{constfiles=awaitfileManager.listFiles(rootUri);constresult:FileInfo[]=[];for(constfileoffiles){conststat=awaitfileManager.stat(file.uri);result.push({uri:file.uri,name:file.name,size:stat.size,lastModified:stat.mtime.getTime()});}returnresult;}catch(err){console.error('[DFS] listFiles failed:',err);return[];}}// 读取文件内容（UTF-8）asyncreadFile(uri:string):Promise<string>{constfd=awaitfileManager.openFile(uri,fs.OpenMode.READ_ONLY);constbuffer=newArrayBuffer(1024*1024);// 1MB maxconstbytesRead=awaitfileManager.read(fd,buffer);awaitfileManager.close(fd);constuint8Array=newUint8Array(buffer,0,bytesRead);returnString.fromCharCode(...uint8Array);}// 写入文件（覆盖）asyncwriteFile(uri:string,content:string):Promise<boolean>{try{constfd=awaitfileManager.openFile(uri,fs.OpenMode.CREATE|fs.OpenMode.WRITE_ONLY|fs.OpenMode.TRUNCATE);constencoder=newTextEncoder();constbuffer=encoder.encode(content);awaitfileManager.write(fd,buffer.buffer);awaitfileManager.close(fd);returntrue;}catch(err){console.error('[DFS] writeFile failed:',err);returnfalse;}}// 创建新文件asynccreateFile(name:string):Promise<string>{consturi=`${this.getDfsRootUri()}${name}`;awaitthis.writeFile(uri,'# 新文档\n\n开始编辑...');returnuri;}// 监听文件变更（用于协同）watchFile(uri:string,callback:(newContent:string)=>void):void{fileManager.on('change',uri,()=>{this.readFile(uri).then(content=>callback(content));});}// 停止监听unwatchFile(uri:string):void{fileManager.off('change',uri);}}constdfsManager=newDfsFileManager('com.example.flutter.dfsdemo');exportdefaultdfsManager;

3. 暴露给 Flutter（插件层）

// plugins/DfsFilePlugin.etsimportdfsManagerfrom'../services/DfsFileManager';import{MethodChannel,EventChannel}from'@flutter/engine';constMETHOD_CHANNEL='com.example.flutter/dfs/method';constEVENT_CHANNEL='com.example.flutter/dfs/event';exportclassDfsFilePlugin{privateeventSink:any=null;privatewatchingUri:string|null=null;init(){constmethodChannel=newMethodChannel(METHOD_CHANNEL);methodChannel.setMethodCallHandler(this.handleMethod.bind(this));consteventChannel=newEventChannel(EVENT_CHANNEL);eventChannel.setStreamHandler({onListen:(_,sink)=>this.eventSink=sink,onCancel:()=>this.eventSink=null});}privateasynchandleMethod(call:any):Promise<any>{switch(call.method){case'listFiles':constfiles=awaitdfsManager.listFiles();return{files};case'readFile':constcontent=awaitdfsManager.readFile(call.arguments['uri']);return{content};case'writeFile':constsuccess=awaitdfsManager.writeFile(call.arguments['uri'],call.arguments['content']);return{success};case'createFile':constnewUri=awaitdfsManager.createFile(call.arguments['name']);return{uri:newUri};case'watchFile':if(this.watchingUri){dfsManager.unwatchFile(this.watchingUri);}this.watchingUri=call.arguments['uri'];dfsManager.watchFile(this.watchingUri,(content)=>{if(this.eventSink){this.eventSink.success({type:'file_changed',content});}});return{success:true};case'unwatchFile':if(this.watchingUri){dfsManager.unwatchFile(this.watchingUri);this.watchingUri=null;}return{success:true};}thrownewError('Unknown method');}}

在EntryAbility.ets中初始化：

newDfsFilePlugin().init();

四、Flutter 侧：协同编辑与预览

1. 封装服务

// lib/services/dfs_service.dartimport'package:flutter/services.dart';classDfsService{staticconst_method=MethodChannel('com.example.flutter/dfs/method');staticconst_event=EventChannel('com.example.flutter/dfs/event');staticFuture<List<Map<String,dynamic>>>listFiles()async{finalresult=await_method.invokeMethod('listFiles');returnList<Map<String,dynamic>>.from(result['files']);}staticFuture<String>readFile(String uri)async{finalresult=await_method.invokeMethod('readFile',{'uri':uri});returnresult['content']asString;}staticFuture<bool>writeFile(String uri,String content)async{finalresult=await_method.invokeMethod('writeFile',{'uri':uri,'content':content,});returnresult['success']==true;}staticFuture<String>createFile(String name)async{finalresult=await_method.invokeMethod('createFile',{'name':name});returnresult['uri']asString;}staticFuture<void>watchFile(String uri)async{await_method.invokeMethod('watchFile',{'uri':uri});}staticFuture<void>unwatchFile()async{await_method.invokeMethod('unwatchFile');}staticStream<Map<String,dynamic>>onEvent()async*{awaitfor(finaleventin_event.receiveBroadcastStream()){yieldeventasMap<String,dynamic>;}}}

2. 协同编辑状态管理（简易 OT）

// lib/providers/editor_provider.dartimport'package:flutter_riverpod/flutter_riverpod.dart';finaleditorProvider=StateNotifierProvider<EditorManager,EditorState>((ref){returnEditorManager();});classEditorState{finalString?currentFileUri;finalString content;finalbool isRemoteUpdating;EditorState({this.currentFileUri,this.content='',this.isRemoteUpdating=false,});EditorStatecopyWith({String?currentFileUri,String?content,bool?isRemoteUpdating,}){returnEditorState(currentFileUri:currentFileUri??this.currentFileUri,content:content??this.content,isRemoteUpdating:isRemoteUpdating??this.isRemoteUpdating,);}}classEditorManagerextendsStateNotifier<EditorState>{EditorManager():super(EditorState());Future<void>openFile(String uri)async{state=state.copyWith(currentFileUri:uri,isRemoteUpdating:true);finalcontent=awaitDfsService.readFile(uri);awaitDfsService.watchFile(uri);state=state.copyWith(content:content,isRemoteUpdating:false);}Future<void>createNewFile(String name)async{finaluri=awaitDfsService.createFile(name);awaitopenFile(uri);}Future<void>updateContent(String newContent)async{if(state.isRemoteUpdating)return;// 防止本地覆盖远程变更if(state.currentFileUri!=null){awaitDfsService.writeFile(state.currentFileUri!,newContent);state=state.copyWith(content:newContent);}}voidhandleRemoteUpdate(String newContent){state=state.copyWith(content:newContent,isRemoteUpdating:true);Future.delayed(Duration(milliseconds:300),(){state=state.copyWith(isRemoteUpdating:false);});}@overridevoiddispose(){DfsService.unwatchFile();super.dispose();}}

3. 构建编辑界面

// lib/screens/editor_screen.dartimport'package:flutter_markdown/flutter_markdown.dart';classEditorScreenextendsConsumerWidget{@overrideWidgetbuild(BuildContext context,WidgetRef ref){finalstate=ref.watch(editorProvider);finaleditor=ref.read(editorProvider.notifier);// 监听远程变更useEffect((){finalsub=DfsService.onEvent().listen((event){if(event['type']=='file_changed'){editor.handleRemoteUpdate(event['content']asString);}});returnsub.cancel;},[]);returnScaffold(appBar:AppBar(title:Text('协作文档')),body:Row(children:[// 左侧：编辑区Expanded(flex:1,child:TextField(controller:TextEditingController(text:state.content),onChanged:(text)=>editor.updateContent(text),maxLines:null,decoration:InputDecoration(hintText:'输入 Markdown...',border:InputBorder.none,contentPadding:EdgeInsets.all(16),),enabled:!state.isRemoteUpdating,),),// 右侧：预览区Expanded(flex:1,child:Container(padding:EdgeInsets.all(16),child:Markdown(data:state.content),),),],),floatingActionButton:FloatingActionButton(onPressed:()=>_showCreateDialog(context,editor),child:Icon(Icons.add),),);}void_showCreateDialog(BuildContext context,EditorManager editor){finalcontroller=TextEditingController();showDialog(context:context,builder:(_)=>AlertDialog(title:Text('新建文档'),content:TextField(controller:controller,decoration:InputDecoration(hintText:'文件名.md'),),actions:[TextButton(onPressed:Navigator.of(context).pop,child:Text('取消')),TextButton(onPressed:(){finalname=controller.text.trim();if(name.isNotEmpty){editor.createNewFile(name.endsWith('.md')?name:'$name.md');Navigator.of(context).pop();}},child:Text('创建'),)],),);}}

五、关键问题与解决方案

六、测试流程

1. 手机和平板安装同一应用；
2. 手机创建report.md，输入内容；
3. 平板自动出现该文件，打开后实时同步；
4. 平板编辑内容，手机立即更新预览；
5. 断开网络后各自编辑，重连后以最后修改时间为准合并（简化逻辑）。

七、总结

本文实现了Flutter 应用通过 OpenHarmony DFS 进行分布式文件协同的完整方案，涵盖：

• 文件自动同步：利用 DFS 统一命名空间；
• 实时协同编辑：结合事件监听与状态管理；
• 所见即所得：Markdown 实时渲染；
• 安全共享：系统级权限保障。

此架构可轻松扩展至：

• 照片/视频共享相册；
• 跨设备笔记同步；
• 团队项目文档协作。

未来的办公，不再有“我的文件”和“你的文件”，只有“我们的文件”。

欢迎大家加入开源鸿蒙跨平台开发者社区，一起共建开源鸿蒙跨平台生态。