如何通过OpenHarmony通讯实现数据共享

OpenHarmony 数据共享实现路径总览

• 跨应用同设备：优先使用 UDMF 统一数据通道（@ohos.data.unifiedDataChannel），通过标准数据通路（如 DATA_HUB）在多应用间以统一类型（文本、图片等）进行“插入/查询/订阅”，适合账号、标识、内容等共享。
• 跨设备同应用：使用 分布式数据对象（DistributedDataObject），在同一应用的不同设备间以相同 sessionId 自动同步对象属性变更，适合播放状态、进度、表单等实时协同。
• 系统级代理刷新卡片：系统应用作为数据提供方开启数据共享，卡片提供方在 form_config.json 中启用 dataProxyEnabled，通过 key + subscriberId 订阅并由系统服务代理刷新卡片。
• 跨应用跨设备（传统）：使用 DataAbility + URI 的标准化访问接口，基于 URI 进行增删改查与权限控制，适合系统设置、内容提供等场景。

方式一 跨应用同设备 UDMF 统一数据通道

• 典型场景：多个 App 共享同一用户的 账号/标识/轻量内容。
• 关键步骤：
  1. 选择数据通路（如 DATA_HUB），构造标准化数据（如 PlainText），封装为 UnifiedData；
  2. 调用 insertData 写入；其他应用用 queryData 读取；
  3. 支持异常捕获与结果回调，便于定位问题。
• 示例（ArkTS，应用 A 写入，应用 B 读取）：

  // 应用A：写入
  import { unifiedDataChannel, uniformTypeDescriptor } from '@kit.ArkData';
  import { BusinessError } from '@kit.BasicServicesKit';
  
  let plainText = new unifiedDataChannel.PlainText();
  plainText.textContent = 'user_12345';
  
  let unifiedData = new unifiedDataChannel.UnifiedData(plainText);
  let options: unifiedDataChannel.Options = {
    intention: unifiedDataChannel.Intention.DATA_HUB
  };
  
  unifiedDataChannel.insertData(options, unifiedData, (err, data) => {
    if (err === undefined) {
      console.info(`Succeeded in inserting data. key = ${plainText.textContent}`);
    } else {
      console.error(`Failed to insert data. code=${err.code}, message=${err.message}`);
    }
  });
  

  // 应用B：读取
  import { unifiedDataChannel, uniformTypeDescriptor } from '@kit.ArkData';
  import { BusinessError } from '@kit.BasicServicesKit';
  
  let options: unifiedDataChannel.Options = {
    intention: unifiedDataChannel.Intention.DATA_HUB
  };
  
  unifiedDataChannel.queryData(options, (err, result) => {
    if (err === undefined && result) {
      // 解析 result 中的 UnifiedData，按类型读取内容
      console.info(`Query result: ${JSON.stringify(result)}`);
    } else {
      console.error(`Query failed. code=${err?.code}, message=${err?.message}`);
    }
  });
  

• 说明：UDMF 对文本、图片等提供标准化类型，减少适配成本，适合“多对多”跨应用数据共享。

方式二 跨设备同应用 分布式数据对象

• 典型场景：同一 App 在手机/平板/电视间共享 播放进度、音量、表单状态 等。
• 关键要点：
  • 通过 sessionId 将不同设备上的对象纳入同一同步会话；
  • 同步最小单位为“属性”，对象属性变更自动同步；
  • 同一 session 每台设备最多 1 个对象；建议不超过 3 台设备 协同；单对象大小不超过 500KB；单个应用最多 16 个 分布式数据对象实例。
• 示例（ArkTS）：

  import distributedObject from '@ohos.data.distributedDataObject';
  
  // 设备A：创建并加入会话
  let objA = distributedObject.createDistributedObject({ name: 'Amy', age: 18, isVis: false });
  objA.setSessionId('session-001');
  objA.on('change', (sessionId, changeData) => {
    changeData.forEach((k) => console.info(`changed: ${k} = ${objA[k]}`));
  });
  
  // 设备B：加入同一会话
  let objB = distributedObject.createDistributedObject({ name: '', age: 0, isVis: false });
  objB.setSessionId('session-001');
  objB.on('change', (sessionId, changeData) => {
    changeData.forEach((k) => console.info(`changed: ${k} = ${objB[k]}`));
  });
  

• 说明：像“全局变量”一样使用分布式对象，显著减少消息收发、冲突解决等样板代码。

方式三 系统级代理刷新卡片的数据共享

• 典型场景：卡片提供方不在运行时，仍可由系统应用代理刷新卡片数据。
• 关键要点：
  • 仅 系统应用 可作为“数据提供方”，并需定义共享标识 key + subscriberId；
  • 卡片提供方在 form_config.json 中开启 dataProxyEnabled，并在 onAddForm 回调中返回订阅信息；
  • 数据提供方将数据写入数据库，数据管理服务感知变更并推送给订阅实例，卡片管理服务再驱动渲染。
• 配置与示例（卡片提供方）：

  {
    "forms": [
      {
        "name": "WidgetProcessData",
        "src": "./ets/widgetprocessdata/pages/WidgetProcessDataCard.ets",
        "uiSyntax": "arkts",
        "updateEnabled": true,
        "dataProxyEnabled": true,
        "defaultDimension": "2*2"
      }
    ]
  }
  

  // onAddForm 返回订阅信息
  import formBindingData from '@ohos.app.form.formBindingData';
  import FormExtensionAbility from '@ohos.app.form.FormExtensionAbility';
  import type Want from '@ohos.app.form.Want';
  
  export default class ProcessDataFormAbility extends FormExtensionAbility {
    onAddForm(want: Want): formBindingData.FormBindingData {
      const key = 'datashareproxy://com.samples.widgetupdatebyproxy/weather';
      const subscriberId = '11'; // 也可使用 formId
      const proxyData = { key, subscriberId };
      return formBindingData.createFormBindingData(proxyData);
    }
  }
  

• 说明：共享数据分为 过程数据（可订阅、有老化期）与 持久化数据（仅系统应用可订阅）。

方式四 跨应用跨设备 DataAbility + URI

• 典型场景：系统设置、内容提供等需要 标准化跨应用/跨设备访问 的数据。
• 关键要点：
  • DataAbility 提供统一的数据访问接口，基于 URI 进行 增删改查；
  • 通过 权限控制 保障数据安全；
  • URI 结构：dataability:///{device_id}/{bundle_name}/{ability_name}/{path}。
• 说明：适合系统级数据一致性与内容共享，是应用模型演进中（FA→Stage）的重要数据共享组件。

选型与落地建议

• 明确维度：先区分 同设备/跨设备、同应用/跨应用，再选择对应方案；
• 数据规模与实时性：小体量、强实时（如状态协同）优先 分布式数据对象；多应用共享标识/账号优先 UDMF；
• 系统能力依赖：需要系统级代理刷新卡片时，采用 卡片代理刷新 机制；
• 兼容与演进：传统内容提供/系统设置可继续使用 DataAbility + URI；
• 约束遵循：注意 对象数量（≤16）、设备数（≤3）、对象大小（≤500KB） 等限制，避免运行时异常。