博客 / 詳情

返回

HarmonyOS跨設備文件操作實戰：從訪問到拷貝的完整實現方案

在萬物互聯的時代，多設備協同已成為用户核心需求。想象這樣的場景：手機拍攝的工作照片需要在平板上編輯，筆記本上的文檔需同步到車載設備查看，智能手錶的健康數據要備份到電腦——HarmonyOS的分佈式文件系統正是為解決這類跨設備數據流轉問題而生。本文將結合實際開發案例，詳細拆解跨設備文件訪問與拷貝的實現邏輯、開發步驟及注意事項，幫助開發者快速落地多設備協同功能。

一、核心技術原理：分佈式文件系統的"中轉魔法"

HarmonyOS跨設備文件操作的核心是分佈式目錄（/data/storage/el2/distributedfiles/），該目錄作為多設備共享的"數據中轉站"，讓同一應用在不同設備上能通過統一接口訪問共享文件。其底層通過分佈式軟總線實現設備間低延時通信，配合文件系統接口（@kit.CoreFileKit/fileIo）完成數據讀寫與拷貝，無需開發者關注複雜的設備組網與數據傳輸細節。

關鍵特性説明：

  1. 設備兼容性：支持手機、平板、電腦、智能穿戴等HarmonyOS全場景設備，只需登錄同一華為賬號即可組網；
  2. 接口統一性：跨設備文件操作接口與本地文件操作完全一致，降低開發學習成本；
  3. 權限安全性：需動態申請ohos.permission.DISTRIBUTED_DATASYNC權限，保障用户數據安全；
  4. 數據一致性：通過分佈式目錄同步文件元數據，設備離線後自動隱藏對應文件，避免數據錯亂。

二、實戰場景一：跨設備文件訪問（實時讀寫共享文檔）

場景需求

用户在手機（設備A）上創建工作文檔並保存到分佈式目錄，隨後在平板（設備B）上打開該文檔進行編輯，編輯內容實時同步（Close-to-Open一致性）。

開發步驟與核心代碼

1. 前置準備：分佈式組網與權限申請

跨設備操作的前提是完成設備組網和權限授權，這兩步是所有跨設備功能的基礎。

權限申請代碼：

import { common, abilityAccessCtrl } from '@kit.AbilityKit';
import { BusinessError } from '@kit.BasicServicesKit';

// 獲取UIAbility上下文（組件內調用）
const getContext = () => {
  return this.getUIContext().getHostContext() as common.UIAbilityContext;
};

// 申請分佈式數據同步權限
const requestDistributedPermission = async () => {
  const context = getContext();
  const atManager = abilityAccessCtrl.createAtManager();
  try {
    const result = await atManager.requestPermissionsFromUser(
      context,
      ['ohos.permission.DISTRIBUTED_DATASYNC']
    );
    console.info(`權限申請結果：${JSON.stringify(result)}`);
    return result.grantedPermissions.length > 0;
  } catch (err: BusinessError | any) {
    console.error(`權限申請失敗：錯誤碼${err.code}，信息${err.message}`);
    return false;
  }
};

組網要求：

  • 設備A（手機）和設備B（平板）登錄同一華為賬號；
  • 開啓藍牙和Wi-Fi功能（無需藍牙配對，Wi-Fi無需同一局域網）；
  • 確保應用已在兩台設備上安裝並完成權限授權。

2. 設備A：創建並寫入共享文件

在手機上創建文檔並保存到分佈式目錄，供平板訪問。

import { fileIo as fs } from '@kit.CoreFileKit';
import { common } from '@kit.AbilityKit';
import { BusinessError } from '@kit.BasicServicesKit';

// 設備A：創建共享文件並寫入內容
const createSharedFile = async () => {
  // 權限校驗
  const hasPermission = await requestDistributedPermission();
  if (!hasPermission) return;

  const context = getContext();
  // 獲取分佈式目錄路徑
  const distributedDir = context.distributedFilesDir;
  const filePath = `${distributedDir}/work_doc.txt`;

  try {
    // 打開文件（不存在則創建）
    const file = fs.openSync(
      filePath,
      fs.OpenMode.READ_WRITE | fs.OpenMode.CREATE
    );
    // 寫入內容（例如工作文檔初稿）
    const content = 'HarmonyOS跨設備協同實戰：文檔編輯示例';
    fs.writeSync(file.fd, content);
    fs.closeSync(file.fd);
    console.info(`文件創建成功：${filePath}`);
  } catch (err: BusinessError | any) {
    console.error(`文件操作失敗：錯誤碼${err.code}，信息${err.message}`);
  }
};

3. 設備B：訪問並編輯共享文件

平板通過分佈式設備管理接口獲取手機的networkId，建立鏈路後讀取並修改文件內容。

import { fileIo as fs } from '@kit.CoreFileKit';
import { common } from '@kit.AbilityKit';
import { BusinessError } from '@kit.BasicServicesKit';
import { buffer } from '@kit.ArkTS';
import { distributedDeviceManager } from '@kit.DistributedServiceKit';

