鸿蒙分布式开发实战：从零构建你的首个跨设备应用

最近和几个独立开发者朋友聊天，大家不约而同地提到了一个痛点：现在的应用生态越来越碎片化。用户可能早上用手机查看日程，下午在平板上处理文档，晚上又在智慧屏上追剧。如果我们为每个设备都单独开发一套应用，不仅开发成本高，维护起来更是噩梦。有没有一种技术，能让我们写一次代码，就能让应用在不同设备上智能运行，甚至让设备之间“对话”协作？

这正是鸿蒙系统分布式能力要解决的核心问题。它不像传统操作系统那样把每台设备看作孤岛，而是构建了一个“超级终端”的愿景——你的手机、平板、手表、智慧屏，甚至未来的车载设备，都能像一台设备那样协同工作。对于开发者而言，这意味着我们可以用一种全新的思维方式来构建应用：应用不再属于单一设备，而是属于用户，可以在用户拥有的设备群中自由流转、无缝衔接。

这篇文章，我将从一个实践者的角度，带你深入鸿蒙分布式开发的世界。我们不谈空泛的概念，而是聚焦于如何动手，利用鸿蒙的分布式软总线、分布式数据管理和分布式任务调度等核心能力，快速构建一个真正能跑起来的跨设备应用。无论你是移动开发的老手，还是对跨端开发充满好奇的新人，都能从这里找到可落地的路径。

1. 环境搭建与项目初始化：迈出第一步

在开始编写任何分布式代码之前，一个稳定、高效的开发环境是基石。鸿蒙的开发工具链经过几年的迭代，已经相当成熟和友好。

1.1 开发工具准备：DevEco Studio

鸿蒙的官方IDE是DevEco Studio，它基于IntelliJ IDEA构建，对于熟悉Android Studio或JetBrains系列工具的开发者来说，上手几乎零成本。

安装与核心配置要点：

1. 获取与安装：从华为开发者联盟官网下载最新版本的DevEco Studio。安装过程与常规软件无异，注意安装路径不要包含中文和空格。
2. SDK管理：首次启动时，IDE会引导你下载HarmonyOS SDK。这里有个关键选择：SDK版本。对于新项目，我强烈建议选择最新的API版本，以确保能使用最新的分布式特性。同时，你需要根据目标设备类型，勾选对应的SDK，例如手机、平板、穿戴设备等。
3. 模拟器与真机：DevEco Studio内置了设备管理器，可以创建手机、平板等多种设备的本地模拟器。模拟器对于初步调试非常方便。但分布式能力的深度测试，尤其是设备发现和连接，强烈建议使用真机。你需要准备至少两台搭载HarmonyOS的设备（如手机和平板），并在开发者选项中开启“调试模式”。

提示：在真机调试前，确保所有测试设备登录了同一个华为帐号，并处于同一局域网下。这是分布式能力生效的基础前提。

1.2 创建你的第一个分布式工程

打开DevEco Studio，选择“Create Project”。这里你会看到丰富的项目模板。

• Empty Ability：最纯净的模板，适合从零开始学习。
• Atomic Service：原子化服务模板，用于开发无需安装、即点即用的服务卡片。
• 对于分布式入门，我推荐使用 “Empty Ability” 模板，因为它结构最清晰，干扰最少。

在项目配置页面，重点关注以下选项：

配置项	推荐值/说明	对分布式开发的影响
Project Type	Application	标准应用类型。
Compile SDK	选择最新的API版本	高版本API通常包含更完善、更稳定的分布式API。
Model	Stage（推荐）	Stage模型是鸿蒙主推的应用模型，在生命周期管理、组件通信等方面更强大，是未来趋势。
Enable Super Visual	根据喜好	低代码可视化布局工具，初学者可开启以快速构建UI。

点击“Finish”，IDE会自动生成项目结构。花几分钟时间熟悉一下核心目录：

