《HarmonyOS技术精讲-Core File Kit》第10篇：分布式文件编辑实战

ldsweet

102人浏览 · 2026-07-03 12:30:30

ldsweet · 2026-07-03 12:30:30 发布

在这里插入图片描述

实际开发中的问题：多设备文本协同编辑

在实际的HarmonyOS NEXT开发中，多设备协同编辑一个文件的需求很常见，比如一个笔记应用需要在手机和平板之间同步文本内容。很多开发者第一时间会想到使用网络通信实现，但这往往需要处理复杂的握手、数据序列化、冲突判断等逻辑。

其实HarmonyOS Core File Kit提供了一个更直接的方案：分布式文件系统。它能让不同设备上的应用看到同一个文件，就像在本地操作一样。这个能力本身不复杂，但真正麻烦的是文件变化的实时监听和编辑冲突的处理。官方示例多展示了文件的基础增删改查，但放到一个需要实时双向同步的文本编辑器里，很多隐藏的问题就会暴露出来。

它解决什么问题：本地化的实时同步

分布式文件系统的核心思路是：让文件物理上在设备A，但设备B通过虚拟路径访问，读写操作最终自动同步回原设备。

它适合什么场景？

笔记协同：手机和平板编辑同一份文档。
配置同步：多设备共享一份配置文件，一处修改，处处生效。
轻量级数据共享：不想引入中心化服务器时，直接通过文件共享数据。

它不适合什么场景？

高并发、低延迟的数据交换（比如实时对战游戏），因为分布式文件同步有网络延迟，不是实时的。
需要精细到字段级别的冲突检测，文件是以“文件”为粒度的，修改时是整个文件更新。

与网络通信对比：

方案	优点	缺点	推荐场景
分布式文件	开发成本低，API简单，无需自己处理网络连接。	冲突处理粒度粗（文件级），实时性比专用通信协议差。	轻量级数据同步，单文件编辑。
网络通信	可精细控制同步逻辑，实时性好。	开发复杂，需处理连接管理、数据序列化、断线重连。	高实时性、需要回调的业务。

环境与前期准备

DevEco Studio 版本：DevEco Studio 6.1.0 及以上
HarmonyOS SDK 版本：HarmonyOS 6.1.0(23) 及以上
目标设备：两台及以上支持分布式能力的手机/平板

核心实现：一个实时同步的文本编辑器

我们实现一个简单的文本编辑页面，核心逻辑是：

在两台设备上打开同一个分布式文件。
一台设备编辑并保存，另一台设备通过fileManager.watch自动检测到变化并刷新UI。

步骤1：获取分布式文件路径

分布式文件系统通过一个context.distributedFilesDir获取一个设备间的共享目录，所有设备都可以通过这个路径访问相同的文件。

// utils/FileHelper.ets
import { context } from '@kit.AbilityKit';
import { fileIo } from '@kit.CoreFileKit';

export function getDistributedFilePath(context: context.UIAbilityContext, fileName: string): string {
  // 获取分布式文件目录
  const distributedDir = context.distributedFilesDir;
  // 构建文件完整路径
  return `${distributedDir}/${fileName}`;
}

export async function ensureFileExists(filePath: string): Promise<void> {
  try {
    // 检查文件是否存在，不存在则创建
    let file = await fileIo.open(filePath, fileIo.OpenMode.CREATE);
    await fileIo.close(file);
  } catch (error) {
    console.error('文件创建失败', JSON.stringify(error));
  }
}

注意点：distributedFilesDir这个路径在不同设备上对应的物理存储路径不同，但逻辑上指向同一个文件。这个目录下的文件改动会自动在其他设备上同步，但这个同步有延迟（通常在几百毫秒到几秒内，取决于网络）。

步骤2：监听文件内容变化

fileManager.watch是核心API，它可以在文件内容、属性变化时回调。这里的关键是：监听器要全局有效，不能随着页面销毁就停止。

// utils/FileWatcher.ets
import { fileIo, fileManager } from '@kit.CoreFileKit';

export class FileWatcher {
  private watcher: fileManager.Watcher | null = null;
  private onFileChange: (() => void) | null = null;
  private path: string = '';

