前言ShareKit是 HarmonyOS 的分享服务能力支持应用间分享文本、图片、文件等数据。在「猫猫大作战」中玩家完成一局游戏后可以分享战绩到微信、微博等社交平台吸引更多朋友来挑战。本文以「猫猫大作战」的战绩分享功能为锚点讲解 systemShare 的完整使用方法包括文本分享、图片分享、UniformDataObject 数据封装、以及分享后的回调处理。提示本系列不讲 ArkTS 基础语法与环境搭建。本篇是阶段五第 154 篇。一、systemShare 基础用法1.1 分享文本import{systemShare}fromkit.ShareKit;import{uniformDataStruct}fromkit.ArkData;asyncfunctionshareText(score:number,playerName:string):Promisevoid{constsharedData:uniformDataStruct.UniformDataObject{value:{text:我在「猫猫大作战」中获得了${score}分快来挑战我吧,html:h3猫猫大作战/h3p得分: b${score}/b/pp玩家:${playerName}/p,},type:general.text,};awaitsystemShare.share(sharedData);}1.2 参数说明参数类型说明示例value.textstring纯文本内容“我在猫猫大作战中获得了 2450 分”value.htmlstringHTML 富文本可选b2450/b 分typestring统一类型标识符 (UTD)general.text、general.image提示type字段是 UTDUniform Type Descriptor告诉系统分享数据的类型。常用类型general.text文本、general.image图片、general.file文件。二、 UniformDataObject 数据封装2.1 数据封装方法import{uniformDataStruct}fromkit.ArkData;// 文本分享consttextData:uniformDataStruct.UniformDataObject{value:{text:分享内容,html:b富文本/b},type:general.text,};// 图片分享constimageData:uniformDataStruct.UniformDataObject{value:{image:pixelMap},type:general.image,};// 文件分享constfileData:uniformDataStruct.UniformDataObject{value:{fileUri:file://{sandboxPath}/score.png},type:general.file,};2.2 数据类型的 UTD 对照分享类型UTD 标识value 格式目标应用纯文本general.text{ text: string }微信、短信富文本general.text{ text, html }微信、QQ图片general.image{ image: PixelMap }微博、朋友圈文件general.file{ fileUri: string }文件管理器链接general.url{ url: string }浏览器三、游戏中分享战绩的完整实现3.1 战绩分享按钮// 游戏结束界面的分享按钮BuilderShareButton(score:number,playerName:string){Button({icon:$r(app.media.ic_share),text:分享战绩}).width(80%).height(48).fontSize(17).fontColor(#FFFFFF).backgroundColor(#45B7D1).borderRadius(24).onClick(async(){try{awaitshareGameResult(score,playerName);promptAction.showToast({message:分享成功});}catch(err){console.error(分享失败:${err.message});promptAction.showToast({message:分享取消或失败});}})}3.2 构造分享内容asyncfunctionshareGameResult(score:number,playerName:string):Promisevoid{// 构造分享文本constscoreTextscore.toLocaleString(zh-CN);constshareContentformatShareText(score,playerName);constsharedData:uniformDataStruct.UniformDataObject{value:{text:shareContent.text,html:shareContent.html,},type:general.text,};awaitsystemShare.share(sharedData);}functionformatShareText(score:number,playerName:string){constscoreTextscore.toLocaleString(zh-CN);return{text: 我在「猫猫大作战」中获得${scoreText}分来挑战我的记录吧下载地址: https://appgallery.huawei.com/cat-battle-war,html:div styletext-align:center;padding:20px; h2 猫猫大作战/h2 p stylefont-size:24px;color:#E74C3C; b${scoreText}/b 分 /p p玩家:${playerName}/p p stylefont-size:14px;color:#95A5A6; 来挑战我的记录吧 /p /div,};}3.3 分享回调处理// systemShare.share() 返回的 Promise// resolve 用户选择了分享目标// reject 用户取消或分享失败try{constresultawaitsystemShare.share(sharedData);// 分享成功用户选择了目标应用console.info(分享成功,JSON.stringify(result));// 可以在这里触发分享成功统计analytics.recordEvent(share_success,{score});}catch(err){// 用户取消或在目标应用分享失败console.info(分享取消:${err.message});// 不视为错误只记录取消analytics.recordEvent(share_cancel);}四、分享图片截图4.1 截取游戏画面import{image}fromkit.ImageKit;asyncfunctioncaptureAndShare():Promisevoid{// 1. 获取当前 UI 的 PixelMap截图constuiContextthis.getUIContext();constpixelMapawaituiContext.createPixelMap({width:360,height:640,});// 2. 编码为 JPEGconstpackerimage.createImagePacker();constbufferawaitpacker.packing(pixelMap,{format:image/jpeg,quality:85,});packer.release();// 3. 保存到临时文件constcontextgetContext()ascommon.UIAbilityContext;consttempPath${context.tempDir}/share_score.jpg;constfilefileIo.openSync(tempPath,fileIo.OpenMode.CREATE|fileIo.OpenMode.WRITE_ONLY|fileIo.OpenMode.TRUNC);fileIo.writeSync(file.fd,buffer);fileIo.closeSync(file);// 4. 分享图片文件constsharedData:uniformDataStruct.UniformDataObject{value:{fileUri:file://${tempPath}},type:general.file,};awaitsystemShare.share(sharedData);}4.2 图片规图片类型建议尺寸格式质量文件大小战绩分享截图360×640JPEG85%~100KB邀请横幅720×360PNG-~200KB角色卡片240×240PNG-~50KB提示分享图片文件大小建议不超过 1MB。过大的图片在社交平台加载慢可能被压缩。五、文件分享战绩数据导出asyncfunctionshareGameData(playerName:string,records:GameRecord[]):Promisevoid{// 1. 序列化战绩数据为 JSONconstdataJSON.stringify({playerName,exportDate:newDate().toISOString(),records,},null,2);// 2. 写入临时文件constcontextgetContext()ascommon.UIAbilityContext;constfilePath${context.tempDir}/game_data_${Date.now()}.json;constfilefileIo.openSync(filePath,fileIo.OpenMode.CREATE|fileIo.OpenMode.WRITE_ONLY|fileIo.OpenMode.TRUNC);fileIo.writeSync(file.fd,data);fileIo.closeSync(file);// 3. 分享文件constsharedData:uniformDataStruct.UniformDataObject{value:{fileUri:file://${filePath}},type:general.file,};awaitsystemShare.share(sharedData);}六、ShareKit vs 原生分享方案维度systemShare原生 systemShare自定义分享面板集成复杂度简单3 行代码中等复杂目标应用系统所有支持的应用系统所有手动指定UI 一致性系统原生界面系统原生需自定义支持数据类型文本/图片/文件文本/URI任意推荐场景通用分享通用分享品牌定制分享七、分享最佳实践7.1 分享内容策略引人注目的开头用 Emoji 吸引注意具体数字得分要精确2450 分 比很高分更吸引人行动号召“来挑战我吧” 引导好友下载下载链接附带应用市场下载地址个性化包含玩家名称让好友知道是谁在邀请7.2 性能考虑// ✅ 分享操作应在用户点击后异步执行避免阻塞 UIButton(分享).onClick(async(){// show loadingthis.isSharingtrue;try{awaitshareGameResult(this.score,this.playerName);}finally{this.isSharingfalse;}})// ✅ 大图片分享前压缩asyncfunctioncompressForShare(pixelMap:PixelMap):PromiseArrayBuffer{constpackerimage.createImagePacker();constbufferawaitpacker.packing(pixelMap,{format:image/jpeg,quality:75,// 适当降低质量减小文件});packer.release();returnbuffer;}八、错误排查问题可能原因解决方法分享界面未弹出数据格式错误检查 UniformDataObject 结构分享后无响应UTD 类型不匹配确保 type 与实际 value 匹配图片分享失败文件路径不存在检查 file:// 路径和文件权限内容为空value.text 未设确保 text 字段有内容九、权限与合规// 分享不需要额外权限// 但如果要分享图片需要读取临时文件的权限// 临时文件在 tempDir 中应用自有权限可直接读写// 隐私提示分享内容中包含玩家名称需在隐私政策中说明constsharePrivacyNotice分享功能会包含您的游戏昵称和得分信息。 这些信息仅用于本次分享不会被我们收集。;十、多语言分享functionformatShareByLocale(score:number,locale:string){constscoreTextscore.toLocaleString(localezh?zh-CN:en-US);consttemplates:Recordstring,{text:string;html:string}{zh:{text: 我在「猫猫大作战」中获得${scoreText}分,html:b${scoreText}/b 分,},en:{text: I scored${scoreText}in Cat Battle!,html:Score: b${scoreText}/b,},};returntemplates[locale]??templates[en];}总结ShareKit 通过systemShare.share()提供系统级分享能力支持文本、图片、文件三种数据格式。核心要点UniformDataObject 封装数据、 type 字段标识数据类型、 文本分享附带 HTML 增强展示、 图片先压缩再分享、 分享取消非异常、 包含下载链接传播应用。下一篇将深入 systemShare——SharedData 与 UTD 类型详解。如果这篇文章对你有帮助欢迎点赞、收藏⭐、关注你的支持是我持续创作的动力相关资源ShareKit 官方文档systemShare API 参考UniformDataObject 类型定义UTD 统一类型描述ImageKit 图片编码文件分享最佳实践开源鸿蒙跨平台社区HarmonyOS 开发者官方文档第 153 篇PushKit 推送第 155 篇SharedData