uni-app x 系统分享实战指南uni.shareWithSystem 全平台调用与源码解析【免费下载链接】uni-appA cross-platform framework using Vue.js项目地址: https://gitcode.com/gh_mirrors/un/uni-app本篇技术指南聚焦 uni-app x 提供的系统分享能力uni.shareWithSystem(options)讲解它如何在无需配置任何三方 SDK 的前提下将文本、链接、图片、视频、音频和任意文件分享到手机系统级分享面板并覆盖 Android、iOS、HarmonyOS 三端的兼容性、参数语义、错误码与平台差异。读完本文你将掌握该 API 的完整调用姿势、错误处理规范、与微信 SDK 分享uni.share的选型取舍以及各平台底层的实现原理。什么是系统分享与 SDK 分享的本质区别uni.shareWithSystem调用的是操作系统原生的分享能力与基于三方 SDK 的分享有根本区别无需配置三方 SDK 的 key 信息。不会出现申请微信开放平台、AppID、签名校验等繁琐环节。手机上所有可接受分享的应用都会出现在系统分享列表中由用户自行选择目标应用App 无需提前集成任何三方分享 SDK。从仓库中的 UTS 插件声明package.json可以看到该能力以 uni_modules 的uni-ext-api形式挂载到uni对象上Androidkotlin、iOSswift、HarmonyOSarkts三端均为原生实现Web 平台不支持js: false。平台兼容性| Web | Android | iOS | HarmonyOS | | :- | :- | :- | :- | | x不支持 | 4.33 | 4.33 | 4.61 |该 API 不支持 Web 平台需运行 uni-app x 到 App 平台体验。源码接口定义interface.uts中以uniPlatform注解标注了各平台最低版本Android/iOS 为 4.33iOS Vapor 架构下错误码相关能力自 5.08 起HarmonyOS 为 4.61。options 参数详解uni.shareWithSystem(options)接收一个ShareWithSystemOptions类型参数必填。options 属性描述| 名称 | 类型 | 必填 | 兼容性 | 描述 | | :- | :- | :- | :-: | :- | | type | string | 否 | Web: x; Android: 4.33; iOS: 4.33; HarmonyOS: 4.61 | 分享类型默认为 text | | summary | string | 否 | Web: x; Android: 4.33; iOS: 4.33; HarmonyOS: 4.61 | 分享的文字内容 | | href | string | 否 | Web: x; Android: 4.33; iOS: 4.33; HarmonyOS: 4.61 | 分享链接 | | imageUrl | string | 否 | Web: x; Android: 4.33; iOS: 4.33; HarmonyOS: 4.61 | 分享单个图片仅支持本地路径 | | imagePaths | Arraystring | 否 | Web: x; Android: 4.33; iOS: 4.33; HarmonyOS: 4.61 | 分享图片仅支持本地路径 | | videoPaths | Arraystring | 否 | Web: x; Android: 4.33; iOS: 4.33; HarmonyOS: 4.61 | 分享 video仅支持本地路径 | | audioPaths | Arraystring | 否 | Web: x; Android: 4.33; iOS: 4.33; HarmonyOS: 4.61 | 分享 audio仅支持本地路径 | | filePaths | Arraystring | 否 | Web: x; Android: 4.33; iOS: 4.33; HarmonyOS: 4.61 | 分享文件仅支持本地路径 | | success | (res: ShareWithSystemSuccess) void | 否 | Web: x; Android: 4.33; iOS: 4.33; HarmonyOS: 4.61 | 成功回调函数 | | fail | (res: ShareWithSystemFail ) void | 否 | Web: x; Android: 4.33; iOS: 4.33; HarmonyOS: 4.61 | 失败回调函数 | | complete | (res: any) void | 否 | Web: x; Android: 4.33; iOS: 4.33; HarmonyOS: 4.61 | 完成回调函数成功、失败均会执行 |type 合法值| 合法值 | 兼容性 | 描述 | | :- | :-: | :- | | text | Web: x; Android: 4.33; iOS: 4.33; HarmonyOS: 4.61 | text 类型 | | image | Web: x; Android: 4.33; iOS: 4.33; HarmonyOS: 4.61 | image 类型 | | video | Web: x; Android: 4.33; iOS: 4.33; HarmonyOS: 4.61 | video 类型 | | audio | Web: x; Android: 4.33; iOS: 4.33; HarmonyOS: 4.61 | audio 类型 | | file | Web: x; Android: 4.33; iOS: 4.33; HarmonyOS: 4.61 | file 类型 |使用要点所有多媒体路径参数imageUrl / imagePaths / videoPaths / audioPaths / filePaths均仅支持本地路径。如需分享网络资源须先下载到本地可使用 download-file或通过uni.chooseImage/uni.chooseVideo选择本地文件后再传入tempFilePath。imageUrl分享单张图片imagePaths分享多张图片两者可混用从 Android 源码UniShareWithSystem.kt可以看到调用时imageUrl会被追加到imagePaths列表中统一处理。type未传时默认按text处理Android 端var tempType text兜底逻辑见 UniShareWithSystem.kt。内容不能全为空Android 与 iOS 端在入口处会校验href、imageUrl、imagePaths、summary、videoPaths、audioPaths、filePaths是否同时为空若全部为空则直接以错误码 1310601分享内容不可以为空走失败回调见 app-android/index.uts。失败回调与错误码失败回调参数类型为ShareWithSystemFail其继承自IUniError统一错误模型可参见 docs/err-spec.md 中的 UniError 说明。ShareWithSystemFail 属性描述| 名称 | 类型 | 必填 | 兼容性 | 描述 | | :- | :- | :- | :-: | :- | | errCode | number | 是 | Web: x | 错误码 | | errSubject | string | 是 | Web: x | 统一错误主题模块名称 | | data | any | 否 | Web: x | 错误信息中包含的数据 | | cause | Error | 否 | — | 源错误信息可包含多个错误详见 SourceError | | errMsg | string | 是 | Web: x | 错误信息 |错误主题errSubject在源码中固定为uni-shareWithSystem见 unierror.uts。errCode 错误码描述| 合法值 | 兼容性 | 描述 | | :- | :-: | :- | | 1310600 | Web: x; Android: 4.33; iOS(VDOM): 4.33; iOS(Vapor): 5.08; HarmonyOS: x | 取消分享 | | 1310601 | Web: x; Android: 4.33; iOS(VDOM): 4.33; iOS(Vapor): 5.08; HarmonyOS: x | 分享内容不可以为空 | | 1310602 | Web: x; Android: 4.33; iOS(VDOM): 4.33; iOS(Vapor): 5.08; HarmonyOS: x | 已经成功调用系统分享接口系统分享出错 | | 1310603 | Web: x; Android: 4.33; iOS(VDOM): 4.33; iOS(Vapor): 5.08; HarmonyOS: 4.61 | 图片路径无效 | | 1310604 | Web: x; Android: 4.33; iOS(VDOM): 4.33; iOS(Vapor): 5.08; HarmonyOS: x | 无效的链接 | | 1310605 | Web: x; Android: 4.33; iOS(VDOM): 4.33; iOS(Vapor): 5.08; HarmonyOS: 4.61 | video 路径无效 | | 1310606 | Web: x; Android: 4.33; iOS(VDOM): 4.33; iOS(Vapor): 5.08; HarmonyOS: 4.61 | file 文件不存在 | | 1310607 | Web: x; Android: 4.33; iOS(VDOM): 4.33; iOS(Vapor): 5.08; HarmonyOS: 4.61 | audio 路径无效 |从 unierror.uts 的映射表可以看到每个错误码对应的英文默认信息例如1310600 - Cancel share、1310601 - Shared content can not be empty。当携带具体原因时errMsg会被拼装为默认信息, the reason: 具体原因的格式iOS 与 Android 通过条件编译分别处理见 unierror.uts。完整示例从文本到文件的全类型分享示例对应仓库中的演示页 share-with-system.uvue已在 src/pages.json 中注册。下面按分享类型分类整理可直接复制到页面中使用。分享纯文本script setup languts const summary 欢迎使用hello uniapp-x const shareText () { uni.hideToast() uni.shareWithSystem({ summary: summary, type:text, success(_) { console.log(Shared----------------------------success) }, fail(res) { console.log(Share failed, res.errCode res.errCode ---res.errMsg res.errMsg) uni.showToast({ icon: error, title: errorCode res.errCode }) }, complete(_) { } }) } /script分享链接链接通过href传入type保持textconst shareLink () { uni.hideToast() uni.shareWithSystem({ type:text, href: https://uniapp.dcloud.io, success(_) { console.log(Shared----------------------------success) }, fail(res) { console.log(Share failed, res.errCode res.errCode ---res.errMsg res.errMsg) uni.showToast({ icon: error, title: errorCode res.errCode }) }, complete(_) { } }) }分享单个本地图片const sharePrivateImg () { uni.hideToast() const imageSrc : string /static/test-image/logo.gif uni.shareWithSystem({ type:image, imageUrl: imageSrc, success(_) { console.log(Shared----------------------------success) // 分享完成请注意此时不一定是成功分享 }, fail(res) { console.log(Share failed, res.errCode res.errCode ---res.errMsg res.errMsg) uni.showToast({ icon: error, title: errorCode res.errCode }) // 分享失败 }, complete(_) { } }) }分享多个本地图片const sharePrivateImgs () { uni.hideToast() const imageSrc : string /static/test-image/logo.jpg let imageUrlList : string[] new Array() imageUrlList.push(/static/test-image/logo.png) imageUrlList.push(imageSrc) uni.shareWithSystem({ imagePaths: imageUrlList, type:image, success(_) { console.log(Shared----------------------------success) // 分享完成请注意此时不一定是成功分享 }, fail(res) { console.log(Share failed, res.errCode res.errCode ---res.errMsg res.errMsg) uni.showToast({ icon: error, title: errorCode res.errCode }) }, complete(_) { } }) }同时分享链接、文本与一张图片const shareAll () { uni.hideToast() const imageSrc : string /static/test-video/fast-forward.png let imageUrlList : string[] new Array() imageUrlList.push(imageSrc) uni.shareWithSystem({ summary: summary, href: https://uniapp.dcloud.io, imagePaths: imageUrlList, type:image, success(_) { console.log(Shared----------------------------success) // 分享完成请注意此时不一定是成功分享 }, fail(res) { console.log(Share failed, res.errCode res.errCode ---res.errMsg res.errMsg) uni.showToast({ icon: error, title: errorCode res.errCode }) }, complete(_) { } }) }分享 video / audio / 文件单个与多个视频、音频、文件的调用结构完全一致仅替换type与路径数组参数// 分享单个 video const sharePrivateVideo () { uni.hideToast() const path1 : string /static/test-video/10second-demo.mp4 uni.shareWithSystem({ videoPaths: [path1], type:video, success(_) { console.log(Shared----------------------------success) }, fail(res) { console.log(Share failed, res.errCode res.errCode ---res.errMsg res.errMsg) uni.showToast({ icon: error, title: errorCode res.errCode }) }, complete(_) { } }) } // 分享多个 audio const sharePrivateAudios () { uni.hideToast() const path1 : string /static/test-audio/ForElise.mp3 const path2 : string /static/test-audio/ForElise.mp3 uni.shareWithSystem({ audioPaths: [path1, path2], type:audio, success(_) { console.log(Shared----------------------------success) }, fail(res) { console.log(Share failed, res.errCode res.errCode ---res.errMsg res.errMsg) uni.showToast({ icon: error, title: errorCode res.errCode }) }, complete(_) { } }) } // 分享单个文件 const sharePrivateFile () { uni.hideToast() const path1 : string /static/filemanager/to.zip uni.shareWithSystem({ filePaths: [path1], type:file, success(_) { console.log(Shared----------------------------success) }, fail(res) { console.log(Share failed, res.errCode res.errCode ---res.errMsg res.errMsg) uni.showToast({ icon: error, title: errorCode res.errCode }) }, complete(_) { } }) }从相册/相机选择图片后分享动态资源系统分享的路径参数仅支持本地路径因此动态资源需要先用uni.chooseImage/uni.chooseVideo拿到本地临时文件const sharePubImg () { uni.hideToast() uni.chooseImage({ count: 3, sourceType: [camera, album], success(e) { uni.shareWithSystem({ imagePaths: e.tempFilePaths, type:image, success(_) { console.log(Shared----------------------------success) // 分享完成请注意此时不一定是成功分享 }, fail(res) { console.log(Share failed, res.errCode res.errCode ---res.errMsg res.errMsg) uni.showToast({ icon: error, title: errorCode res.errCode }) }, complete(_) { } }) } }) } const sharePubMedias () { uni.hideToast() uni.chooseVideo({ success(res) { uni.shareWithSystem({ videoPaths: [res.tempFilePath], type:video, success(_) { console.log(Shared----------------------------success) }, fail(res) { console.log(Share failed, res.errCode res.errCode ---res.errMsg res.errMsg) uni.showToast({ icon: error, title: errorCode res.errCode }) }, complete(_) { } }) } }) }指定 view 截图后分享借助uni.getElementById(id).takeSnapshot()将页面指定区域截图为本地图片再走系统分享完整的截图实现见示例页 share-with-system.uvueconst shareSnapShot () { uni.hideToast() uni.getElementById(viewshot)?.takeSnapshot({ success: function (res) { uni.shareWithSystem({ imageUrl: res.tempFilePath, type:image, success(_) { console.log(Shared----------------------------success) }, fail(res) { console.log(Share failed, res.errCode res.errCode ---res.errMsg res.errMsg) uni.showToast({ icon: error, title: errorCode res.errCode }) }, complete(_) { } }) }, fail: function (res) { console.log(res) uni.showToast({ icon: error, title: 截图失败 }) } }) }错误路径的容错演示利于理解错误码示例页还包含一组故意传错路径的按钮用于演示各错误码的触发时机例如单张图片传不存在的路径/static/test-image/logo.jpg11→ 触发 1310603图片路径无效多张图片中混入错误路径/static/test-image/logo.jpg1、/static/test-image/logo.jpg3→ 同样触发 1310603并提示无效的具体文件video 传错误路径10second-demo1.mp4→ 触发 1310605audio 传错误路径ForElise.mp32→ 触发 1310607文件传不存在的路径/static/filemanager1/to.zip→ 触发 1310606。// 多个本地图片含有错误路径示例 const sharePrivateErrorImgs () { uni.hideToast() const errorImageSrc1 : string /static/test-image/logo.jpg1 const errorImageSrc2 : string /static/test-image/logo.jpg3 const imageSrc : string /static/test-image/logo.jpg let imageUrlList : string[] new Array() imageUrlList.push(imageSrc) imageUrlList.push(errorImageSrc1) imageUrlList.push(errorImageSrc2) uni.shareWithSystem({ imagePaths: imageUrlList, type:image, success(_) { console.log(Shared----------------------------success) }, fail(res) { console.log(Share failed, res.errCode res.errCode ---res.errMsg res.errMsg) uni.showToast({ icon: error, title: errorCode res.errCode }) }, complete(_) { } }) }三端底层实现原理uni.shareWithSystem是一个 UTS 扩展 API实现代码位于 src/uni_modules/uni-shareWithSystem/utssdk 目录按平台分离| 目录/文件 | 目标平台 | 实现语言 | 核心内容 | | -- | -- | -- | -- | | utssdk/app-android | Android | UTS Kotlin | 基于Intent.ACTION_SEND/ACTION_SEND_MULTIPLE的系统分享 | | utssdk/app-ios | iOS | UTS Swift | 基于UIActivityViewController的系统分享 | | utssdk/app-harmony | HarmonyOS | UTS ArkTS | 基于 ShareKitsystemShare.ShareController的系统分享 | | utssdk/interface.uts | 多平台共用 | UTS | 参数与错误码类型定义 | | utssdk/unierror.uts | 多平台共用 | UTS | 统一错误对象与错误码文案映射 |AndroidIntent 分享与私有资源处理Android 端核心实现为 UniShareWithSystem.kt类型分发根据type走when分支将对应的路径数组交给checkPath()做合法性检查路径检查与转换checkPath()通过UTSAndroid.convert2AbsFullPath()将相对路径转为绝对路径。对应用私有资源以/android_asset/开头会先通过DHFile.copyAssetsFile()拷贝到externalCacheDir/share/下因为应用私有路径无法直接分享对content://开头的 URI 直接透传其余路径校验文件是否真实存在构造 IntentsetSysShareIntent()中单个文件使用Intent.ACTION_SENDEXTRA_STREAM多个文件使用Intent.ACTION_SEND_MULTIPLEEXTRA_STREAMParcelableArrayListMIME 类型对file设置为*/*其余类型设置为type/*如image/*拉起面板通过Intent.createChooser()创建系统分享选择器并添加FLAG_GRANT_READ_URI_PERMISSION授权Android 7.0 使用 FileProvider 生成 content URI见 UniShareWithSystem.ktcontext.startActivity()启动异常兜底任何异常统一以 1310602 走失败回调。入口 app-android/index.uts 负责空内容校验全空则触发 1310601、回调分发success/fail/complete 三回调由ShareManager统一管理。iOSUIActivityViewController 与类型校验iOS 端核心实现为 app-ios/index.uts异步图片加载图片通过UTSiOS.loadImage()异步加载并用DispatchGroup等待加载失败或路径无效会累积错误列表并在最后统一触发 1310603链接校验isValidHref()要求href具备 scheme 与 host且 scheme 必须为http或https否则触发 1310604无效的链接媒体类型校验isValidVideoFile()/isValidAudioFile()在 iOS 14 通过UTTypeUniformTypeIdentifiers判断文件是否 conform 到 movie/video/audio 类型低版本则退化为按扩展名白名单判断视频扩展名如 mp4/mov/avi/mkv…音频扩展名如 mp3/aac/wav/flac…无效路径分别触发 1310605 / 1310607呈现面板构建UIActivityViewController通过completionWithItemsHandler回调区分三种结果——activityError非空触发 1310602、completed true走成功回调、否则视为取消触发 1310600iPad 上额外配置popoverPresentationController的 sourceView/sourceRect 以正确弹出路径转换getValidPath()支持file://前缀、/var/绝对路径及应用资源路径UTSiOS.getResourcePath()三种形式统一转成URL供分享。HarmonyOSShareKit 与沙箱资源处理鸿蒙端核心实现为 app-harmony/index.uts构建 SharedRecord将href、imageUrl、imagePaths、videoPaths、audioPaths、filePaths、summary分别映射为systemShare.SharedRecord使用uniformTypeDescriptor标记HYPERLINK/IMAGE/VIDEO/AUDIO/FILE/TEXT等 UTD 类型沙箱资源处理processShareFile()会将位于resourceDir下的应用资源文件复制到应用沙箱临时目录TEMP_PATH/systemShareCache下再通过fileUri.getUriFromPath()转为可分享的 uri——因为 resfile 下的文件本身无法直接分享源码注释明确标注了这一点错误映射各类资源处理失败分别抛出 1310603 / 1310605 / 1310606 / 1310607全部记录为空时抛出 1310601呈现与回调通过ShareController.show()以BATCH选择模式 DETAIL预览模式拉起系统分享面板监听dismiss事件后 resolve注意鸿蒙端当前未单独区分用户取消事件取消分享不触发 1310600与 Android/iOS 存在差异。通用错误对象三端最终统一构造ShareWithSystemFailImpl继承自UniError填充errSubject uni-shareWithSystem、errCode与errMsg再依次派发fail与complete回调见 unierror.uts。注意系统分享与微信 SDK 分享的差异系统分享和微信 SDK 分享在 Android 上存在显著差异选型时需要特别注意原文档注意节原文要点朋友圈能力不同Android 系统分享单张图片可以进朋友圈但多张图片进朋友圈只能使用微信 SDK即 uni.share。链接分享形态不同Android 系统分享链接到微信时只能以纯文本方式分享如需方条链接卡片式链接需使用微信 SDK 的 uni.share而iOS 的系统分享可以直接分享方条链接。链接图片组合行为不同Android 系统分享同时分享链接和图片到微信时最终只能分享图片而 iOS 系统分享同时分享链接和图片时会把图片作为链接的题图缩略图。因此如果你的核心场景是分享到微信且需要卡片式链接、多图进朋友圈应选用微信 SDK 分享 uni.share需配置微信开放平台 key如果追求免配置、覆盖所有可接收分享的应用则优先选择本文的uni.shareWithSystem。相关资源API 文档源文件docs/api/share-with-system.md插件类型与参数定义src/uni_modules/uni-shareWithSystem/utssdk/interface.uts错误对象与错误码映射src/uni_modules/uni-shareWithSystem/utssdk/unierror.utsAndroid 原生实现UniShareWithSystem.ktiOS 原生实现app-ios/index.utsHarmonyOS 原生实现app-harmony/index.uts完整演示页src/pages/API/share-with-system/share-with-system.uvue统一错误规范docs/err-spec.mdSDK 分享对比参照docs/api/share.md【免费下载链接】uni-appA cross-platform framework using Vue.js项目地址: https://gitcode.com/gh_mirrors/un/uni-app创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考