HarmonyOS实战项目：构建一个跨设备的Todo清单应用（上）

news/2025/10/30 11:05:14/文章来源:https://www.cnblogs.com/ifeng0918/p/19176293

1. 项目概述与架构设计

1.1 项目背景与核心价值

在HarmonyOS生态中，跨设备Todo应用是展示分布式能力的最佳实践场景。用户可以在手机端创建任务，在平板上查看编辑，在手表上接收提醒，实现真正的无缝体验。这种多设备协同模式解决了传统单设备应用的数据孤岛问题，让用户任务管理更加高效便捷。

与传统Todo应用的对比优势：

数据实时同步：任一设备的操作秒级同步到所有设备
设备能力互补：手机便捷输入、平板大屏浏览、手表即时提醒
体验连续性：设备间任务状态无缝流转，不中断用户工作流

1.2 技术架构设计

本项目采用分层分布式架构，确保系统的高可用性和可扩展性：

应用层：UI界面（手机、平板、手表多端适配）↓
业务层：任务管理、分布式同步、冲突解决↓
服务层：数据持久化、设备管理、消息推送↓
通信层：分布式软总线、数据同步引擎

核心模块职责划分：

任务管理模块：负责Todo任务的CRUD操作和本地存储
设备管理模块：发现可用设备、管理设备状态和能力
同步引擎模块：处理跨设备数据同步和冲突解决
UI适配模块：针对不同设备尺寸提供最佳交互体验

2. 开发环境配置与项目初始化

2.1 环境准备与依赖配置

首先在package.json中配置项目依赖和HarmonyOS SDK版本要求：

{"dependencies": {"@ohos/distributedHardware": "^1.0.0","@ohos/data.distributedDataObject": "^1.0.0","@ohos.data.distributedKVStore": "^1.0.0","@ohos.ability.featureAbility": "^1.0.0"},"harmonyos": {"compileSdkVersion": 12,"compatibleSdkVersion": 9}
}

2.2 权限声明配置

在module.json5中声明应用所需的分布式权限：

{"module": {"requestPermissions": [{"name": "ohos.permission.DISTRIBUTED_DATASYNC","reason": "用于跨设备同步Todo数据","usedScene": {"abilities": ["MainAbility"],"when": "always"}},{"name": "ohos.permission.GET_DISTRIBUTED_DEVICE_INFO","reason": "发现和连接其他设备","usedScene": {"abilities": ["MainAbility"],"when": "inuse"}}]}
}

3. 数据模型设计与分布式存储

3.1 核心数据模型定义

设计良好的数据模型是分布式应用的基础。以下是Todo应用的核心数据结构：

// Todo任务数据模型
interface TodoItem {id: string;                    // 全局唯一标识title: string;                 // 任务标题description?: string;          // 任务描述（可选）completed: boolean;            // 完成状态priority: 'low' | 'medium' | 'high';  // 优先级dueDate?: number;              // 截止时间戳createdAt: number;             // 创建时间updatedAt: number;             // 最后更新时间deviceId: string;             // 创建设备IDtags: string[];               // 标签分类
}// 同步元数据
interface SyncMetadata {version: number;               // 数据版本号（用于冲突检测）lastSyncTime: number;         // 最后同步时间deviceId: string;             // 最后修改设备
}// 设备信息模型
interface DeviceInfo {deviceId: string;             // 设备唯一标识deviceName: string;           // 设备显示名称deviceType: 'phone' | 'tablet' | 'watch' | 'tv'; // 设备类型capabilities: DeviceCapabilities; // 设备能力lastSeen: number;             // 最后在线时间isTrusted: boolean;           // 是否可信设备
}

3.2 分布式数据存储实现

采用KV Store作为主要存储方案，平衡性能与复杂度：