MyFirstDistributedApp/
├── entry/          # 主模块
│   ├── src/
│   │   ├── main/
│   │   │   ├── ets/        # ArkTS代码目录
│   │   │   │   ├── entryability/
│   │   │   │   └── pages/  # 页面UI组件
│   │   │   └── resources/  # 资源文件（图片、字符串等）
│   │   └── module.json5    # 模块配置文件，声明能力、权限等
└── oh-package.json5        # 项目依赖配置文件

其中，module.json5 文件是分布式能力的“声明书”，我们后续会频繁修改它。

2. 理解分布式核心：软总线、数据与任务

在写代码前，我们需要在脑子里建立起鸿蒙分布式能力的三个支柱模型。这能帮你理解后续的API调用究竟在背后做了什么。

2.1 分布式软总线：设备的“隐形神经网络”

你可以把分布式软总线想象成一个智能的、自动组网的内部通信系统。当你的手机、平板、智慧屏登录同一账号并处于可发现范围时，软总线就在它们之间建立了一条安全、高效的虚拟通道。

• 自动发现：设备无需用户手动配对（如蓝牙），软总线基于网络（Wi-Fi、蓝牙等）自动发现并认证可信设备。
• 统一通信：为上层应用提供统一的通信接口，开发者无需关心底层是Wi-Fi P2P、蓝牙还是其他协议。
• 安全通道：所有通信经过加密，确保数据只能在可信设备间传输。

对于开发者，软总线是透明的。我们通过更高层的分布式数据管理和分布式任务调度API来间接使用它，这极大地简化了开发复杂度。

2.2 分布式数据管理：让数据“活”起来

在传统开发中，数据通常被“锁”在单个设备的本地数据库或文件中。跨设备同步需要自己实现复杂的网络传输和冲突解决。鸿蒙的分布式数据管理（Distributed Data Object, KVStore）提供了开箱即用的解决方案。

它的核心思想是基于KV（键值）模型的跨设备数据同步。当你在一个设备上修改了某个键对应的值，这个变化会自动、实时地同步到所有订阅了该数据对象的其他可信设备上。

一个简单的场景：你在手机上的购物应用中添加了一件商品到“收藏夹”，当你打开平板上的同一应用时，这件商品已经出现在平板的收藏夹里了。这就是分布式KVStore在背后工作。

2.3 分布式任务调度：让应用“流动”起来

这是分布式体验中最具魔力的一环。分布式任务调度允许一个设备上的应用组件（如一个播放音乐的页面）被迁移到另一个设备上继续运行。

典型流程：

1. 用户在手机上看视频。
2. 手机靠近智慧屏，手机界面出现“流转”图标。
3. 用户点击流转，视频播放任务（包括当前的播放进度、音效设置等状态）瞬间从手机迁移到智慧屏上继续播放。
4. 手机可以释放出来做其他事情。

实现这一功能的关键是Ability的跨设备启动和迁移。鸿蒙的UIAbility组件不仅可以在本设备启动，还可以指定在另一台设备上远程启动。

3. 实战：构建一个跨设备协同待办清单

理论说得再多，不如动手写代码。我们来构建一个简单的“分布式待办清单”应用。它将在两台设备上运行，在一台设备上新增或勾选完成一个待办项，另一台设备上的列表会实时同步更新。

3.1 项目基础与UI搭建

首先，我们在 entry/src/main/pages/Index.ets 中构建一个简单的UI界面。

// Index.ets
import { distributedTodoManager } from '../model/DistributedTodoModel';
import { TodoItem } from '../model/TodoItem';

@Entry
@Component
struct Index {
  @State todoList: Array<TodoItem> = [];
  @State newTodoTitle: string = '';

  // 生命周期函数：页面显示时加载数据
  aboutToAppear() {
    this.loadTodos();
  }

  loadTodos() {
    // 从分布式数据管理器中获取列表
    distributedTodoManager.getTodoList().then((list) => {
      this.todoList = list;
    });
  }

