文章目录

在这里插入图片描述

每日一句正能量

人生的每个瞬间，都值得你全力经营，用心体会。
反对“到达主义”——认为只有达成某个目标（财富、地位）后人生才开始。其实意义就在过程中，在每一个当下。认真对待此刻，就是认真对待整个人生。

摘要

摘要： HarmonyOS 的分布式能力让多设备协同从概念走向日常。本文聚焦 HarmonyOS 6.1 的跨设备拖拽与剪贴板共享两大特性，从 API 接入、数据格式定义、权限管理到多设备交互设计，提供完整的适配方案。通过外卖应用中将订单卡片从手机拖拽到平板的实战示例，帮助开发者快速掌握分布式数据流转的核心技术。

一、特性概述与适用场景

1.1 跨设备拖拽（Cross-Device Drag & Drop）

跨设备拖拽允许用户在一个设备上长按并拖动内容，直接放置到另一个设备的应用界面中。HarmonyOS 6.1 在原有同设备拖拽的基础上，将能力扩展到同一账号下的任意 HarmonyOS 设备。

典型场景：

场景 操作 效果
手机 → 平板 长按手机上的订单卡片，拖拽到平板 平板直接展示订单详情页
平板 → 智慧屏 拖拽视频链接到智慧屏 智慧屏直接开始播放
手机 → 车机 拖拽导航地址到车机 车机自动发起导航

1.2 剪贴板共享（Clipboard Sharing）

剪贴板共享让复制操作突破设备边界。用户在一台设备上复制内容，可在同一账号下的其他设备上直接粘贴。

典型场景：

场景 操作
手机上复制验证码 平板上直接粘贴，无需手动输入
平板上复制文章链接 手机上粘贴并打开
车机上复制地址 手机上粘贴到地图应用

1.3 两大特性的关系

维度 跨设备拖拽 剪贴板共享
交互方式 手势操作，直观 复制粘贴，习惯
数据量 可携带大文件/富媒体 适合文本/小数据
目标明确性 明确知道要拖到哪个应用 不确定在哪个设备粘贴
实时性 即时传输 延迟数秒同步

二、跨设备拖拽 API 详解

2.1 核心模块

HarmonyOS 6.1 的跨设备拖拽能力封装在 @kit.ArkUI 的拖拽框架中，核心接口如下：

import { drag } from '@kit.ArkUI';
import { distributedDeviceManager } from '@kit.DistributedServiceKit';

在这里插入图片描述

2.2 让组件可拖拽

通过 draggable(true) 和 onDragStart 将任意 ArkUI 组件变为拖拽源：

// components/DraggableOrderCard.ets
@Component
export struct DraggableOrderCard {
  @Prop order: Order;

  build() {
    Column() {
      Text(this.order.shopName)
        .fontSize(16)
        .fontWeight(FontWeight.Bold);
      Text(`订单号: ${this.order.id}`)
        .fontSize(12)
        .fontColor('#888');
      Text(`¥${this.order.totalPrice}`)
        .fontSize(18)
        .fontColor('#e74c3c');
    }
    .width('100%')
    .padding(16)
    .backgroundColor('#f8f9fa')
    .borderRadius(12)
    .draggable(true)  // 启用拖拽
    .onDragStart((event: DragEvent) => {
      // 构造拖拽数据
      const dragData = this.buildDragData();
      event.setData(dragData);
      
      // 设置拖拽预览图
      event.setPreview({
        builder: () => this.dragPreviewBuilder()
      });
      
      console.info(`[Drag] 开始拖拽订单: ${this.order.id}`);
    })
    .onDragEnd((event: DragEvent) => {
      if (event.getResult() === DragResult.DRAG_SUCCESSFUL) {
        console.info('[Drag] 拖拽成功');
      } else {
        console.info('[Drag] 拖拽取消或失败');
      }
    });
  }

  private buildDragData(): drag.DragData {
    // 定义拖拽数据的 MIME 类型与内容
    return {
      mimeTypes: ['application/vnd.harmonyos.order', 'text/plain'],
      data: JSON.stringify({
        orderId: this.order.id,
        shopName: this.order.shopName,
        totalPrice: this.order.totalPrice,
        items: this.order.items,
        // 跨设备必需的标识
        sourceDevice: distributedDeviceManager.getLocalDeviceId(),
        timestamp: Date.now()
      })
    };
  }

  @Builder
  private dragPreviewBuilder() {
    Column() {
      Text(this.order.shopName)
        .fontSize(14)
        .fontColor('#333');
    }
    .padding(12)
    .backgroundColor('#ffffff')
    .borderRadius(8)
    .shadow({ radius: 8, color: 'rgba(0,0,0,0.15)' });
  }
}

2.3 接收拖拽数据