import distributedKVStore from '@ohos.data.distributedKVStore';
import { BusinessError } from '@ohos.base';class TodoDataManager {private kvManager: distributedKVStore.KVManager | null = null;private kvStore: distributedKVStore.KVStore | null = null;// 初始化分布式KV Storeasync initializeDataStore(): Promise<void> {try {const config: distributedKVStore.KVManagerConfig = {bundleName: 'com.example.todoapp',userInfo: { userId: 'defaultUser' }};this.kvManager = distributedKVStore.createKVManager(config);const options: distributedKVStore.Options = {createIfMissing: true,encrypt: false,backup: false,autoSync: true,kvStoreType: distributedKVStore.KVStoreType.DEVICE_COLLABORATION,securityLevel: distributedKVStore.SecurityLevel.S2};this.kvStore = await this.kvManager.getKVStore('todo_store', options);// 设置数据变更监听this.setupDataChangeListener();} catch (error) {console.error('初始化数据存储失败:', error);}}// 保存Todo任务async saveTodoItem(todo: TodoItem): Promise<boolean> {if (!this.kvStore) return false;try {// 更新元数据todo.updatedAt = Date.now();const syncKey = `todo_${todo.id}`;await this.kvStore.put(syncKey, JSON.stringify(todo));return true;} catch (error) {console.error('保存Todo失败:', error);return false;}}// 获取所有Todo任务async getAllTodos(): Promise<TodoItem[]> {if (!this.kvStore) return [];try {const entries = await this.kvStore.getEntries('todo_');const todos: TodoItem[] = [];for (const entry of entries) {try {const todo = JSON.parse(entry.value as string) as TodoItem;todos.push(todo);} catch (parseError) {console.warn('解析Todo数据失败:', parseError);}}return todos.sort((a, b) => b.updatedAt - a.updatedAt);} catch (error) {console.error('获取Todo列表失败:', error);return [];}}
}

4. 设备管理与发现机制

4.1 设备发现与连接

实现设备的自动发现和可信连接管理：

import deviceManager from '@ohos.distributedHardware.deviceManager';class DeviceDiscoveryManager {private availableDevices: Map<string, DeviceInfo> = new Map();private deviceCallbacks: Array<(devices: DeviceInfo[]) => void> = [];// 初始化设备发现async initializeDeviceDiscovery(): Promise<void> {try {const dm = await deviceManager.createDeviceManager('com.example.todoapp');// 监听设备状态变化dm.on('deviceStateChange', (data) => {this.handleDeviceStateChange(data);});// 开始设备发现const subscribeInfo = {subscribeId: Math.random().toString(36).substring(2),mode: 0xAA, // 主动发现模式medium: 2,   // Wi-Fifreq: 2,     // 正常频率isSameAccount: false,isWakeRemote: true,capability: 0};dm.startDeviceDiscovery(subscribeInfo);} catch (error) {console.error('设备发现初始化失败:', error);}}// 处理设备状态变化private handleDeviceStateChange(data: any): void {const { deviceId, deviceName, deviceType, state } = data;if (state === 'online') {// 设备上线const deviceInfo: DeviceInfo = {deviceId,deviceName,deviceType: this.mapDeviceType(deviceType),capabilities: await this.getDeviceCapabilities(deviceId),lastSeen: Date.now(),isTrusted: true};this.availableDevices.set(deviceId, deviceInfo);this.notifyDeviceCallbacks();} else if (state === 'offline') {// 设备离线this.availableDevices.delete(deviceId);this.notifyDeviceCallbacks();}}// 获取可信设备列表getTrustedDevices(): DeviceInfo[] {return Array.from(this.availableDevices.values()).filter(device => device.isTrusted).sort((a, b) => b.lastSeen - a.lastSeen);}
}

4.2 设备能力协商

不同设备具有不同的能力，需要智能分配任务：