  // 开始监听文件变化
  startWatch(filePath: string, callback: () => void): void {
    this.path = filePath;
    this.onFileChange = callback;
    
    // 创建一个watcher实例，监听文件事件
    this.watcher = fileManager.createWatcher(this.path);
    if (this.watcher) {
      this.watcher.on('change', (events: Array<fileManager.WatcherEvent>) => {
        // events包含具体变化信息，我们仅关心有变化
        if (this.onFileChange) {
          this.onFileChange();
        }
      });
    }
  }

  // 停止监听
  stopWatch(): void {
    if (this.watcher) {
      // 移除所有监听器
      this.watcher.off('change');
      // 释放watcher资源
      this.watcher = null;
    }
  }
}

为什么不在页面里直接用watcher.on？
因为ArkUI的页面销毁时，如果watcher没有正确释放，可能导致内存泄漏或重复监听。通过一个单独的管理类，可以生命周期可控地管理。

步骤3：核心页面实现

现在把文件读写、文件监视、 UI刷新整合起来。

// pages/DistributeEditor.ets
import { context } from '@kit.AbilityKit';
import { fileIo } from '@kit.CoreFileKit';
import { getDistributedFilePath, ensureFileExists } from '../utils/FileHelper';
import { FileWatcher } from '../utils/FileWatcher';

@Entry
@Component
struct DistributeEditor {
  @State textContent: string = '';
  @State isEditing: boolean = false;
  private filePath: string = '';
  private watcher: FileWatcher = new FileWatcher();
  private currentContext: context.UIAbilityContext = getContext(this) as context.UIAbilityContext;

  aboutToAppear(): void {
    this.initDistributedFile();
  }

  // 初始化分布式文件
  async initDistributedFile(): Promise<void> {
    this.filePath = getDistributedFilePath(this.currentContext, 'distributed_note.txt');
    await ensureFileExists(this.filePath);
    
    // 先读取已有内容
    this.textContent = await this.readFileContent();
    
    // 开始监听文件变化
    this.watcher.startWatch(this.filePath, () => {
      // 当有其他设备写入文件时，自动刷新内容
      // 注意：这里的回调不在UI线程，需要切换到主线程更新UI
      this.readFileContent().then((content: string) => {
        if (!this.isEditing) {
          // 只在当前用户没有编辑时更新，避免覆盖用户正在输入的内容
          this.textContent = content;
        }
      });
    });
  }

  // 读取文件内容
  async readFileContent(): Promise<string> {
    try {
      let file = await fileIo.open(this.filePath, fileIo.OpenMode.READ_ONLY);
      let readSize = await fileIo.stat(this.filePath);
      let content: string = '';
      if (readSize.size > 0) {
        let buf = new ArrayBuffer(readSize.size);
        await fileIo.read(file.fd, buf);
        content = String.fromCharCode.apply(null, new Uint8Array(buf));
      }
      await fileIo.close(file);
      return content;
    } catch (e) {
      console.error('读取文件失败', JSON.stringify(e));
      return '';
    }
  }

  // 保存内容并写入文件
  async saveFileContent() {
    // 标记当前用户正在编辑，避免被其他设备的watcher覆盖
    this.isEditing = true;
    try {
      let file = await fileIo.open(this.filePath, fileIo.OpenMode.WRITE_ONLY | fileIo.OpenMode.TRUNC);
      let encodedContent = this.textContent;
      let buf = new ArrayBuffer(encodedContent.length);
      let view = new Uint8Array(buf);
      for (let i = 0; i < encodedContent.length; i++) {
        view[i] = encodedContent.charCodeAt(i);
      }
      await fileIo.write(file.fd, buf);
      await fileIo.close(file);
      // 保存完成后，恢复编辑标记
      this.isEditing = false;
    } catch (e) {
      console.error('写入文件失败', JSON.stringify(e));
      this.isEditing = false;
    }
  }

