鸿蒙学习实战之路-跨设备剪贴板完全指南

跨设备剪贴板的概念：就像空中餐盘，能在设备间传递数据约束与限制：需要同一账号、Wi-Fi、蓝牙等条件复制功能：设备 A 复制数据到剪贴板粘贴功能：设备 B 从剪贴板获取数据进阶玩法：处理不同类型的数据是不是超简单？只需要几行代码，就能实现跨设备剪贴板功能，提升用户体验！

刺猬二大爷

491人浏览 · 2026-01-14 06:00:00

刺猬二大爷 · 2026-01-14 06:00:00 发布

鸿蒙学习实战之路-跨设备剪贴板完全指南

最近好多朋友问我：“西兰花啊，我在平板上复制了一段文字，想粘到手机上咋弄啊？总不能每次都发微信吧！” 害，这问题可问对人了！今天我就手把手带你实现这个超实用的跨设备剪贴板功能，就像把菜从一个盘子直接夹到另一个盘子那么方便～

🥦 先唠唠跨设备剪贴板是啥

剪贴板分为本地剪贴板和跨设备剪贴板，本地剪贴板就像你家厨房的盘子，只能在自己家（设备内）用；跨设备剪贴板就像有个"空中餐盘"，能把你在 A 设备复制的东西直接拿到 B 设备粘贴！

想象一下：你在平板上看到一段很棒的菜谱，复制下来，直接在手机的备忘录里粘贴保存，连微信都不用打开，是不是超级高效？

看看官方给的效果图，是不是超直观？

在这里插入图片描述

🤖 它是怎么工作的？

就像餐厅的传菜系统，有一套完整的流程：

在这里插入图片描述

你夹菜：在设备 A 复制数据（就像把菜夹到空中餐盘）
传菜员送菜：系统剪贴板服务处理数据并完成同步（这个过程你看不到）
你接菜：在设备 B 粘贴来自设备 A 的数据（就像从空中餐盘把菜夹到自己的盘子里）

作为开发者，咱们只需要实现"夹菜"和"接菜"这两步，剩下的系统帮咱们搞定～

📱 哪些应用适合用？

如果你正在开发：

浏览器类应用
备忘录、笔记类应用
邮件等富文本编辑类应用
任何需要复制粘贴的应用

都可以接入跨设备剪贴板，提升用户体验！

🥦 西兰花警告

在开始之前，先说说约束与限制：

设备版本	限制条件
HarmonyOS NEXT Developer Preview0 及以上	✅ 双端设备需要打开跨设备剪贴板开关 ✅ 双端设备需要登录同一华为账号 ✅ 双端设备需要打开 Wi-Fi 和蓝牙 ✅ 双端设备过程中需解锁、亮屏

这些条件一个都不能少！就像炒菜不能少了火，少了哪个都炒不出好菜～

第一步：准备工具（导入模块）

要做饭得先准备好工具，要做跨设备剪贴板得先导入模块：

import pasteboard from "@ohos.pasteboard";
import { BusinessError } from "@ohos.base";

就这么简单！不需要申请额外权限，系统会自动处理～

第二步：夹菜（设备 A 复制数据）

现在咱们来实现复制功能，就像把菜夹到空中餐盘：

// 复制数据到剪贴板
async function 复制到剪贴板(): Promise<void> {
  // 要复制的内容（就像要夹的菜）
  let 要复制的内容: string = "西兰花真好吃！";

  // 把内容放到剪贴板里（夹到空中餐盘）
  let 剪贴板内容: pasteboard.PasteData = pasteboard.createData(
    pasteboard.MIMETYPE_TEXT_PLAIN, // 数据类型：纯文本
    要复制的内容 // 要复制的内容
  );

  // 获取系统剪贴板对象（找到空中餐盘）
  let 系统剪贴板: pasteboard.SystemPasteboard =
    pasteboard.getSystemPasteboard();

  // 把内容放到系统剪贴板（菜放到空中餐盘）
  await 系统剪贴板.setData(剪贴板内容).catch((err: BusinessError) => {
    console.error(`复制失败: ${err.code}, ${err.message}`);
  });

  console.info("复制成功！内容：" + 要复制的内容);
}

🥦 西兰花小贴士：

跨设备复制的数据两分钟内有效，就像菜放久了会凉～
系统会自动处理跨设备的数据传递，咱们只需要像本地剪贴板一样用就行！

第三步：接菜（设备 B 粘贴数据）

现在咱们来实现粘贴功能，就像从空中餐盘把菜夹到自己的盘子里：