  build() {
    Column({ space: 20 }) {
      // 标题
      Text('分布式待办清单')
        .fontSize(30)
        .fontWeight(FontWeight.Bold)

      // 新增待办输入框
      TextInput({ placeholder: '输入新待办事项...', text: this.newTodoTitle })
        .onChange((value: string) => {
          this.newTodoTitle = value;
        })
        .width('90%')
        .padding(10)
        .backgroundColor(Color.White)
        .borderRadius(10)

      Button('添加')
        .onClick(() => {
          if (this.newTodoTitle.trim()) {
            distributedTodoManager.addTodo(this.newTodoTitle.trim()).then(() => {
              this.newTodoTitle = '';
              this.loadTodos(); // 刷新列表
            });
          }
        })
        .width('50%')

      // 待办列表
      List({ space: 10 }) {
        ForEach(this.todoList, (item: TodoItem) => {
          ListItem() {
            Row({ space: 10 }) {
              // 完成状态复选框
              Checkbox()
                .select(item.completed)
                .onChange((checked: boolean) => {
                  distributedTodoManager.toggleTodo(item.id, checked).then(() => {
                    this.loadTodos();
                  });
                })
              // 待办文本
              Text(item.title)
                .fontSize(18)
                .decoration({ type: item.completed ? TextDecorationType.LineThrough : TextDecorationType.None })
                .fontColor(item.completed ? Color.Gray : Color.Black)
                .layoutWeight(1) // 占据剩余空间
              // 删除按钮
              Button('删除')
                .onClick(() => {
                  distributedTodoManager.deleteTodo(item.id).then(() => {
                    this.loadTodos();
                  });
                })
            }
            .padding(10)
            .backgroundColor(Color.White)
            .borderRadius(8)
            .width('100%')
          }
        }, (item: TodoItem) => item.id.toString())
      }
      .width('100%')
      .layoutWeight(1) // 列表占据主要空间
      .alignListItem(ListItemAlign.Center)
    }
    .padding(20)
    .width('100%')
    .height('100%')
    .backgroundColor('#F5F5F5')
  }
}

这个界面包含了输入框、添加按钮和一个待办列表，每个列表项有复选框、文本和删除按钮。但数据操作都委托给了一个叫 distributedTodoManager 的模块，这正是我们实现分布式的关键。

3.2 实现分布式数据管理

现在，我们来创建数据模型和管理器。首先定义待办项的数据结构。

// entry/src/main/model/TodoItem.ts
export class TodoItem {
  id: number;
  title: string;
  completed: boolean;
  createTime: number;

  constructor(title: string) {
    this.id = Date.now(); // 简单用时间戳作ID
    this.title = title;
    this.completed = false;
    this.createTime = Date.now();
  }
}

接下来是重头戏：实现基于分布式KVStore的数据管理器。

// entry/src/main/model/DistributedTodoModel.ts
import { distributedKVStore, KVManager } from '@kit.DistributedDataKit';
import { BusinessError } from '@kit.BasicServicesKit';
import { TodoItem } from './TodoItem';

const STORE_ID = 'distributed_todo_store';
const KEY_TODO_LIST = 'todo_list';

class DistributedTodoManager {
  private kvManager: KVManager | null = null;
  private kvStore: distributedKVStore.SingleKVStore | null = null;

  // 初始化KVStore
  async initKVStore(): Promise<void> {
    try {
      const context = getContext(this) as common.UIAbilityContext;
      this.kvManager = new KVManager(context);

      const options: KVManager.KVStoreOptions = {
        bundleName: context.abilityInfo.bundleName,
        userType: KVManager.UserType.SAME_USER_ID, // 同账号用户
        context: context
      };

      // 获取KVStore实例
      this.kvStore = await this.kvManager.getKVStore<distributedKVStore.SingleKVStore>(STORE_ID, options);

      // 订阅数据变化
      await this.subscribeDataChange();
      console.info('DistributedTodoManager: KVStore initialized and subscribed.');
    } catch (err) {
      const error = err as BusinessError;
      console.error(`DistributedTodoManager: Failed to init KVStore. Code: ${error.code}, message: ${error.message}`);
    }
  }