目标组件通过 onDrop 接收拖拽数据：

// pages/OrderDropZone.ets
@Component
struct OrderDropZone {
  @State droppedOrder: Order | null = null;
  @State isDraggingOver: boolean = false;

  build() {
    Column() {
      Text('拖拽订单到此处')
        .fontSize(16)
        .fontColor(this.isDraggingOver ? '#3498db' : '#888');

      if (this.droppedOrder) {
        OrderDetailCard({ order: this.droppedOrder });
      }
    }
    .width('100%')
    .height(200)
    .backgroundColor(this.isDraggingOver ? '#f0f3ff' : '#f5f6fa')
    .borderRadius(12)
    .border({
      width: 2,
      color: this.isDraggingOver ? '#3498db' : 'transparent',
      style: BorderStyle.Dashed
    })
    .allowDrop(['application/vnd.harmonyos.order', 'text/plain'])
    .onDragEnter(() => {
      this.isDraggingOver = true;
      console.info('[Drop] 拖拽进入目标区域');
    })
    .onDragLeave(() => {
      this.isDraggingOver = false;
      console.info('[Drop] 拖拽离开目标区域');
    })
    .onDrop((event: DragEvent) => {
      this.isDraggingOver = false;
      
      // 获取拖拽数据
      const dragData = event.getData();
      const plainText = dragData.getData('text/plain');
      
      if (plainText) {
        try {
          const orderData = JSON.parse(plainText) as OrderData;
          
          // 校验数据来源
          if (this.validateOrderData(orderData)) {
            this.droppedOrder = this.convertToOrder(orderData);
            
            // 判断是否为跨设备拖拽
            if (orderData.sourceDevice !== distributedDeviceManager.getLocalDeviceId()) {
              console.info(`[Drop] 收到来自设备 ${orderData.sourceDevice} 的跨设备拖拽`);
              promptAction.showToast({ message: '已接收来自手机的订单' });
            }
          }
        } catch (err) {
          console.error('[Drop] 数据解析失败:', err);
        }
      }
      
      event.setResult(DragResult.DRAG_SUCCESSFUL);
    });
  }

  private validateOrderData(data: OrderData): boolean {
    return !!data.orderId && !!data.shopName && data.timestamp > 0;
  }

  private convertToOrder(data: OrderData): Order {
    return {
      id: data.orderId,
      shopName: data.shopName,
      totalPrice: data.totalPrice,
      items: data.items ?? []
    };
  }
}

interface OrderData {
  orderId: string;
  shopName: string;
  totalPrice: number;
  items?: OrderItem[];
  sourceDevice: string;
  timestamp: number;
}

三、剪贴板共享实战

3.1 剪贴板基础 API

HarmonyOS 6.1 的剪贴板服务在 @kit.BasicServicesKit 中：

import { pasteboard } from '@kit.BasicServicesKit';

3.2 写入剪贴板（带跨设备标记）

// services/ClipboardHelper.ets
import { pasteboard } from '@kit.BasicServicesKit';
import { distributedDeviceManager } from '@kit.DistributedServiceKit';

export class ClipboardHelper {
  // 复制订单信息到剪贴板，支持跨设备共享
  static async copyOrder(order: Order): Promise<void> {
    const systemPasteboard = pasteboard.getSystemPasteboard();

    // 构造 PasteData，包含多种 MIME 类型
    const pasteData = pasteboard.createData(pasteboard.MIMETYPE_TEXT_PLAIN,
      `订单: ${order.shopName}\n金额: ¥${order.totalPrice}\n编号: ${order.id}`
    );

    // 添加 HarmonyOS 专属数据格式
    pasteData.addRecord({
      mimeType: 'application/vnd.harmonyos.order',
      plainText: JSON.stringify({
        orderId: order.id,
        shopName: order.shopName,
        totalPrice: order.totalPrice,
        sourceDevice: distributedDeviceManager.getLocalDeviceId()
      })
    });

    // 写入剪贴板并启用跨设备同步
    await systemPasteboard.setData(pasteData);
    await systemPasteboard.setDistributedEnable(true);  // 关键：启用跨设备同步

    promptAction.showToast({ message: '已复制，可在其他设备粘贴' });
  }

  // 读取剪贴板内容
  static async readClipboard(): Promise<ClipboardContent | null> {
    const systemPasteboard = pasteboard.getSystemPasteboard();
    const hasData = await systemPasteboard.hasData();

    if (!hasData) {
      return null;
    }

    const pasteData = await systemPasteboard.getData();
    const records = pasteData.getAllRecords();

    let plainText = '';
    let harmonyData: OrderData | null = null;

    for (const record of records) {
      if (record.mimeType === pasteboard.MIMETYPE_TEXT_PLAIN) {
        plainText = record.plainText ?? '';
      }
      if (record.mimeType === 'application/vnd.harmonyos.order') {
        try {
          harmonyData = JSON.parse(record.plainText ?? '{}') as OrderData;
        } catch { /* ignore */ }
      }
    }

    return { plainText, harmonyData };
  }
}

