文章目录前言剪贴板 API 概览写入剪贴板读取剪贴板监听剪贴板变化注意事项实战一键复制邀请码写在最后前言复制粘贴听起来是个人都会的操作对吧但你真去写代码的时候就发现——读剪贴板要权限权限审核还特别严不用权限的方案又得用系统按钮样式改不了。我上周就被这个卡了一下午。剪贴板看似简单隐私合规这道坎够你喝一壶。今天把写入、读取、监听一条龙讲完顺带聊聊怎么在审核和体验之间找平衡。剪贴板 API 概览HarmonyOS 的剪贴板能力在kit.BasicServicesKit的pasteboard模块里核心 API 就这几个API作用是否需要权限createPlainTextData(text)创建纯文本数据对象否getSystemPasteboard()获取系统剪贴板实例否setData(data)写入剪贴板否getData()读取剪贴板需权限或 PasteButtonon(update, callback)监听剪贴板变化需权限hasData()判断剪贴板是否有数据否敲黑板写入不需要权限读取才敏感。这是所有合规方案的出发点。写入剪贴板写入是最简单的不需要任何权限直接调就行import{pasteboard}fromkit.BasicServicesKit;functioncopyToClipboard(text:string):void{letpasteboardDatapasteboard.createData(pasteboard.MIMETYPE_TEXT_PLAIN,text);letsystemPasteboardpasteboard.getSystemPasteboard();systemPasteboard.setData(pasteboardData);}关键代码讲解pasteboard.createData()第一个参数是 MIME 类型纯文本用MIMETYPE_TEXT_PLAINsetData()是异步方法写入成功后用户在任何地方长按都能粘贴如果要写入其他类型MIME 还有MIMETYPE_TEXT_HTML、MIMETYPE_URI等实际项目里通常要给个反馈告诉用户复制成功了。配合UIContext.getPromptAction()加个 Toastimport{pasteboard}fromkit.BasicServicesKit;EntryComponentstruct CopyDemo{privatetextContent:stringHM7INVITE2026;aboutToAppear():void{AppStorage.setOrCreate(context,this.getUIContext());}build(){Column(){Text(this.textContent).fontSize(20).padding(12).borderRadius(8).borderWidth(1).onClick(()this.copyText(this.textContent))}.width(100%).height(100%).justifyContent(FlexAlign.Center)}privatecopyText(text:string):void{letdatapasteboard.createData(pasteboard.MIMETYPE_TEXT_PLAIN,text);letpbpasteboard.getSystemPasteboard();pb.setData(data);letctx:UIContext|undefinedAppStorage.get(context);ctx?.getPromptAction().showToast({message:复制成功});}}AppStorage.setOrCreate(context, this.getUIContext())在aboutToAppear里存上下文后续拿它弹 ToastshowToast是轻量级提示1.5 秒自动消失不会打断用户操作读取剪贴板读取就敏感了。你有两条路方案一声明READ_PASTEBOARD权限——审核严要说明场景用户感知也强方案二用系统PasteButton——不需要权限系统自动弹授权提示强烈推荐方案二。除非你是剪贴板管理工具类 App否则别去申请读取权限。PasteButton方案的代码import{pasteboard}fromkit.BasicServicesKit;EntryComponentstruct PasteDemo{StatepastedText:string;build(){Column({space:20}){PasteButton().onClick(async(){letpbpasteboard.getSystemPasteboard();letdataawaitpb.getData();this.pastedTextdata.getPrimaryText()||;})Text(读取结果this.pastedText).fontSize(16)}.width(100%).height(100%).justifyContent(FlexAlign.Center)}}关键代码讲解PasteButton是系统组件用户点击后系统弹出授权弹窗用户同意后才读取getData()返回PasteData对象用getPrimaryText()取纯文本内容这套流程不需要在module.json5里声明任何权限审核零风险监听剪贴板变化有些场景需要实时监听剪贴板内容变化比如剪贴板管理工具。这个需要READ_PASTEBOARD权限import{pasteboard}fromkit.BasicServicesKit;letpbpasteboard.getSystemPasteboard();pb.on(update,(){pb.getData().then((data){lettextdata.getPrimaryText();console.info(剪贴板更新了text);});});on(update, callback)在剪贴板内容变化时触发回调里再调getData()拿最新内容别忘了在页面销毁时pb.off(update)取消监听避免内存泄漏血泪教训监听回调里别做耗时操作不然整个剪贴板操作会卡顿。注意事项搞剪贴板这几个坑必须知道权限问题读取剪贴板要READ_PASTEBOARD权限但审核会追问场景。能用PasteButton就别申请权限隐私合规别在onPageShow或后台自动读取剪贴板用户完全不知情的情况下偷读审核必拒大小限制单次写入数据不能超过 2MB图片类型的 PixelMap 也有尺寸限制生命周期剪贴板内容在设备重启后会清空别指望持久化主线程调用setData和getData都是异步方法记得用await或.then()处理结果实战一键复制邀请码把前面学的串起来做一个邀请码一键复制的完整组件import{pasteboard}fromkit.BasicServicesKit;EntryComponentstruct InviteCodePage{StateinviteCode:stringHM7VIP2026;Statecopied:booleanfalse;build(){Column({space:30}){Text(邀请好友得积分).fontSize(24).fontWeight(FontWeight.Bold)Row(){Text(this.inviteCode).fontSize(28).fontWeight(FontWeight.Medium).letterSpacing(4).fontColor(#333)Text(this.copied?已复制:复制).fontSize(14).fontColor(this.copied?#4CAF50:#2196F3).padding({left:12,right:12,top:6,bottom:6}).borderRadius(4).backgroundColor(this.copied?#E8F5E9:#E3F2FD).onClick(()this.copyCode())}.padding(20).borderRadius(12).backgroundColor(#F5F5F5).width(80%).justifyContent(FlexAlign.SpaceBetween)Text(将邀请码分享给好友好友注册后双方各得 100 积分).fontSize(14).fontColor(#999).width(80%)}.width(100%).height(100%).justifyContent(FlexAlign.Center)}privatecopyCode():void{letdatapasteboard.createData(pasteboard.MIMETYPE_TEXT_PLAIN,this.inviteCode);pasteboard.getSystemPasteboard().setData(data);this.copiedtrue;setTimeout((){this.copiedfalse;},2000);}}实现逻辑点击复制按钮调用setData把邀请码写入剪贴板copied状态控制按钮文字和颜色变化给用户即时反馈2 秒后状态自动恢复避免用户误以为还在剪贴板里实际上剪贴板内容还在只是视觉状态恢复写在最后剪贴板操作的代码量不大但隐私合规比技术实现更值得花心思。我的原则就一条写入随便写读取必须用户主动触发。PasteButton方案虽然样式不可定制但省了权限申请的麻烦审核也更容易过。如果你非要自己画 UI 去读剪贴板那就老老实实申请权限、老老实实说明场景别想着偷摸读。
文章目录前言剪贴板 API 概览写入剪贴板读取剪贴板监听剪贴板变化注意事项实战一键复制邀请码写在最后前言复制粘贴听起来是个人都会的操作对吧但你真去写代码的时候就发现——读剪贴板要权限权限审核还特别严不用权限的方案又得用系统按钮样式改不了。我上周就被这个卡了一下午。剪贴板看似简单隐私合规这道坎够你喝一壶。今天把写入、读取、监听一条龙讲完顺带聊聊怎么在审核和体验之间找平衡。剪贴板 API 概览HarmonyOS 的剪贴板能力在kit.BasicServicesKit的pasteboard模块里核心 API 就这几个API作用是否需要权限createPlainTextData(text)创建纯文本数据对象否getSystemPasteboard()获取系统剪贴板实例否setData(data)写入剪贴板否getData()读取剪贴板需权限或 PasteButtonon(update, callback)监听剪贴板变化需权限hasData()判断剪贴板是否有数据否敲黑板写入不需要权限读取才敏感。这是所有合规方案的出发点。写入剪贴板写入是最简单的不需要任何权限直接调就行import{pasteboard}fromkit.BasicServicesKit;functioncopyToClipboard(text:string):void{letpasteboardDatapasteboard.createData(pasteboard.MIMETYPE_TEXT_PLAIN,text);letsystemPasteboardpasteboard.getSystemPasteboard();systemPasteboard.setData(pasteboardData);}关键代码讲解pasteboard.createData()第一个参数是 MIME 类型纯文本用MIMETYPE_TEXT_PLAINsetData()是异步方法写入成功后用户在任何地方长按都能粘贴如果要写入其他类型MIME 还有MIMETYPE_TEXT_HTML、MIMETYPE_URI等实际项目里通常要给个反馈告诉用户复制成功了。配合UIContext.getPromptAction()加个 Toastimport{pasteboard}fromkit.BasicServicesKit;EntryComponentstruct CopyDemo{privatetextContent:stringHM7INVITE2026;aboutToAppear():void{AppStorage.setOrCreate(context,this.getUIContext());}build(){Column(){Text(this.textContent).fontSize(20).padding(12).borderRadius(8).borderWidth(1).onClick(()this.copyText(this.textContent))}.width(100%).height(100%).justifyContent(FlexAlign.Center)}privatecopyText(text:string):void{letdatapasteboard.createData(pasteboard.MIMETYPE_TEXT_PLAIN,text);letpbpasteboard.getSystemPasteboard();pb.setData(data);letctx:UIContext|undefinedAppStorage.get(context);ctx?.getPromptAction().showToast({message:复制成功});}}AppStorage.setOrCreate(context, this.getUIContext())在aboutToAppear里存上下文后续拿它弹 ToastshowToast是轻量级提示1.5 秒自动消失不会打断用户操作读取剪贴板读取就敏感了。你有两条路方案一声明READ_PASTEBOARD权限——审核严要说明场景用户感知也强方案二用系统PasteButton——不需要权限系统自动弹授权提示强烈推荐方案二。除非你是剪贴板管理工具类 App否则别去申请读取权限。PasteButton方案的代码import{pasteboard}fromkit.BasicServicesKit;EntryComponentstruct PasteDemo{StatepastedText:string;build(){Column({space:20}){PasteButton().onClick(async(){letpbpasteboard.getSystemPasteboard();letdataawaitpb.getData();this.pastedTextdata.getPrimaryText()||;})Text(读取结果this.pastedText).fontSize(16)}.width(100%).height(100%).justifyContent(FlexAlign.Center)}}关键代码讲解PasteButton是系统组件用户点击后系统弹出授权弹窗用户同意后才读取getData()返回PasteData对象用getPrimaryText()取纯文本内容这套流程不需要在module.json5里声明任何权限审核零风险监听剪贴板变化有些场景需要实时监听剪贴板内容变化比如剪贴板管理工具。这个需要READ_PASTEBOARD权限import{pasteboard}fromkit.BasicServicesKit;letpbpasteboard.getSystemPasteboard();pb.on(update,(){pb.getData().then((data){lettextdata.getPrimaryText();console.info(剪贴板更新了text);});});on(update, callback)在剪贴板内容变化时触发回调里再调getData()拿最新内容别忘了在页面销毁时pb.off(update)取消监听避免内存泄漏血泪教训监听回调里别做耗时操作不然整个剪贴板操作会卡顿。注意事项搞剪贴板这几个坑必须知道权限问题读取剪贴板要READ_PASTEBOARD权限但审核会追问场景。能用PasteButton就别申请权限隐私合规别在onPageShow或后台自动读取剪贴板用户完全不知情的情况下偷读审核必拒大小限制单次写入数据不能超过 2MB图片类型的 PixelMap 也有尺寸限制生命周期剪贴板内容在设备重启后会清空别指望持久化主线程调用setData和getData都是异步方法记得用await或.then()处理结果实战一键复制邀请码把前面学的串起来做一个邀请码一键复制的完整组件import{pasteboard}fromkit.BasicServicesKit;EntryComponentstruct InviteCodePage{StateinviteCode:stringHM7VIP2026;Statecopied:booleanfalse;build(){Column({space:30}){Text(邀请好友得积分).fontSize(24).fontWeight(FontWeight.Bold)Row(){Text(this.inviteCode).fontSize(28).fontWeight(FontWeight.Medium).letterSpacing(4).fontColor(#333)Text(this.copied?已复制:复制).fontSize(14).fontColor(this.copied?#4CAF50:#2196F3).padding({left:12,right:12,top:6,bottom:6}).borderRadius(4).backgroundColor(this.copied?#E8F5E9:#E3F2FD).onClick(()this.copyCode())}.padding(20).borderRadius(12).backgroundColor(#F5F5F5).width(80%).justifyContent(FlexAlign.SpaceBetween)Text(将邀请码分享给好友好友注册后双方各得 100 积分).fontSize(14).fontColor(#999).width(80%)}.width(100%).height(100%).justifyContent(FlexAlign.Center)}privatecopyCode():void{letdatapasteboard.createData(pasteboard.MIMETYPE_TEXT_PLAIN,this.inviteCode);pasteboard.getSystemPasteboard().setData(data);this.copiedtrue;setTimeout((){this.copiedfalse;},2000);}}实现逻辑点击复制按钮调用setData把邀请码写入剪贴板copied状态控制按钮文字和颜色变化给用户即时反馈2 秒后状态自动恢复避免用户误以为还在剪贴板里实际上剪贴板内容还在只是视觉状态恢复写在最后剪贴板操作的代码量不大但隐私合规比技术实现更值得花心思。我的原则就一条写入随便写读取必须用户主动触发。PasteButton方案虽然样式不可定制但省了权限申请的麻烦审核也更容易过。如果你非要自己画 UI 去读剪贴板那就老老实实申请权限、老老实实说明场景别想着偷摸读。