// 从剪贴板粘贴数据
async function 从剪贴板粘贴(): Promise<void> {
  // 获取系统剪贴板对象（找到空中餐盘）
  let 系统剪贴板: pasteboard.SystemPasteboard =
    pasteboard.getSystemPasteboard();

  // 从剪贴板获取内容（从空中餐盘夹菜）
  系统剪贴板.getData((err: BusinessError, data: pasteboard.PasteData) => {
    if (err) {
      console.error(`粘贴失败: ${err.code}, ${err.message}`);
      return;
    }

    // 处理获取到的内容
    // 1. 获取剪贴板里有多少个内容
    let 内容数量: number = data.getRecordCount();
    console.info("剪贴板里有" + 内容数量 + "个内容");

    // 2. 获取主要数据类型
    let 数据类型: string = data.getPrimaryMimeType();
    console.info("主要数据类型: " + 数据类型);

    // 3. 获取主要文本内容（直接夹最上面的菜）
    let 主要内容: string = data.getPrimaryText();
    console.info("粘贴的内容: " + 主要内容);

    // 这里可以把内容显示到界面上
  });
}

第四步：进阶玩法（处理不同类型的数据）

刚才咱们只处理了文本，现在来试试处理其他类型的数据。不过别担心，基本原理都差不多～

4.1 复制其他类型的数据

// 复制自定义类型的数据
async function 复制自定义数据(): Promise<void> {
  // 假设我们要复制一个图片
  let 图片数据: ArrayBuffer = new ArrayBuffer(1024); // 这里应该是实际的图片数据

  let 剪贴板内容: pasteboard.PasteData = pasteboard.createData(
    "image/jpeg", // 图片类型
    图片数据 // 图片数据
  );

  let 系统剪贴板: pasteboard.SystemPasteboard =
    pasteboard.getSystemPasteboard();
  await 系统剪贴板.setData(剪贴板内容).catch((err: BusinessError) => {
    console.error(`复制图片失败: ${err.code}, ${err.message}`);
  });
}

4.2 粘贴不同类型的数据

// 粘贴时判断数据类型
async function 智能粘贴(): Promise<void> {
  let 系统剪贴板: pasteboard.SystemPasteboard =
    pasteboard.getSystemPasteboard();

  系统剪贴板.getData((err: BusinessError, data: pasteboard.PasteData) => {
    if (err) {
      console.error(`粘贴失败: ${err.code}, ${err.message}`);
      return;
    }

    let 数据类型: string = data.getPrimaryMimeType();

    if (数据类型 === pasteboard.MIMETYPE_TEXT_PLAIN) {
      // 处理文本
      let 文本内容: string = data.getPrimaryText();
      console.info("粘贴了文本: " + 文本内容);
    } else if (数据类型 === "image/jpeg") {
      // 处理图片
      console.info("粘贴了图片");
      // 这里可以获取图片数据并显示
    } else {
      // 处理其他类型
      console.info("粘贴了未知类型的数据: " + 数据类型);
    }
  });
}

🥦 跨设备剪贴板的"烹饪秘诀"

要做好跨设备剪贴板这道菜，有几个秘诀得记住：

5.1 数据类型要规范

就像菜要分类放，数据也要用标准的 MIME 类型定义：

文本：pasteboard.MIMETYPE_TEXT_PLAIN
图片：image/jpeg、image/png
其他：根据实际情况定义

5.2 错误处理要到位

就像炒菜可能会糊锅，剪贴板操作也可能会失败。一定要加上错误处理，给用户友好的提示！

5.3 异步操作要注意

剪贴板的操作都是异步的，要用async/await或者回调函数处理，不要直接同步调用～

5.4 兼容性要考虑

如果你的应用需要支持版本迁移，可以参考下面的代码：

import { AbilityConstant, UIAbility, Want } from "@kit.AbilityKit";
import { promptAction } from "@kit.ArkUI";

// 应用迁移时的兼容性处理
export default class EntryAbility extends UIAbility {
  onContinue(wantParam: Record<string, Object>) {
    // 获取迁移对端应用的版本号
    const 目标版本 = wantParam.version;

    // 应用可根据源端版本号设置支持接续的最小兼容版本号
    const 最小兼容版本: number = 0; // 替换为应用自己支持的版本号

    // 兼容性校验
    if (目标版本 < 最小兼容版本) {
      // 版本不兼容时提示用户
      promptAction.showToast({
        message: "目标端应用版本过低，不支持接续，请升级后再试",
        duration: 2000,
      });
      // 返回不匹配
      return AbilityConstant.OnContinueResult.MISMATCH;
    }

    console.info(`迁移版本 = ${目标版本}`);

    // 迁移数据保存
    const 要迁移的数据 = "西兰花食谱";
    if (要迁移的数据) {
      // 将要迁移的数据保存在wantParam中
      wantParam["数据"] = 要迁移的数据;
    }

    // 返回同意迁移
    return AbilityConstant.OnContinueResult.AGREE;
  }
}