前言

剪贴板是应用间数据传递的常用方式，如复制文本、分享链接等。@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 安装依赖

ohpm install @pura/harmony-utils

2.2 复制文本

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 粘贴文本

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

2.4 检查剪贴板

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

三、完整页面示例

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 一键复制组件

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 邀请码复制

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

五、注意事项

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

六、常见问题

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

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

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

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

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

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

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

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

总结

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

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