// 設備B：訪問並編輯設備A的共享文件
const accessRemoteFile = async () => {
  // 權限校驗
  const hasPermission = await requestDistributedPermission();
  if (!hasPermission) return;

  const context = getContext();
  const distributedDir = context.distributedFilesDir;
  const filePath = `${distributedDir}/work_doc.txt`;

  try {
    // 1. 獲取設備A的networkId
    const dmInstance = distributedDeviceManager.createDeviceManager('com.example.distributedfile');
    const deviceList = dmInstance.getAvailableDeviceListSync();
    if (!deviceList || deviceList.length === 0) {
      console.error('未發現可用設備');
      return;
    }
    const networkId = deviceList[0].networkId; // 首個可用設備即為設備A

    // 2. 建立跨設備文件訪問鏈路
    const dfsListeners: fs.DfsListeners = {
      onStatus: (netId, status) => {
        console.info(`鏈路狀態：${netId} - ${status}`);
      }
    };
    await fs.connectDfs(networkId, dfsListeners);
    console.info('跨設備鏈路建立成功');

    // 3. 讀取文件內容
    const file = fs.openSync(filePath, fs.OpenMode.READ_WRITE);
    const buffer = new ArrayBuffer(4096);
    const readSize = fs.readSync(file.fd, buffer, { offset: 0, length: buffer.byteLength });
    const content = buffer.from(buffer, 0, readSize).toString();
    console.info(`讀取到的內容：${content}`);

    // 4. 編輯文件（追加內容）
    const newContent = `${content}\n平板端編輯時間：${new Date().toLocaleString()}`;
    fs.writeSync(file.fd, newContent, { offset: content.length });
    fs.closeSync(file.fd);
    console.info('文件編輯並保存成功');

    // 5. 斷開鏈路
    await fs.disconnectDfs(networkId);
  } catch (err: BusinessError | any) {
    console.error(`跨設備訪問失敗：錯誤碼${err.code}，信息${err.message}`);
  }
};

關鍵注意事項

  1. 鏈路管理：訪問完成後必須調用disconnectDfs斷開鏈路，避免資源泄露；
  2. 超時處理：設備離線感知存在4秒延遲，需處理"文件可見但設備已離線"的異常場景；
  3. 一致性保障：僅保證Close-to-Open一致性，若兩端同時編輯同一文件，需自行實現衝突解決邏輯。

三、實戰場景二：跨設備文件拷貝（批量同步照片/視頻）

場景需求

用户在户外用手機（設備A）拍攝了大量照片，回家後需要將照片批量拷貝到電腦（設備B）進行備份，要求支持拷貝進度監聽和臨時文件清理。

開發步驟與核心代碼

1. 設備A：將本地照片拷貝至分佈式目錄

手機端需先將相冊中的照片（沙箱目錄文件）拷貝到分佈式目錄，作為跨設備拷貝的數據源。

import { fileIo as fs } from '@kit.CoreFileKit';
import { common } from '@kit.AbilityKit';
import { BusinessError } from '@kit.BasicServicesKit';
import { fileUri } from '@kit.CoreFileKit';

// 設備A：將沙箱文件拷貝到分佈式目錄
const copyToDistributedDir = async (localFilePath: string) => {
  const hasPermission = await requestDistributedPermission();
  if (!hasPermission) return;

  const context = getContext();
  const sandBoxDir = context.filesDir; // 沙箱目錄（存儲本地照片）
  const distributedDir = context.distributedFilesDir; // 分佈式目錄

  try {
    // 源文件路徑（沙箱目錄）
    const srcPath = `${sandBoxDir}/${localFilePath}`;
    // 目標文件路徑（分佈式目錄）
    const destPath = `${distributedDir}/${localFilePath}`;

    // 轉換路徑為URI（文件拷貝需基於URI操作）
    const srcUri = fileUri.getUriFromPath(srcPath);
    const destUri = fileUri.getUriFromPath(destPath);

    // 執行拷貝
    await fs.copy(srcUri, destUri);
    console.info(`文件拷貝成功：${srcPath} -> ${destPath}`);
    return true;
  } catch (err: BusinessError | any) {
    console.error(`拷貝到分佈式目錄失敗：錯誤碼${err.code}，信息${err.message}`);
    return false;
  }
};

// 批量拷貝照片示例
const batchCopyPhotos = async () => {
  const photos = ['photo_1.jpg', 'photo_2.jpg', 'photo_3.jpg']; // 本地沙箱中的照片文件名
  for (const photo of photos) {
    const success = await copyToDistributedDir(photo);
    if (!success) {
      console.error(`照片${photo}拷貝失敗`);
    }
  }
};

2. 設備B：從分佈式目錄拷貝文件到本地

電腦端通過分佈式鏈路連接手機，將分佈式目錄中的照片拷貝到本地沙箱，並監聽拷貝進度，拷貝完成後清理分佈式目錄的臨時文件。

import { fileIo as fs } from '@kit.CoreFileKit';
import { common } from '@kit.AbilityKit';
import { BusinessError } from '@kit.BasicServicesKit';
import { fileUri } from '@kit.CoreFileKit';
import { distributedDeviceManager } from '@kit.DistributedServiceKit';

