复制粘贴看着简单，不就是往剪贴板塞点文本吗？等到产品说"复制一段文字到另一个应用自动识别"“复制图片要能粘贴”“跨设备同步剪贴板”，你才发现坑不少——权限管控、数据类型适配、跨应用数据共享方案选择，每个都能卡半天。这篇把剪贴板读写、跨应用数据共享、组件间数据传递的完整方案讲清楚。
剪贴板基础读写
HarmonyOS 的剪贴板通过pasteboard模块访问，它来自@kit.BasicServicesKit——注意不是@kit.ArkData。核心 API 就三个：getSystemPasteboard()获取实例，setData()写入，getData()读取。
import{pasteboard}from'@kit.BasicServicesKit';import{BusinessError}from'@kit.BasicServicesKit';asynccopyToClipboard(text:string):Promise<void>{constsystemPasteboard:pasteboard.SystemPasteboard=pasteboard.getSystemPasteboard();constpasteData:pasteboard.PasteData=pasteboard.createData(pasteboard.MIMETYPE_TEXT_PLAIN,text);try{awaitsystemPasteboard.setData(pasteData);console.info('复制成功');}catch(e){consterr=easBusinessError;console.error(`复制失败:${err.code}-${err.message}`);}}asyncpasteFromClipboard():Promise<string>{constsystemPasteboard:pasteboard.SystemPasteboard=pasteboard.getSystemPasteboard();try{constpasteData:pasteboard.PasteData=awaitsystemPasteboard.getData();if(pasteData.getRecordCount()>0){constrecord:pasteboard.PasteDataRecord=pasteData.getRecord(0);returnrecord.toPlainText();}return'';}catch(e){consterr=easBusinessError;console.error(`粘贴失败:${err.code}`);return'';}}createData是工厂方法，第一个参数指定 MIME 类型，第二个是内容。写入后系统剪贴板立刻生效，其他应用可以读取。读取时getData()返回完整的PasteData对象，用getRecord(0)取第一条记录。
注意：API 12 起，读取剪贴板需要ohos.permission.READ_PASTEBOARD权限，或者使用安全控件（PasteButton）获取临时授权。不申请权限直接getData()会报错。
还有一个容易忽略的点：setData是覆盖式写入——每次调用都会把剪贴板之前的内容全部替换掉。如果你想往剪贴板"追加"内容，必须先getData读出来，往 PasteData 里 addRecord，再setData写回去。否则前一次复制的数据就丢了。
多类型数据读写
剪贴板不只支持纯文本。它支持 HTML 富文本、URI、Want、PixelMap 等多种类型。一条 PasteData 可以包含多个 Record，每个 Record 还可以用addEntry添加不同格式的副本。
interfaceRichCopyParams{plainText:string;htmlText:string;}asynccopyRichText(params:RichCopyParams):Promise<void>{constsystemPasteboard=pasteboard.getSystemPasteboard();// 创建纯文本类型，再追加 HTML 格式constpasteData:pasteboard.PasteData=pasteboard.createData(pasteboard.MIMETYPE_TEXT_PLAIN,params.plainText);constrecord:pasteboard.PasteDataRecord=pasteData.getRecord(0);// 同一条记录添加 HTML 副本，粘贴方按需选择格式record.addEntry(pasteboard.MIMETYPE_TEXT_HTML,params.htmlText);awaitsystemPasteboard.setData(pasteData);}asyncpasteAsHtml():Promise<string>{constsystemPasteboard=pasteboard.getSystemPasteboard();constpasteData:pasteboard.PasteData=awaitsystemPasteboard.getData();constrecord:pasteboard.PasteDataRecord=pasteData.getRecord(0);// 尝试获取 HTML 格式，没有则回退纯文本consthtml:string=record.toHtmlText();if(html.length>0){returnhtml;}returnrecord.toPlainText();}addEntry的核心价值是"一条数据多种格式"——纯文本给简单应用用，HTML 给富文本编辑器用，URI 给文件管理器用。粘贴方按自己能力选择最合适的格式读取，这就是跨应用兼容的基础。
关键区别：addEntry是往同一条 Record 加不同格式的数据；而addRecord是加一条全新的 Record（比如多文件复制时每个文件一个 Record）。两者用途不同，别混用。
多类型数据的典型场景是富文本编辑器：用户选中一段图文混排的内容复制，你需要同时存纯文本（给记事本粘贴）、HTML（给浏览器粘贴）、PixelMap（给图片编辑器粘贴）。粘贴方根据自己的能力选择最合适的格式读取，这样无论粘贴到哪个 App 都能保持最佳效果。
URI 类型与文件共享
复制文件不是把整个文件塞进剪贴板，而是复制文件的 URI。粘贴方拿到 URI 后，通过fileIo读取或拷贝文件内容。这是跨应用共享文件的正确方式。
import{fileIoasfs}from'@kit.CoreFileKit';asynccopyFileUri(fileUri:string):Promise<void>{constsystemPasteboard=pasteboard.getSystemPasteboard();constpasteData:pasteboard.PasteData=pasteboard.createData(pasteboard.MIMETYPE_TEXT_URI,fileUri);awaitsystemPasteboard.setData(pasteData);}asyncpasteFileUri():Promise<string>{constsystemPasteboard=pasteboard.getSystemPasteboard();constpasteData:pasteboard.PasteData=awaitsystemPasteboard.getData();constrecord:pasteboard.PasteDataRecord=pasteData.getRecord(0);consturi:string=record.toUri();// 用 fileIo 拷贝文件到自己的沙箱constcontext=getContext(this);constdestPath=`${context.filesDir}/pasted_file.dat`;fs.copySync(uri,destPath);returndestPath;}URI 类型的好处是零拷贝——不需要把文件内容序列化到剪贴板（128MB 上限也扛不住大文件），只传一个引用，粘贴方按需读取。
注意：URI 指向的文件可能受原应用的权限控制。如果原应用设置了shareMode限制，粘贴方可能读不到。建议用系统文件管理器或 Photo Picker 选择的文件 URI，权限最宽松。
还有一点：剪贴板的数据总大小上限是 128MB。纯文本和 URI 类型不可能触顶，但如果你往剪贴板塞大图片的 PixelMap，就要注意这个上限。超过限制setData会直接报错，不会截断。
剪贴板变化监听
有些场景需要在剪贴板内容变化时自动响应——比如电商 App 检测用户复制了口令码，自动弹窗提示跳转。这就需要监听剪贴板变化事件。
privateonClipboardChange=():void=>{this.checkClipboardForCode();};asyncstartClipboardListener():Promise<void>{constsystemPasteboard=pasteboard.getSystemPasteboard();systemPasteboard.on('update',this.onClipboardChange);}asyncstopClipboardListener():Promise<void>{constsystemPasteboard=pasteboard.getSystemPasteboard();systemPasteboard.off('update',this.onClipboardChange);}asynccheckClipboardForCode():Promise<void>{constsystemPasteboard=pasteboard.getSystemPasteboard();// 先检查是否包含文本数据，避免无谓读取consthasText:boolean=systemPasteboard.hasDataType(pasteboard.MIMETYPE_TEXT_PLAIN);if(!hasText){return;}constpasteData:pasteboard.PasteData=awaitsystemPasteboard.getData();constrecord:pasteboard.PasteDataRecord=pasteData.getRecord(0);consttext:string=record.toPlainText();// 检测口令码格式if(text.startsWith('￥')&&text.length>=8){console.info('检测到口令码，弹窗提示跳转');}}on('update')在剪贴板内容被任何应用修改时触发。先hasDataType检查是否有感兴趣的数据类型，避免每次都getData触发权限弹窗。
注意：监听回调里调getData()同样需要 READ_PASTEBOARD 权限。没有权限的 App 只能知道"剪贴板变了"，但读不到内容。另外在aboutToDisappear里必须off掉监听，否则会内存泄漏。
跨应用数据共享：DataShare
剪贴板适合一次性复制粘贴，但如果两个应用需要持续共享结构化数据（比如配置中心 App 给业务 App 推送开关），就要用 DataShare。DataShare 是 HarmonyOS 的跨应用数据共享机制，支持发布-订阅模式。
import{dataShare}from'@kit.ArkData';interfaceSharedConfig{uri:string;value:string;allowList:Array<string>;}asyncpublishSharedConfig(config:SharedConfig):Promise<void>{consthandle:dataShare.DataProxyHandle=awaitdataShare.createDataProxyHandle();constproxyData:dataShare.ProxyData={uri:config.uri,value:config.value,allowList:config.allowList,};awaithandle.publish(proxyData);console.info(`配置发布成功:${config.uri}`);}asyncreadSharedConfig(uri:string):Promise<string>{consthandle:dataShare.DataProxyHandle=awaitdataShare.createDataProxyHandle();constproxyData:dataShare.ProxyData=awaithandle.get(uri);returnproxyData.value;}DataShare 的 URI 格式是datashareproxy://{bundleName}/{path}，allowList控制哪些 App 可以读取。发布方统一管理配置，访问方只读——这是比剪贴板更适合"持久共享"的方案。
关键区别：DataShare 是"发布-订阅"模式，数据长期有效直到发布方删除；剪贴板是"复制-粘贴"模式，数据会被下一次复制覆盖。按场景选择。
DataShare 还支持变更监听——访问方可以订阅某个 URI 的数据变化，发布方修改后自动通知。这对配置类场景特别有用：配置中心改了个开关，业务 App 立刻收到通知刷新 UI，不需要轮询。
AppStorage 跨组件数据传递
回到应用内部，组件之间共享数据最轻量的方案是AppStorage。它是一个全局的 KV 存储，任何组件都可以通过@StorageLink或@StorageProp读写同一个 key。
interfaceClipboardState{lastCopiedText:string;copyCount:number;}// 在 Entry 页面初始化@Entry@Componentstruct ClipboardDemoPage{@StorageLink('lastCopiedText')lastCopiedText:string='';@StorageLink('copyCount')copyCount:number=0;asynconCopy():Promise<void>{constsystemPasteboard=pasteboard.getSystemPasteboard();constpasteData=pasteboard.createData(pasteboard.MIMETYPE_TEXT_PLAIN,'示例文本');awaitsystemPasteboard.setData(pasteData);// 通过 AppStorage 同步到其他组件this.lastCopiedText='示例文本';this.copyCount++;}build(){Column({space:16}){Text(`最近复制:${this.lastCopiedText}`)Text(`复制次数:${this.copyCount}`)Button('复制文本').onClick(()=>{this.onCopy();})}}}@StorageLink是双向绑定——组件修改会同步到 AppStorage，AppStorage 变化也会同步回组件。@StorageProp是单向的，只从 AppStorage 读，组件内修改不会回写。
注意：AppStorage是进程级单例，只在当前应用内有效，不能跨应用。跨应用要用 DataShare 或剪贴板。
分布式数据同步概览
HarmonyOS 还有一个更上层的能力——分布式数据同步。同一账号下的多台设备（手机、平板、手表）可以自动同步数据，不需要你写网络传输逻辑。核心是distributedData模块。
import{distributedData}from'@kit.ArkData';interfaceSyncConfig{storeId:string;key:string;value:string;}asynccreateDistributedStore(config:SyncConfig):Promise<void>{constoptions:distributedData.Options={createIfMissing:true,autoSync:true,securityLevel:distributedData.SecurityLevel.S1,};conststore:distributedData.KVStore=awaitdistributedData.createKVStore(config.storeId,options);awaitstore.put(config.key,config.value);// 数据会自动同步到同账号的其他设备}分布式同步的底层是系统自动完成的——你在 A 设备 put 一个 key-value，B 设备的 KVStore 会自动收到更新事件。适合配置同步、草稿同步这类轻量数据。
关键区别：分布式数据同步需要设备在同一账号下且网络互通；DataShare 是同设备跨应用；剪贴板可以跨设备（跨设备剪贴板）也可以跨应用。三者的适用范围不同。
分布式数据同步最适合的场景是"轻量配置同步"，比如用户的主题设置、字体大小、输入习惯等。这些数据量小、变更频率低，用 KVStore + autoSync 就能自动搞定。但要注意，分布式同步不是实时的——网络延迟、设备休眠都可能导致同步有几秒到几十秒的延迟，不要依赖它做实时性要求高的场景。
完整剪贴板演示页面
把剪贴板读写、变化监听、AppStorage 同步组合成一个演示页面。
@Entry@Componentstruct ClipboardSharePage{@StateinputText:string='';@StatepastedText:string='';@StatecopyCount:number=0;@StorageLink('globalClipText')globalClipText:string='';aboutToAppear():void{this.startClipboardListener();}aboutToDisappear():void{this.stopClipboardListener();}asyncstartClipboardListener():Promise<void>{constsystemPasteboard=pasteboard.getSystemPasteboard();systemPasteboard.on('update',():void=>{this.onClipboardUpdated();});}asyncstopClipboardListener():Promise<void>{constsystemPasteboard=pasteboard.getSystemPasteboard();systemPasteboard.off('update');}asynconClipboardUpdated():Promise<void>{constsystemPasteboard=pasteboard.getSystemPasteboard();consthasText=systemPasteboard.hasDataType(pasteboard.MIMETYPE_TEXT_PLAIN);if(!hasText){return;}constpasteData:pasteboard.PasteData=awaitsystemPasteboard.getData();if(pasteData.getRecordCount()>0){consttext:string=pasteData.getRecord(0).toPlainText();this.pastedText=text;this.globalClipText=text;}}asyncdoCopy():Promise<void>{if(this.inputText.length===0){return;}constsystemPasteboard=pasteboard.getSystemPasteboard();constpasteData=pasteboard.createData(pasteboard.MIMETYPE_TEXT_PLAIN,this.inputText);awaitsystemPasteboard.setData(pasteData);this.copyCount++;this.globalClipText=this.inputText;}asyncdoPaste():Promise<void>{constsystemPasteboard=pasteboard.getSystemPasteboard();constpasteData:pasteboard.PasteData=awaitsystemPasteboard.getData();if(pasteData.getRecordCount()>0){this.pastedText=pasteData.getRecord(0).toPlainText();}}build(){Column({space:16}){Text('剪贴板与数据共享').fontSize(24).fontWeight(FontWeight.Bold)TextInput({placeholder:'输入要复制的文本',text:this.inputText}).width('90%').onChange((value:string)=>{this.inputText=value;})Row({space:12}){Button('复制').onClick(()=>{this.doCopy();})Button('粘贴').onClick(()=>{this.doPaste();})}Text(`粘贴内容:${this.pastedText}`).fontSize(16)Text(`复制次数:${this.copyCount}`).fontSize(16)Text(`全局同步文本:${this.globalClipText}`).fontSize(14).fontColor('#888888')}.width('100%').height('100%').padding(20)}}这个页面覆盖了文本复制粘贴、剪贴板变化监听、AppStorage 跨组件同步三个核心能力。监听回调里用hasDataType先判断类型再读取，既节省权限开销又避免无谓 IO。
踩坑清单
| 问题 | 原因 | 解决 |
|---|---|---|
| getData 报权限错误 | API 12 需 READ_PASTEBOARD | 申请权限或用 PasteButton 安全控件 |
| 剪贴板监听不触发 | 未注册 on(‘update’) | aboutToAppear 注册，aboutToDisappear 注销 |
| 复制图片粘贴出来是文本 | 读取方式不对 | 检查 MIMETYPE 用 toPixelMap 而非 toPlainText |
| addEntry 和 addRecord 混淆 | 两者含义不同 | addEntry 同一记录加格式，addRecord 加新记录 |
| 连续 setData 数据丢失 | 剪贴板同一时间只支持一次写入 | 串行 await，不要并发写入 |
| AppStorage 修改不刷新 UI | 用了 @StorageProp 而非 @StorageLink | 需要双向绑定用 @StorageLink |
| DataShare get 返回空 | allowList 未包含当前应用 | 发布时 allowList 加入目标 bundleName |
| URI 类型粘贴报文件不存在 | 原应用已关闭文件描述符 | 及时拷贝到自身沙箱，不要延迟读取 |
| 分布式同步不生效 | 设备不在同一账号或网络不通 | 确认同账号且同一 WiFi |
| PasteButton 样式不定制 | 安全控件样式受限 | 接受系统样式或改用权限申请方式 |