  build() {
    Column() {
      TextInput({ placeholder: '在此编辑文本...', text: this.textContent })
        .onChange((value: string) => {
          this.textContent = value;
        })
        .width('100%')
        .height('60%')
        .border({ width: 1, color: Color.Gray })
        .padding(10)
        .onBlur(() => {
          // 当输入框失去焦点时，自动保存
          this.saveFileContent();
        })
      
      Button('保存')
        .onClick(() => {
          this.saveFileContent();
        })
        .margin({ top: 20 })
      
      Text(`文件路径: ${this.filePath}`)
        .fontSize(12)
        .fontColor(Color.Gray)
        .height('10%')
    }
    .padding(20)
    .width('100%')
    .height('100%')
  }

  aboutToDisappear(): void {
    // 页面销毁时停止监听
    this.watcher.stopWatch();
  }
}

代码说明：

initDistributedFile：在页面创建时初始化文件路径，读取已有内容，并启动监听。
readFileContent：读取文件内容，使用fileIo的标准读写方式。
saveFileContent：写入文件。使用OpenMode.TRUNC先截断文件再写入，保证替换整个文件内容，而不是追加。
watch回调处理：当一个设备保存文件时，另一个设备会收到change事件，然后读取最新内容并更新UI。通过isEditing标记避免了用户正在编辑时被覆盖。
生命周期：aboutToDisappear中停止watcher，防止内存泄漏。

常见问题与避坑指南

这个功能虽然API看起来简单，但实际开发中有几个高频问题。

坑1：监听回调不触发

现象：设备A写入文件后，设备B的watcher.on('change')回调没有执行。
原因：

文件路径不正确。distributedFilesDir在真机上可能返回的路径与模拟器不同，导致两设备实际没有打开同一个文件。
文件写入方式不对。fileIo.write写入内容后，必须调用close才会触发同步操作。
监听器生命周期问题。如果watcher创建后页面被销毁，watcher也会被销毁。
解决：

打印distributedFilesDir实际路径，在两台设备上对比是否指向同一个逻辑文件。
确保在写入后调用fileIo.close。
将watcher实例提升到全局或使用单例管理，避免页面销毁。

坑2：写入乱码问题

现象：读出来的文本有时候出现乱码。
原因：read和write操作处理的是字节数组，没有指定编码。HarmonyOS的分布式文件系统使用UTF-8编码，但我们的write可能没有正确编码。
解决：在写入前，用TextEncoder将字符串转为UTF-8的Uint8Array。

// 正确的编码写入方式
let encoder = new util.TextEncoder();
let uint8Array = encoder.encodeInto(this.textContent);
let buf = uint8Array.buffer as ArrayBuffer;
await fileIo.write(file.fd, buf);

读取时对应使用util.TextDecoder解码。

let decoder = new util.TextDecoder();
let content = decoder.decodeWithStream(new Uint8Array(buf), {stream: false});

坑3：冲突时数据丢失

现象：两台设备同时编辑同一个文件，然后都保存，导致某一台设备的修改被覆盖。
原因：文件以“文件”为粒度同步，没有内置的冲突检测机制。
解决：更健壮的做法是引入乐观锁。在文件头部写入一个递增的版本号，保存时检查版本号是否一致。如果发现冲突，由用户手动选择保留哪个版本。本文的示例只用了简单的isEditing标记防覆盖，更适合单端编辑、多端阅读的场景。

最佳实践

使用UITaskDispatcher更新UI：watcher的回调可能在异步线程执行，不能直接修改@State。通过windowStage.getMainWindow().getUIContext().runOnMainThread或者直接在回调里使用async/await（ArkUI的异步操作会自动在主线程执行）可以避免。
避免高频写入：如果用户输入时每敲一个字符就写入一次，会频繁触发分布式同步，造成性能问题。建议使用防抖（debounce）或像本文一样在输入框失焦时写入。
先判断再写入：在写入前，先读取当前文件内容，对比是否和本地保存的内容一致。如果一致，则无需重复写入，减少不必要的同步。

DEMO入口

完整的项目结构如下：

entry/
├── src/
│   └── main/
│       └── ets/
│           ├── pages/
│           │   └── DistributeEditor.ets
│           └── utils/
│               ├── FileHelper.ets
│               └── FileWatcher.ets
└── entryability/
    └── EntryAbility.ets