鸿蒙三方库 | harmony-utils之PasteboardUtil剪贴板数据读写详解

前言

剪贴板是应用间数据传递的常用方式，如复制文本、分享链接等。@pura/harmony-utils 的 PasteboardUtil 封装了剪贴板读写方法，简化了剪贴板操作。本文将从API说明、代码实战、进阶用法、常见问题等多个维度进行全面讲解，帮助开发者快速掌握并应用到实际项目中。

一、PasteboardUtil核心API

PasteboardUtil 提供了以下剪贴板操作方法：

方法	说明	返回类型	使用场景
`setText(text)`	复制文本到剪贴板	void	复制功能
`getText()`	从剪贴板读取文本	string	粘贴功能
`hasText()`	剪贴板是否有文本	boolean	状态检测
`clear()`	清空剪贴板	void	隐私保护

1.1 核心特性

简洁易用：封装复杂API为一行调用，降低使用门槛
类型安全：完整的TypeScript类型定义，编译期即可发现错误
异常处理：内置异常捕获机制，避免运行时崩溃
状态检测：支持检测剪贴板是否有内容

1.2 剪贴板操作对照

操作	方法	说明	触发方式
复制	setText	写入剪贴板	用户点击
粘贴	getText	读取剪贴板	用户点击
检测	hasText	检查内容	自动检测
清空	clear	清除内容	主动清理

二、完整使用步骤

2.1 安装依赖

bash 复制代码

ohpm install @pura/harmony-utils

2.2 复制文本

typescript 复制代码

import { PasteboardUtil } from '@pura/harmony-utils';

Button('复制文本')
  .width('100%')
  .onClick(() => {
    try {
      PasteboardUtil.setText('Hello harmony-utils!');
      this.result = '文本已复制到剪贴板 📋';
    } catch (e) {
      this.result = '异常: ' + e;
    }
  })

2.3 粘贴文本

typescript 复制代码

Button('粘贴文本')
  .width('100%')
  .onClick(async () => {
    try {
      let text = await PasteboardUtil.getText();
      this.result = `剪贴板内容:\n${text || '（空）'}`;
    } catch (e) {
      this.result = '异常: ' + e;
    }
  })

2.4 检查剪贴板

typescript 复制代码

Button('检查剪贴板')
  .width('100%')
  .onClick(() => {
    try {
      let has = PasteboardUtil.hasText();
      this.result = `剪贴板: ${has ? '有内容 ✅' : '为空 ❌'}`;
    } catch (e) {
      this.result = '异常: ' + e;
    }
  })

三、完整页面示例

typescript 复制代码

import { PasteboardUtil, ToastUtil } from '@pura/harmony-utils';

@Entry
@Component
struct PasteboardDemo {
  @State result: string = '';
  @State inputText: string = '';

  build() {
    Column({ space: 12 }) {
      TextInput({ text: this.inputText }).onChange(v => this.inputText = v)
      Button('复制').width('100%').onClick(() => {
        PasteboardUtil.setText(this.inputText);
        ToastUtil.show('已复制');
      });
      Button('粘贴').width('100%').onClick(async () => {
        let text = await PasteboardUtil.getText();
        this.result = text || '剪贴板为空';
      });
      Text(this.result).fontSize(14).fontColor('#333333')
    }
    .padding(16)
  }
}

四、进阶用法

4.1 一键复制组件

typescript 复制代码

import { PasteboardUtil, ToastUtil } from '@pura/harmony-utils';

@Component
struct CopyableText {
  @Prop text: string = '';

  build() {
    Row() {
      Text(this.text).layoutWeight(1)
      Text('复制').fontColor('#007DFF').onClick(() => {
        PasteboardUtil.setText(this.text);
        ToastUtil.show('已复制');
      })
    }
  }
}

4.2 邀请码复制

typescript 复制代码

function copyInviteCode(code: string): void {
  PasteboardUtil.setText(code);
  ToastUtil.showLong('邀请码已复制，快去分享吧！');
}

五、注意事项

隐私安全：剪贴板内容其他应用也可读取
异步读取：getText为异步方法，需使用await
内容限制：剪贴板内容有大小限制
初始化依赖 ：使用前需确保 AppUtil.init() 已调用
清空时机：敏感信息使用后建议清空剪贴板

六、常见问题

Q1: getText()读取不到内容？

可能是其他应用未写入文本，或剪贴板已被清空。

Q2: 复制后其他应用粘贴不到？

检查是否成功写入，部分系统对跨应用剪贴板有限制。

Q3: 如何复制图片到剪贴板？

当前PasteboardUtil主要支持文本，图片复制需要使用系统剪贴板API。

Q4: 剪贴板内容会自动清除吗？

系统可能定期清除剪贴板内容，建议及时使用。

总结

PasteboardUtil 的剪贴板操作方法为应用间数据传递提供了便捷支持。本文详细介绍了核心API、使用步骤、完整示例、进阶用法以及常见问题的解决方案。开发者可以利用剪贴板实现复制粘贴、分享链接等功能。

本文基于 @pura/harmony-utils 工具库，更多功能请参考官方文档与后续系列文章。