// 設備B：從分佈式目錄拷貝文件到本地
const copyFromDistributedDir = async (fileName: string) => {
  const hasPermission = await requestDistributedPermission();
  if (!hasPermission) return;

  const context = getContext();
  const localDir = context.filesDir; // 電腦本地沙箱目錄（存儲備份照片）
  const distributedDir = context.distributedFilesDir; // 分佈式目錄

  try {
    // 1. 獲取設備A的networkId
    const dmInstance = distributedDeviceManager.createDeviceManager('com.example.distributedfile');
    const deviceList = dmInstance.getAvailableDeviceListSync();
    if (!deviceList || deviceList.length === 0) {
      console.error('未發現手機設備');
      return;
    }
    const networkId = deviceList[0].networkId;

    // 2. 建立跨設備鏈路
    const dfsListeners: fs.DfsListeners = {
      onStatus: (netId, status) => {
        if (status !== 0) {
          console.error(`分佈式目錄訪問失敗：${status}`);
        }
      }
    };
    await fs.connectDfs(networkId, dfsListeners);

    // 3. 定義拷貝進度監聽
    const progressListener: fs.ProgressListener = (progress) => {
      const progressRate = Math.round((progress.processedSize / progress.totalSize) * 100);
      console.info(`拷貝進度：${fileName} - ${progressRate}%`);
    };
    const copyOptions: fs.CopyOptions = { progressListener };

    // 4. 執行拷貝
    const srcPath = `${distributedDir}/${fileName}`;
    const destPath = `${localDir}/backup_${fileName}`;
    const srcUri = fileUri.getUriFromPath(srcPath);
    const destUri = fileUri.getUriFromPath(destPath);

    await fs.copy(srcUri, destUri, copyOptions);
    console.info(`照片備份成功：${destPath}`);

    // 5. 清理分佈式目錄臨時文件
    fs.unlinkSync(srcPath);
    console.info(`臨時文件清理成功：${srcPath}`);

    // 6. 斷開鏈路
    await fs.disconnectDfs(networkId);
  } catch (err: BusinessError | any) {
    console.error(`照片備份失敗：錯誤碼${err.code}，信息${err.message}`);
  }
};

// 批量備份照片示例
const batchBackupPhotos = async () => {
  const photos = ['photo_1.jpg', 'photo_2.jpg', 'photo_3.jpg'];
  for (const photo of photos) {
    await copyFromDistributedDir(photo);
  }
};

關鍵優化點

  1. 進度監聽：通過ProgressListener實時反饋拷貝進度，提升用户體驗；
  2. 臨時文件清理：拷貝完成後調用unlinkSync刪除分佈式目錄文件，節省設備存儲空間；
  3. 批量處理：通過循環實現多文件批量拷貝，適配照片、視頻等批量同步場景；
  4. 錯誤重試：可添加失敗重試邏輯（如網絡波動導致的拷貝失敗），增強穩定性。

四、常見問題與解決方案

1. 權限申請失敗

  • 原因：用户拒絕授權或應用未在config.json中聲明權限；
  • 解決方案：在config.json中添加權限聲明，同時在申請權限前向用户説明授權用途，提升授權通過率。
{
  "module": {
    "reqPermissions": [
      {
        "name": "ohos.permission.DISTRIBUTED_DATASYNC",
        "reason": "需要跨設備同步文件數據",
        "usedScene": {
          "ability": ["com.example.distributedfile.MainAbility"],
          "when": "always"
        }
      }
    ]
  }
}

2. 無法發現目標設備

  • 原因：設備未登錄同一賬號、藍牙/Wi-Fi未開啓，或設備處於離線狀態；
  • 解決方案：在應用中添加設備狀態檢測邏輯，提示用户完成賬號登錄和網絡設置。

3. 文件拷貝/訪問超時

  • 原因：網絡波動、文件過大或設備性能不足；
  • 解決方案：設置超時處理機制，對大文件採用分片傳輸（需自行實現），避免長時間阻塞主線程。

4. 文件衝突

  • 原因：多設備同時創建同名文件；
  • 解決方案：遵循HarmonyOS衝突處理規則，或自定義文件命名規則（如添加時間戳），避免文件名重複。

五、總結

HarmonyOS的分佈式文件系統通過"分佈式目錄+統一接口"的設計，極大簡化了跨設備文件操作的開發難度。開發者只需關注"文件放入分佈式目錄"和"從分佈式目錄讀取文件"兩個核心步驟，即可實現多設備間的數據流轉。無論是實時文檔編輯、照片批量備份，還是跨設備多媒體共享，都能通過本文介紹的方案快速落地。

在實際開發中，建議結合具體場景優化用户體驗：如添加設備連接狀態提示、文件操作進度條、錯誤重試機制等。同時，需嚴格遵循權限申請規範和數據安全要求，確保用户數據在跨設備傳輸過程中的安全性與私密性。隨着HarmonyOS生態的不斷完善，跨設備協同將迎來更多創新場景，開發者可基於本文技術方案探索更多可能性。

harmonyos-next
user avatar
0 位用戶收藏了這個故事！

發佈 評論

Some HTML is okay.