interface DeviceCapabilities {canEdit: boolean;        // 是否支持编辑canNotify: boolean;      // 是否支持通知screenSize: 'small' | 'medium' | 'large'; // 屏幕尺寸inputMethods: ('touch' | 'voice' | 'keyboard')[]; // 输入方式
}class DeviceCapabilityManager {// 根据设备类型推断能力inferCapabilities(deviceType: string): DeviceCapabilities {const capabilities: { [key: string]: DeviceCapabilities } = {'phone': {canEdit: true,canNotify: true,screenSize: 'small',inputMethods: ['touch', 'voice']},'tablet': {canEdit: true,canNotify: true,screenSize: 'medium',inputMethods: ['touch', 'keyboard']},'watch': {canEdit: false,canNotify: true,screenSize: 'small',inputMethods: ['touch']},'tv': {canEdit: false,canNotify: false,screenSize: 'large',inputMethods: []}};return capabilities[deviceType] || capabilities.phone;}// 为任务分配合适的设备findSuitableDeviceForTask(task: TodoItem, devices: DeviceInfo[]): string | null {if (task.completed) {// 已完成任务适合在任何设备查看return devices[0]?.deviceId || null;}// 未完成任务优先选择支持编辑的设备const editableDevices = devices.filter(device => device.capabilities.canEdit);if (editableDevices.length > 0) {// 优先选择屏幕较大的设备进行编辑return editableDevices.sort((a, b) => this.getScreenSizeScore(b.capabilities.screenSize) - this.getScreenSizeScore(a.capabilities.screenSize))[0].deviceId;}return null;}private getScreenSizeScore(size: string): number {const scores = { 'small': 1, 'medium': 2, 'large': 3 };return scores[size] || 1;}
}

5. 分布式任务同步引擎

5.1 同步策略设计

实现高效可靠的数据同步机制：

class SyncEngine {private pendingChanges: Map<string, TodoItem> = new Map();private isSyncing: boolean = false;private syncQueue: Array<() => Promise<void>> = [];// 队列化同步操作async queueSyncOperation(operation: () => Promise<void>): Promise<void> {this.syncQueue.push(operation);if (!this.isSyncing) {await this.processSyncQueue();}}// 处理同步队列private async processSyncQueue(): Promise<void> {this.isSyncing = true;while (this.syncQueue.length > 0) {const operation = this.syncQueue.shift();if (operation) {try {await operation();} catch (error) {console.error('同步操作失败:', error);// 重试逻辑await this.retryOperation(operation);}}}this.isSyncing = false;}// 增量同步机制async performIncrementalSync(localTodos: TodoItem[], remoteTodos: TodoItem[]): Promise<TodoItem[]> {const mergedTodos: TodoItem[] = [];const localMap = new Map(localTodos.map(todo => [todo.id, todo]));const remoteMap = new Map(remoteTodos.map(todo => [todo.id, todo]));// 合并所有唯一的IDconst allIds = new Set([...localMap.keys(), ...remoteMap.keys()]);for (const id of allIds) {const local = localMap.get(id);const remote = remoteMap.get(id);if (local && remote) {// 冲突解决mergedTodos.push(this.resolveConflict(local, remote));} else if (local) {mergedTodos.push(local);} else if (remote) {mergedTodos.push(remote);}}return mergedTodos;}
}

5.2 冲突解决策略

处理多设备同时修改的数据冲突：

class ConflictResolver {// 基于时间戳的冲突解决resolveConflict(local: TodoItem, remote: TodoItem): TodoItem {// 优先选择较新的版本if (remote.updatedAt > local.updatedAt) {return remote;} else if (local.updatedAt > remote.updatedAt) {return local;}// 时间戳相同，基于设备优先级return this.resolveByDevicePriority(local, remote);}// 基于设备类型的优先级解决private resolveByDevicePriority(local: TodoItem, remote: TodoItem): TodoItem {const devicePriority = { 'phone': 3, 'tablet': 2, 'watch': 1, 'tv': 0 };const localPriority = devicePriority[local.deviceType] || 0;const remotePriority = devicePriority[remote.deviceType] || 0;if (remotePriority > localPriority) {return remote;} else {return local;}}// 智能合并策略（用于复杂冲突）smartMerge(local: TodoItem, remote: TodoItem): TodoItem {// 检查哪些字段有冲突const conflictedFields = this.getConflictedFields(local, remote);if (conflictedFields.length === 0) {return local.updatedAt >= remote.updatedAt ? local : remote;}// 对每个冲突字段应用特定合并规则const merged = { ...local };for (const field of conflictedFields) {merged[field] = this.mergeField(field, local[field], remote[field]);}merged.updatedAt = Date.now();merged.deviceId = this.getCurrentDeviceId();return merged;}
}