  // 订阅数据变更，实现实时同步
  private async subscribeDataChange(): Promise<void> {
    if (!this.kvStore) {
      return;
    }
    try {
      await this.kvStore.on('dataChange', distributedKVStore.SubscribeType.SUBSCRIBE_TYPE_ALL, (data) => {
        console.info(`DistributedTodoManager: Data changed.`);
        // 在实际应用中，这里可以触发一个全局事件，通知UI更新
        // 例如：AppStorage.setOrCreate('todoListUpdateTrigger', Date.now());
      });
    } catch (err) {
      const error = err as BusinessError;
      console.error(`Failed to subscribe data change. Code: ${error.code}, message: ${error.message}`);
    }
  }

  // 添加待办
  async addTodo(title: string): Promise<void> {
    const todo = new TodoItem(title);
    const currentList = await this.getTodoList();
    currentList.push(todo);
    await this.saveTodoList(currentList);
  }

  // 获取待办列表
  async getTodoList(): Promise<Array<TodoItem>> {
    if (!this.kvStore) {
      await this.initKVStore();
    }
    try {
      const value = await this.kvStore?.get(KEY_TODO_LIST);
      return value ? JSON.parse(value as string) : [];
    } catch (err) {
      console.error('Failed to get todo list from KVStore.');
      return [];
    }
  }

  // 保存待办列表（内部方法）
  private async saveTodoList(list: Array<TodoItem>): Promise<void> {
    if (!this.kvStore) {
      return;
    }
    try {
      await this.kvStore.put(KEY_TODO_LIST, JSON.stringify(list));
      console.info('DistributedTodoManager: Todo list saved.');
    } catch (err) {
      const error = err as BusinessError;
      console.error(`Failed to save todo list. Code: ${error.code}, message: ${error.message}`);
    }
  }

  // 切换待办状态
  async toggleTodo(id: number, completed: boolean): Promise<void> {
    const list = await this.getTodoList();
    const index = list.findIndex(item => item.id === id);
    if (index !== -1) {
      list[index].completed = completed;
      await this.saveTodoList(list);
    }
  }

  // 删除待办
  async deleteTodo(id: number): Promise<void> {
    const list = await this.getTodoList();
    const newList = list.filter(item => item.id !== id);
    await this.saveTodoList(newList);
  }
}

export const distributedTodoManager = new DistributedTodoManager();

代码解析与关键点：

1. KVManager 与 SingleKVStore：这是操作分布式数据库的核心类。SingleKVStore 提供针对单个键值对的增删改查操作。
2. UserType.SAME_USER_ID：这是实现跨设备同步的关键配置。它指定了数据只在同一华为帐号下的不同设备之间同步。
3. 数据序列化：分布式KVStore存储的是字符串。我们需要将 TodoItem 对象数组通过 JSON.stringify() 序列化成字符串进行存储，读取时再通过 JSON.parse() 反序列化。
4. 订阅变更 (on(‘dataChange’))：我们订阅了全局的数据变更通知。当任何设备（包括本设备）修改了 todo_list 这个键对应的数据时，所有设备的回调函数都会被触发。在实际完整应用中，这里应该抛出一个事件，驱动UI自动刷新，而不是像我们示例中那样需要手动调用 loadTodos()。

3.3 配置权限与声明能力

分布式功能需要相应的权限。我们需要在 module.json5 文件中进行声明。