interface ClipboardContent {
  plainText: string;
  harmonyData: OrderData | null;
}

3.3 监听剪贴板变化

在页面中实时响应跨设备粘贴：

// pages/OrderList.ets
import { pasteboard } from '@kit.BasicServicesKit';

@Entry
@Component
struct OrderList {
  @State orders: Order[] = [];
  private pasteboardListener: (() => void) | null = null;

  aboutToAppear(): void {
    // 监听剪贴板变化
    const systemPasteboard = pasteboard.getSystemPasteboard();
    this.pasteboardListener = () => {
      this.handleClipboardChange();
    };
    systemPasteboard.on('update', this.pasteboardListener);
  }

  aboutToDisappear(): void {
    if (this.pasteboardListener) {
      pasteboard.getSystemPasteboard().off('update', this.pasteboardListener);
    }
  }

  private async handleClipboardChange(): Promise<void> {
    const content = await ClipboardHelper.readClipboard();
    
    if (content?.harmonyData) {
      const data = content.harmonyData;
      const isCrossDevice = data.sourceDevice !== distributedDeviceManager.getLocalDeviceId();
      
      if (isCrossDevice) {
        // 来自其他设备的剪贴板内容
        promptAction.showToast({ 
          message: `检测到来自其他设备的订单: ${data.shopName}` 
        });
        
        // 可选：自动跳转到订单详情
        // router.pushUrl({ url: 'pages/OrderDetail', params: { orderId: data.orderId } });
      }
    }
  }

  build() {
    Column() {
      // 页面内容...
    }
  }
}

四、权限申请与配置

4.1 权限声明

跨设备数据流转涉及分布式能力，需要声明以下权限：

在这里插入图片描述

// module.json5
{
  "module": {
    "requestPermissions": [
      {
        "name": "ohos.permission.DISTRIBUTED_DATASYNC",
        "reason": "$string:dist_data_sync_reason"
      },
      {
        "name": "ohos.permission.DISTRIBUTED_SOFTBUS_CENTER",
        "reason": "$string:dist_softbus_reason"
      },
      {
        "name": "ohos.permission.ACCESS_PASTEBOARD",
        "reason": "$string:pasteboard_reason"
      },
      {
        "name": "ohos.permission.GET_NETWORK_INFO",
        "reason": "$string:network_info_reason"
      }
    ]
  }
}

4.2 分布式设备发现

在发起跨设备拖拽前，需要确保目标设备已在线：

// services/DeviceManager.ets
import { distributedDeviceManager } from '@kit.DistributedServiceKit';

export class DeviceManager {
  // 获取同一账号下的在线设备列表
  static async getOnlineDevices(): Promise<DeviceInfo[]> {
    try {
      const devices = await distributedDeviceManager.getAvailableDeviceListSync();
      return devices.map(device => ({
        id: device.deviceId,
        name: device.deviceName,
        type: device.deviceType,  // phone / tablet / tv / car
        isLocal: device.isLocal
      }));
    } catch (err) {
      console.error('[Device] 获取设备列表失败:', err);
      return [];
    }
  }

  // 判断当前是否有其他在线设备
  static async hasPeerDevices(): Promise<boolean> {
    const devices = await this.getOnlineDevices();
    return devices.some(d => !d.isLocal);
  }
}

interface DeviceInfo {
  id: string;
  name: string;
  type: string;
  isLocal: boolean;
}

五、数据流转与交互设计

5.1 跨设备数据流转图

在这里插入图片描述

上图展示了跨设备拖拽与剪贴板共享的完整数据流转链路。拖拽数据通过分布式软总线直接传输，剪贴板数据则通过分布式数据管理服务异步同步。

5.2 数据格式设计规范

跨设备传输的数据应遵循以下规范：

// 通用跨设备数据包格式
interface DistributedDataPacket {
  // 协议版本，用于兼容性处理
  version: '1.0';
  
  // 数据类型标识
  mimeType: string;
  
  // 实际业务数据（JSON 序列化）
  payload: string;
  
  // 元数据
  metadata: {
    sourceDevice: string;     // 来源设备 ID
    targetDevice?: string;    // 目标设备 ID（可选）
    timestamp: number;        // 创建时间
    ttl: number;              // 有效期（毫秒）
  };
  
  // 安全签名（可选，高敏感数据使用）
  signature?: string;
}

5.3 交互设计建议