6. 基础UI组件与交互设计

6.1 响应式布局组件

创建适配不同屏幕尺寸的UI组件：

@Component
struct TodoListItem {@Prop todo: TodoItem;@Prop onToggle: (id: string) => void;@Prop onEdit: (todo: TodoItem) => void;@StorageProp('currentDeviceType') deviceType: string;build() {Row() {// 完成状态复选框Checkbox({ selected: this.todo.completed }).onChange((checked: boolean) => {this.onToggle(this.todo.id);}).margin(12)// 任务内容区域Column() {Text(this.todo.title).fontSize(this.getTitleFontSize()).decoration({ type: this.todo.completed ? TextDecorationType.LineThrough : TextDecorationType.None })if (this.todo.description) {Text(this.todo.description).fontSize(14).fontColor(Color.Gray).maxLines(2).margin({ top: 4 })}// 标签和日期信息if (this.deviceType !== 'watch') {this.buildMetaInfo();}}.layoutWeight(1).alignItems(HorizontalAlign.Start)// 操作按钮（根据设备能力显示）if (this.deviceType !== 'watch') {Button('编辑').onClick(() => this.onEdit(this.todo)).padding(8)}}.padding(16).backgroundColor(Color.White).borderRadius(8).shadow(2)}// 根据设备类型调整字体大小private getTitleFontSize(): number {const sizes = { 'phone': 16, 'tablet': 18, 'watch': 14, 'tv': 20 };return sizes[this.deviceType] || 16;}@BuilderbuildMetaInfo() {Row() {if (this.todo.priority !== 'medium') {Text(this.getPriorityText()).fontSize(12).fontColor(this.getPriorityColor()).padding({ left: 8, right: 8, top: 2, bottom: 2 }).backgroundColor(this.getPriorityBackground()).borderRadius(4)}if (this.todo.dueDate) {Text(this.formatDate(this.todo.dueDate)).fontSize(12).fontColor(Color.Gray).margin({ left: 8 })}}.margin({ top: 8 })}
}

6.2 设备适配的页面布局

主页面根据设备能力提供不同的布局：

@Entry
@Component
struct TodoMainPage {@State todos: TodoItem[] = [];@State currentDevice: DeviceInfo;@Provide('currentDeviceType') deviceType: string = 'phone';// 设备特定的布局配置private getLayoutConfig() {const configs = {'phone': { columns: 1, itemHeight: 80 },'tablet': { columns: 2, itemHeight: 100 },'tv': { columns: 3, itemHeight: 120 },'watch': { columns: 1, itemHeight: 60 }};return configs[this.deviceType] || configs.phone;}build() {Column() {// 标题栏this.buildHeader()// 内容区域if (this.deviceType === 'phone' || this.deviceType === 'watch') {this.buildMobileLayout();} else {this.buildTabletLayout();}}.width('100%').height('100%').backgroundColor('#F5F5F5')}@BuilderbuildHeader() {Row() {Text('Todo清单').fontSize(24).fontWeight(FontWeight.Bold)Blank()// 设备连接状态指示器DeviceStatusIndicator({ device: this.currentDevice })// 同步状态指示器SyncStatusIndicator()}.padding(16).backgroundColor(Color.White)}@BuilderbuildMobileLayout() {Column() {// 统计信息TodoStatistics({ todos: this.todos })// 列表区域List({ space: 12 }) {ForEach(this.todos, (todo: TodoItem) => {ListItem() {TodoListItem({ todo: todo,onToggle: this.toggleTodo.bind(this),onEdit: this.editTodo.bind(this)})}})}.layoutWeight(1)}}@BuilderbuildTabletLayout() {Row() {// 侧边栏（统计和筛选）Column() {TodoStatistics({ todos: this.todos })TodoFilter()}.width('30%').margin({ right: 12 })// 主内容区Column() {List({ space: 12 }) {ForEach(this.todos, (todo: TodoItem) => {ListItem() {TodoListItem({ todo: todo,onToggle: this.toggleTodo.bind(this),onEdit: this.editTodo.bind(this)})}})}}.layoutWeight(1)}}
}