// entry/src/main/module.json5 (部分)
{
  "module": {
    "requestPermissions": [
      {
        "name": "ohos.permission.DISTRIBUTED_DATASYNC" // 分布式数据同步权限
      }
    ],
    "abilities": [
      {
        "name": "EntryAbility",
        "srcEntry": "./ets/entryability/EntryAbility.ets",
        "description": "$string:EntryAbility_desc",
        "icon": "$media:icon",
        "label": "$string:EntryAbility_label",
        "startWindowIcon": "$media:icon",
        "startWindowBackground": "$color:start_window_background",
        "exported": true, // 允许被其他应用或设备调用
        "skills": [
          {
            "actions": [
              "action.system.home"
            ],
            "entities": [
              "entity.system.home"
            ]
          }
        ]
      }
    ]
  }
}

此外，还需要在 AppScope/app.json5 中声明应用级别的分布式特性。

// AppScope/app.json5
{
  "app": {
    "bundleName": "com.example.myfirstdistributedapp",
    "vendor": "example",
    "versionCode": 1000000,
    "versionName": "1.0.0",
    "icon": "$media:app_icon",
    "label": "$string:app_name",
    "distributedNotificationEnabled": true, // 启用分布式通知
    "supportBackup": false,
    "network": {
      "cleartextTraffic": true // 允许HTTP明文流量（仅调试用，上架应关闭）
    }
  }
}

4. 进阶：实现分布式UI迁移与任务流转

数据同步已经让我们的应用“智能”了起来。接下来，我们尝试更酷的功能：将正在编辑某个待办项的界面，从手机迁移到平板上继续操作。

4.1 理解UIAbility迁移

在鸿蒙中，UIAbility是应用组件，它包含UI界面和应用逻辑。分布式UI迁移的本质是将一个UIAbility实例从一个设备迁移到另一个设备上继续运行。迁移过程中，系统会保存原设备上Ability的状态（通过 onSaveState），然后在目标设备上恢复（通过 onRestoreState），并重新构建UI。

4.2 改造应用以支持迁移

首先，我们需要修改待办列表，点击某个待办项可以进入一个编辑详情页。

1. 创建编辑页面：新建 entry/src/main/pages/Detail.ets。
2. 修改Index页面：将List项中的文本部分改为可点击，并导航到Detail页面，同时传递待办项的ID。

// 在Index.ets的List项中，修改Text部分
Text(item.title)
  .fontSize(18)
  .decoration({ type: item.completed ? TextDecorationType.LineThrough : TextDecorationType.None })
  .fontColor(item.completed ? Color.Gray : Color.Black })
  .layoutWeight(1)
  .onClick(() => {
    // 跳转到详情页，并传递id
    router.pushUrl({
      url: 'pages/Detail',
      params: { todoId: item.id }
    });
  })

3. 实现Detail页面：该页面接收ID，从分布式数据中获取对应待办项，并允许编辑标题和状态。

关键步骤：使Detail页面所在的Ability支持迁移。

我们需要在 EntryAbility.ets 中重写状态保存与恢复的方法。

// entry/src/main/entryability/EntryAbility.ets
import { AbilityConstant, UIAbility, Want } from '@kit.AbilityKit';
import { window } from '@kit.ArkUI';
import { distributedTodoManager } from '../model/DistributedTodoModel';
import { hilog } from '@kit.PerformanceAnalysisKit';

export default class EntryAbility extends UIAbility {
  private currentTodoId: number | undefined; // 记录当前正在查看的待办ID

  onWindowStageCreate(windowStage: window.WindowStage) {
    // ... 原有代码，设置主页面
    // 假设从Want中获取传递的参数（在迁移恢复时）
    const want = this.context.startAbilityParam?.want;
    if (want?.parameters) {
      this.currentTodoId = want.parameters['todoId'] as number;
      // 可以根据todoId决定初始加载哪个页面，这里简化处理
    }
    windowStage.loadContent('pages/Index', (err) => {
      // ...
    });
  }