场景 设计建议
拖拽预览 跨设备拖拽时，预览图应包含"跨设备"视觉标识
放置反馈 数据到达后，播放轻微音效 + Toast 提示来源设备
冲突处理 同一数据多次拖拽，以时间戳最新的为准
离线处理 目标设备离线时，数据缓存 24 小时，上线后推送

六、完整实战：手机 → 平板订单流转

以下是将手机上的订单卡片拖拽到平板查看详情的完整实现：

// Phone端：拖拽源页面
@Entry
@Component
struct PhoneOrderPage {
  @State orders: Order[] = [
    { id: '1001', shopName: '麦当劳', totalPrice: 45.5, items: [] },
    { id: '1002', shopName: '星巴克', totalPrice: 38.0, items: [] }
  ];

  build() {
    Column({ space: 12 }) {
      Text('长按订单卡片，拖拽到平板')
        .fontSize(14)
        .fontColor('#888')
        .margin({ top: 20, bottom: 10 });

      List() {
        ForEach(this.orders, (order: Order) => {
          ListItem() {
            DraggableOrderCard({ order })
          }
        });
      }
      .width('100%')
      .layoutWeight(1);
    }
    .width('100%')
    .height('100%')
    .padding(16);
  }
}

// Pad端：接收页面
@Entry
@Component
struct PadOrderPage {
  @State receivedOrders: Order[] = [];

  build() {
    Row() {
      // 左侧：订单列表（本地）
      Column() {
        Text('本地订单')
          .fontSize(18)
          .fontWeight(FontWeight.Bold)
          .margin(16);
        // ...
      }
      .width('50%')
      .height('100%');

      // 右侧：跨设备接收区
      Column() {
        Text('跨设备订单')
          .fontSize(18)
          .fontWeight(FontWeight.Bold)
          .margin(16);

        OrderDropZone()
          .width('90%')
          .height(300);

        List() {
          ForEach(this.receivedOrders, (order: Order) => {
            ListItem() {
              OrderDetailCard({ order })
            }
          });
        }
        .width('90%')
        .layoutWeight(1);
      }
      .width('50%')
      .height('100%')
      .backgroundColor('#fafafa');
    }
    .width('100%')
    .height('100%');
  }
}

七、常见问题与排障

7.1 跨设备拖拽失败

现象 原因 解决
拖拽时无跨设备预览 未登录同一华为账号 检查设备是否登录同一账号
放置后无数据 MIME 类型不匹配 确保 allowDrop 包含拖拽源的 MIME 类型
数据解析错误 JSON 格式不一致 统一数据格式版本号，做兼容性处理
拖拽延迟高 网络状况差 分布式软总线依赖局域网，检查 Wi-Fi 连接

7.2 剪贴板不同步

现象 原因 解决
其他设备粘贴为空 未启用分布式同步 调用 setDistributedEnable(true)
同步延迟高 网络波动 剪贴板同步为异步操作，允许数秒延迟
大数据无法同步 剪贴板大小限制 超过 1MB 的数据建议用拖拽或文件传输

八、总结

HarmonyOS 6.1 的跨设备拖拽与剪贴板共享，将分布式能力从"系统级特性"下沉为"应用级 API"，让开发者能以极低的成本实现多设备协同体验。

核心要点回顾：

  • 在 module.json5 中申请 DISTRIBUTED_DATASYNC 和 ACCESS_PASTEBOARD 权限；
  • 拖拽源组件设置 draggable(true) 和 onDragStart，构造标准化数据包；
  • 目标区域设置 allowDrop 和 onDrop，处理跨设备数据到达；
  • 剪贴板写入时调用 setDistributedEnable(true) 启用跨设备同步；
  • 监听剪贴板 update 事件，实时响应其他设备的复制操作；
  • 数据包包含 sourceDevice 和 timestamp，便于溯源和去重；
  • 为跨设备操作提供明确的视觉和听觉反馈。

多设备协同不是未来，而是现在。掌握这两项特性，意味着你的应用已经站在了 HarmonyOS 分布式体验的第一梯队。

转载自：https://blog.csdn.net/u014727709/article/details/162939332
欢迎 👍点赞✍评论⭐收藏，欢迎指正

# HarmonyOS 6.1
Logo
HarmonyOS开发者社区

讨论HarmonyOS开发技术，专注于API与组件、DevEco Studio、测试、元服务和应用上架分发等。

更多推荐

cover

莘莘学子，学习鸿蒙，致力自主系统开发

avatar HarmonyOS开发者社区
cover

鸿蒙三方库 | harmony-utils之NetworkUtil默认网络与绑定网络详解

avatar HarmonyOS开发者社区
cover

HarmonyOS新特性-沉浸光感在叠叠消小游戏中的落地实践

avatar HarmonyOS开发者社区