一、功能简介

本篇讲解如何基于 HarmonyOS 的分布式能力，实现不同设备间（如手机、平板、智慧屏）数据同步，适用于跨屏协作、数据迁移、多端共享等场景。

二、应用场景示例

• 在手机编辑文档，自动同步到平板；
• 一端登录，所有设备同步登录状态；
• 多设备实时共享购物车、播放进度等。

三、核心技术模块

分布式能力依赖 HarmonyOS 的多设备协同特性（仅支持 DevEco Studio Stage 模型 + API 10+ 真机部署）

所需模块

import distributedKVStore from '@ohos.data.distributedKVStore'

四、页面结构

entry/src/main/ets/pages/DistributedSyncDemo.ets

五、代码演示（跨设备数据写入 + 自动同步）

@Entry
@Component
struct DistributedSyncDemo {
  @State text: string = ''
  @State message: string = ''
  private kvManager: distributedKVStore.KVManager
  private kvStore: distributedKVStore.SingleKVStore

  async aboutToAppear() {
    const config = {
      bundleName: 'com.example.harmonyapp',
      userInfo: {
        userId: '0',
        userType: distributedKVStore.UserType.SAME_USER_ID
      }
    }
    this.kvManager = distributedKVStore.createKVManager(config)
    const options = {
      storeId: 'globalStore',
      kvStoreType: distributedKVStore.KVStoreType.SINGLE_VERSION,
      autoSync: true,
      encrypt: false,
      backup: false,
      securityLevel: distributedKVStore.SecurityLevel.S0
    }
    this.kvStore = await this.kvManager.getKVStore(options)

    // 监听数据变更（跨设备触发）
    this.kvStore.on('dataChange', (changes) => {
      for (const entry of changes.insertEntries ?? []) {
        if (entry.key === 'sharedText') {
          this.text = entry.value.value
          this.message = '[远端] 同步成功'
        }
      }
    })

    // 初始读取
    const result = await this.kvStore.get('sharedText')
    if (result) {
      this.text = result
    }
  }

  async updateText() {
    await this.kvStore.put('sharedText', this.text)
    this.message = '[本地] 写入并同步成功'
  }

  build() {
    Column() {
      Text('分布式数据同步演示')
        .fontSize(20)
        .margin({ bottom: 12 })

      TextArea({ text: this.text, onChange: val => this.text = val })
        .placeholder('输入内容，自动同步到其他设备')
        .height(120)
        .padding(10)
        .borderRadius(8)
        .backgroundColor('#f5f5f5')
        .fontSize(16)
        .margin({ bottom: 12 })

      Button('写入并同步')
        .onClick(() => this.updateText())
        .margin({ bottom: 12 })

      Text(this.message)
        .fontSize(14)
        .fontColor(Color.Blue)
    }
    .width('100%')
    .padding(20)
  }
}

六、运行效果

1. 在设备 A 输入文本 → 点击同步；
2. 设备 B 同一应用中收到变更 → 自动展示新值；
3. 可反向同步，实现全端实时数据更新。

七、常见易错点与解决方案

八、拓展建议

• 实现跨设备通知、聊天、协同文档等；
• 结合 DeviceManager 实现设备发现与主动连接；
• 使用 FA模型 + Continuation 进一步支持跨屏迁移。