  // 当系统决定迁移此Ability时调用，用于保存状态
  onSaveState(reason: AbilityConstant.StateType, wantParam: Record<string, Object>): AbilityConstant.OnSaveResult {
    hilog.info(0x0000, 'EntryAbility', 'onSaveState called, reason: %{public}d', reason);
    if (reason === AbilityConstant.StateType.CONTINUATION) { // 迁移原因
      // 将需要迁移的状态存入wantParam
      if (this.currentTodoId !== undefined) {
        wantParam['todoId'] = this.currentTodoId;
        hilog.info(0x0000, 'EntryAbility', 'Saved todoId: %{public}d for continuation.', this.currentTodoId);
      }
      // 可以保存更多状态，如滚动位置、表单内容等
      return AbilityConstant.OnSaveResult.ACCEPT;
    }
    return AbilityConstant.OnSaveResult.REJECT;
  }

  // 在目标设备上恢复Ability状态时调用
  onRestoreState(wantParam: Record<string, Object>): void {
    hilog.info(0x0000, 'EntryAbility', 'onRestoreState called.');
    if (wantParam['todoId']) {
      this.currentTodoId = wantParam['todoId'] as number;
      hilog.info(0x0000, 'EntryAbility', 'Restored todoId: %{public}d', this.currentTodoId);
      // 这里可以触发事件，通知Detail页面加载对应的待办项
      // AppStorage.setOrCreate('restoredTodoId', this.currentTodoId);
    }
  }
}

4. 在UI中触发迁移：在Detail页面的UI上添加一个“流转”按钮。其背后调用的是鸿蒙的分布式任务调度API。

// 在Detail.ets中
import { continuationManager } from '@kit.AbilityKit';
import { BusinessError } from '@kit.BasicServicesKit';
import { promptAction } from '@kit.ArkUI';

@Component
struct Detail {
  @State todoItem: TodoItem | null = null;

  // 触发迁移到其他设备
  startContinuation() {
    let want: Want = {
      deviceId: '', // 空字符串表示由系统选择或用户选择设备
      bundleName: 'com.example.myfirstdistributedapp',
      abilityName: 'EntryAbility',
      parameters: {
        todoId: this.todoItem?.id // 传递当前待办ID
      }
    };

    let options: continuationManager.ContinuationOptions = {
      deviceType: [continuationManager.DeviceType.SMART_PHONE, continuationManager.DeviceType.SMART_PAD] // 指定目标设备类型
    };

    continuationManager.startContinuation(want, options, (err: BusinessError) => {
      if (err) {
        promptAction.showToast({ message: `流转失败: ${err.message}` });
        console.error(`startContinuation failed, code is ${err.code}, message is ${err.message}`);
      } else {
        promptAction.showToast({ message: '已发起流转' });
      }
    });
  }

  build() {
    Column() {
      // ... 待办详情展示UI
      Button('流转到其他设备')
        .onClick(() => {
          this.startContinuation();
        })
    }
  }
}

当用户点击“流转到其他设备”按钮时，系统会弹出设备选择器（显示同一账号下的其他可用设备），用户选择后，当前的Detail页面状态就会迁移到那台设备上继续显示和操作。

4.3 测试与调试技巧

1. 真机环境：准备至少两台HarmonyOS设备，登录相同华为账号，连接同一Wi-Fi。
2. 日志查看：充分利用 hilog 在DevEco Studio的“Log”窗口查看分布式操作的详细日志，这是排查问题最有效的手段。
3. 模拟器限制：分布式设备发现和迁移功能在模拟器上可能受限或不稳定，真机测试是必须的。
4. 权限检查：确保应用已在设备的“设置-应用-权限管理”中获得了“分布式数据”等必要权限。

走到这一步，你已经成功构建了一个具备数据实时同步和界面迁移能力的简单分布式应用。这只是一个起点，鸿蒙的分布式能力远不止于此，还有分布式硬件资源共享（如调用另一台设备的摄像头）、跨设备服务调用等更高级的特性等待探索。开发过程中，多思考用户的实际跨设备使用场景，让技术服务于无缝的体验，才是分布式开发的精髓所在。