uniapp 分享设置与调用
在不同平台,分享的调用方式和逻辑有较大差异。
- App:可以自主控制分享内容、分享形式及分享平台
- 使用
uni.share
API方式调用社交sdk分享 - 使用plus.share.sendWithSystem (opens new window)呼起手机os的系统分享菜单
- 小程序:不支持API调用,只能用户主动点击触发分享。可使用自定义按钮方式 <button open-type="share"> 或监听系统右上角的分享按钮 onShareAppMessage 进行自定义分享内容
- H5:如果是普通浏览器,浏览器自带分享按钮;如果是在微信内嵌浏览器中,可调用js-sdk进行分享,参考(opens new window)
- APP:可以直接使用已经封装好的uni-share插件详情(opens new window)
一、uni.share(OBJECT)
uni-app的App引擎已经封装了微信、QQ、微博的分享SDK,开发者可以直接调用相关功能。
可以分享到微信、QQ、微博,每个社交平台被称为分享服务提供商,即provider。
可以分享文字、图片、图文横条、音乐、视频等多种形式。同时注意,分享为小程序也使用本API。即在App里可以通过本API把一个内容以小程序(通常为内容页)方式直接分享给微信好友。
平台差异说明
App | H5 | 微信小程序 | 支付宝小程序 | 百度小程序 | 字节跳动小程序、飞书小程序 | QQ小程序 | 快手小程序 | 京东小程序 |
---|---|---|---|---|---|---|---|---|
√ | x | x | x | x | x | x | x | x |
OBJECT 参数说明
参数名 | 类型 | 必填 | 说明 |
---|---|---|---|
provider | String | 是 | 分享服务提供商(即weixin|qq|sinaweibo),通过 uni.getProvider 获取可用的分享服务商,可用是指在manifest.json的sdk配置中配的分享sdk厂商,与本机安装了什么社交App无关 |
type | Number | 否 | 分享形式,如图文、纯文字、纯图片、音乐、视频、小程序等。默认图文 0。不同分享服务商支持的形式不同,具体参考下面type值说明。 |
title | String | 否 | 分享内容的标题 |
scene | String | provider 为 weixin 时必选 | 场景,可取值参考下面说明。 |
summary | String | type 为 1 时必选 | 分享内容的摘要 |
href | String | type 为 0 时必选 | 跳转链接 |
imageUrl | String | type 为 0、2、5 时必选 | 图片地址。type为0时,推荐使用小于20Kb的图片 |
mediaUrl | String | type 为 3、4 时必选 | 音视频地址 |
miniProgram | Object | type 为 5 时必选 | 分享小程序必要参数 |
openCustomerServiceChat | Boolean | 否 | 是否启用拉起客服功能(目前仅支持微信。HBuilder X 3.4.3+) |
corpid | String | openCustomerServiceChat = true 时必填 |
客服ID(目前仅支持微信。HBuilder X 3.4.3+) |
customerUrl | String | openCustomerServiceChat = true 时必填 |
客服的页面路径(目前仅支持微信。HBuilder X 3.4.3+) |
success | Function | 否 | 接口调用成功的回调 |
fail | Function | 否 | 接口调用失败的回调函数 |
complete | Function | 否 | 接口调用结束的回调函数(调用成功、失败都会执行) |
type 值说明
值 | 说明 | provider 支持度 |
---|---|---|
0 | 图文 | weixin、sinaweibo |
1 | 纯文字 | weixin、qq |
2 | 纯图片 | weixin、qq |
3 | 音乐 | weixin、qq |
4 | 视频 | weixin、sinaweibo |
5 | 小程序 | weixin |
scene 值说明
值 | 说明 |
---|---|
WXSceneSession | 分享到聊天界面 |
WXSceneTimeline | 分享到朋友圈 |
WXSceneFavorite | 分享到微信收藏 |
miniProgram 值说明
值 | 类型 | 说明 |
---|---|---|
id | String | 微信小程序原始id |
path | String | 点击链接进入的页面 |
type | Number | 微信小程序版本类型,可取值: 0-正式版; 1-测试版; 2-体验版。 默认值为0。 |
webUrl | String | 兼容低版本的网页链接 |
注意事项:
- 真机运行时,分享调用的是HBuilder真机运行基座的sdk配置,分享出去的内容会显示为HBuilder。需自行在各社交平台注册账户,在manifest的sdk配置中填写自己的配置,打包后生效。
- 分享到 QQ 必须含有 href 链接
- 分享文字到 QQ 时,title 必选
- 新浪微博仅支持分享本地音视频,不能分享网络音视频
- 仅支持分享微信小程序到微信聊天界面,想进入朋友圈需改为分享图片方式,在图片中包含小程序码。一般通过canvas绘制图片,插件市场有很多生成图片的插件。
- 在 iOS 端,若未安装微博客户端,会启用微博的网页分享,此时不能分享图片
- 分享新浪微博不会返回正确的成功回调
- 不能直接分享到QQ空间,可以分享到QQ,然后在QQ的界面里选择QQ空间。
- 分享微信朋友圈多图,微信官方已经禁掉这个功能。可以考虑把多张图用canvas合并成一张图分享出去。
- 从APP分享到微信时,无法判断用户是否点击取消分享,因为微信官方禁掉了分享成功的返回值。
#分享到微信聊天界面示例代码
分享文字
uni.share({
provider: "weixin",
scene: "WXSceneSession",
type: 1,
summary: "我正在使用HBuilderX开发uni-app,赶紧跟我一起来体验!",
success: function (res) {
console.log("success:" + JSON.stringify(res));
},
fail: function (err) {
console.log("fail:" + JSON.stringify(err));
}
});
分享图片
uni.share({
provider: "weixin",
scene: "WXSceneSession",
type: 2,
imageUrl: "https://bjetxgzv.cdn.bspapp.com/VKCEYUGU-uni-app-doc/d8590190-4f28-11eb-b680-7980c8a877b8.png",
success: function (res) {
console.log("success:" + JSON.stringify(res));
},
fail: function (err) {
console.log("fail:" + JSON.stringify(err));
}
});
分享图文
href、imageUrl 为必选参数,title/summary 二选一,最好将这四个参数都选上。
uni.share({
provider: "weixin",
scene: "WXSceneSession",
type: 0,
href: "http://uniapp.dcloud.io/",
title: "uni-app分享",
summary: "我正在使用HBuilderX开发uni-app,赶紧跟我一起来体验!",
imageUrl: "https://bjetxgzv.cdn.bspapp.com/VKCEYUGU-uni-app-doc/d8590190-4f28-11eb-b680-7980c8a877b8.png",
success: function (res) {
console.log("success:" + JSON.stringify(res));
},
fail: function (err) {
console.log("fail:" + JSON.stringify(err));
}
});
分享到微信朋友圈示例代码
分享文字
uni.share({
provider: "weixin",
scene: "WXSceneTimeline",
type: 1,
summary: "我正在使用HBuilderX开发uni-app,赶紧跟我一起来体验!",
success: function (res) {
console.log("success:" + JSON.stringify(res));
},
fail: function (err) {
console.log("fail:" + JSON.stringify(err));
}
});
分享图片
uni.share({
provider: "weixin",
scene: "WXSceneTimeline",
type: 2,
imageUrl: "https://bjetxgzv.cdn.bspapp.com/VKCEYUGU-uni-app-doc/d8590190-4f28-11eb-b680-7980c8a877b8.png",
success: function (res) {
console.log("success:" + JSON.stringify(res));
},
fail: function (err) {
console.log("fail:" + JSON.stringify(err));
}
});
分享图文
href、imageUrl 为必选参数,title、summary 至少有一项。
uni.share({
provider: "weixin",
scene: "WXSceneTimeline",
type: 0,
href: "http://uniapp.dcloud.io/",
title: "uni-app分享",
summary: "我正在使用HBuilderX开发uni-app,赶紧跟我一起来体验!",
imageUrl: "https://bjetxgzv.cdn.bspapp.com/VKCEYUGU-uni-app-doc/d8590190-4f28-11eb-b680-7980c8a877b8.png",
success: function (res) {
console.log("success:" + JSON.stringify(res));
},
fail: function (err) {
console.log("fail:" + JSON.stringify(err));
}
});
App分享为微信小程序(App中分享一个内容到微信好友,对方微信中呈现的是一个小程序卡片)
uni.share({
provider: 'weixin',
scene: "WXSceneSession",
type: 5,
imageUrl: 'https://bjetxgzv.cdn.bspapp.com/VKCEYUGU-uni-app-doc/962fc340-4f2c-11eb-bdc1-8bd33eb6adaa.png',
title: '欢迎体验uniapp',
miniProgram: {
id: 'gh_abcdefg',
path: 'pages/index/index',
type: 0,
webUrl: 'http://uniapp.dcloud.io'
},
success: ret => {
console.log(JSON.stringify(ret));
}
});
二、uni.share 在App端各社交平台分享配置说明
- 第一步,打开 manifest.json -> App模块权限配置,勾选 Share(分享);
- 第二步,按如下文档具体配置微信、微博、QQ的参数。
(1)微信分享
在 manifest.json 的 App SDK 配置里,勾选微信消息及朋友圈,并填写 appid,如需在iOS平台使用还需要配置通用链接。
参考文档
- 微信 appid 申请步骤:https://ask.dcloud.net.cn/article/208 (opens new window)。
- iOS平台微信SDK配置通用链接:https://ask.dcloud.net.cn/article/36445 (opens new window)。
(2)新浪微博分享
在 manifest.json 的 App SDK 配置里,勾选勾选新浪微博,并填写相关appkey,新浪微博 appkey 申请步骤可参考:https://ask.dcloud.net.cn/article/209 (opens new window)。
(3)QQ 分享
在 manifest.json 的 App SDK 配置里,勾选分享到QQ好友,并填写相关appkey,QQ分享 appkey 申请步骤:
- 前往 QQ 开放平台:https://connect.qq.com/index.html (opens new window);
- 完成开发者注册;
- 创建应用,选择移动 App,填写相关信息,然后等待审核,审核通过后即可得到AppId。
这些配置需要打包生效,真机运行仍然是HBuilder基座的设置,可使用自定义基座包 (opens new window)调试。离线打包请参考离线打包文档在原生工程中配置。
配置并打包后,通过uni.getProvider
可以得到配置的结果列表,注意这里返回的是manifest配置的,与手机端是否安装微信、QQ、微博无关。
如果手机端未安装QQ、微博,调用时会启动这些平台的wap页面分享,如果已安装相应客户端,会启动它们的客户端分享。
#FAQ
-
Q:App端如何集成其他分享SDK,如facebook分享、twitter分享
-
A:插件市场已有相关插件,详见 (opens new window);也可以根据原生插件教程自行开发,原生插件开发文档见https://ask.dcloud.net.cn/article/35428(opens new window)
-
Q:弹出分享菜单,是否有已经写好的插件?
-
A:插件市场有很多封装好的分享菜单插件,底部图标菜单 (opens new window),可直接弹出菜单,并且没有遮挡层级问题,推荐使用。
三、uni.shareWithSystem(OBJECT)
调用系统分享组件发送分享消息,不需要配置分享SDK
平台差异说明
App | H5 | 微信小程序 | 支付宝小程序 | 百度小程序 | 字节跳动小程序、飞书小程序 | QQ小程序 | 京东小程序 |
---|---|---|---|---|---|---|---|
√(App 2.6.4+) | x | x | x | x | x | x | x |
OBJECT 参数说明
参数名 | 类型 | 必填 | 说明 |
---|---|---|---|
type | String | - | 分享类型,只支持text,image,默认为text |
summary | String | - | 分享的文字内容 |
href | String | - | 分享链接,ios端分享到微信时必填此字段 |
imageUrl | String | - | 分享图片,仅支持本地路径 |
success | Function | 否 | 接口调用成功的回调 |
fail | Function | 否 | 接口调用失败的回调函数 |
complete | Function | 否 | 接口调用结束的回调函数(调用成功、失败都会执行) |
注意事项
- Android端当msg参数中设置图片(
imageUrl
属性)时,分享类型自动变为为image
,在分享时可能只会发送图片(如微信);没有设置图片时分享类型则认为是文本text
。 - Android端高版本无法分析私有路径的图片,只能分享来自相册的图片(使用 uni.chooseImage 选择图像时请设置为原图)。
- iOS端不同的分享程序对分享内容有要求,如微信分享时必需添加链接地址
href
,否则微信分享失败。 注:iOS8.0及以上系统触发成功回调则表示发送消息成功。
示例代码
uni.shareWithSystem({
summary: '',
href: 'https://uniapp.dcloud.io',
success(){
// 分享完成,请注意此时不一定是成功分享
},
fail(){
// 分享失败
}
})
四、plus.share.sendWithSystem(msg, successCB, errorCB)
Android和iOS都有应用注册分享接口的机制,基本上所有有接收分享内容功能的应用,都会注册分享接口。
App端可调用手机的系统分享,实现所有注册分享的应用的呼起,比如短信、邮件、蓝牙(仅Android)、隔空投送(仅iOS),或其他注册系统分享的应用,比如钉钉。
与uni.share
相比,调用系统分享不需要集成三方sdk。但有些功能上的限制,比如无法分享为微信小程序。
平台差异说明
App | H5 | 微信小程序 | 支付宝小程序 | 百度小程序 | 字节跳动小程序、飞书小程序 | QQ小程序 | 快手小程序 | 京东小程序 |
---|---|---|---|---|---|---|---|---|
√ | x | x | x | x | x | x | x | x |
说明: 调用系统分享组件分享消息,通过msg参数设置分享内容。 发送成功后通过successCB回调函数通知操作完成,发送失败则通过errorCB回调返回。
参数 | 类型 | 说明 |
---|---|---|
msg | object | 要发送的分享消息对象,如文字内容,图片等信息。对象格式见下。必填 |
successCB | 成功回调,可选。注:此回调仅保证呼起分享界面,并不表示分享消息已经发送成功 | |
errorCB | 失败回调,可选 |
msg参数说明
参数 | 类型 | 说明 |
---|---|---|
type | String | 分享类型,仅支持text、image |
content | String | 分享消息的文字内容 |
pictures | Array[ String ] | 分享消息中包含的图片路径,仅支持本地路径。 若分享平台仅支持提交一张图片,传入多张图片则仅提交第一张图片。 如果未指定type类型,优先级顺序为:pictures>content(即设置了pictures则认为分享图片类型)。 |
href | String | 分享独立的链接地址,仅支持网络地址(以http://或https://开头)。 如果未指定type类型,优先级顺序为:href>pictures>content(即设置了href则认为分享网页类型)。 |
示例代码
plus.share.sendWithSystem({content:'分享内容',href:'https://www.dcloud.io/'}, function(){
console.log('分享成功');
}, function(e){
console.log('分享失败:'+JSON.stringify(e));
});
注意
- Android:当msg参数中设置图片(msg.pictures属性)时,分享类型为"image",在分享时可能只会发送图片(如微信);没有设置图片时分享类型则认为是文本"text"。
- iOS:不同的分享程序对分享内容有要求,如微信分享时必需添加链接地址(msg.href),否则微信分享失败。 注:iOS8.0及以上系统表示分享操作成功则表示发送消息成功。
- 很多App的做法是点击分享按钮首先弹出一个自定义菜单,放置微信好友、朋友圈、QQ、微博等功能图标,然后再放置一个更多分享,点击后会调用系统分享。类似插件在插件市场 (opens new window)很多。
五、onShareAppMessage(OBJECT)
小程序中用户点击分享后,在 js 中定义 onShareAppMessage 处理函数(和 onLoad 等生命周期函数同级),设置该页面的分享信息。
- 用户点击分享按钮的时候会调用。这个分享按钮可能是小程序右上角原生菜单自带的分享按钮,也可能是开发者在页面中放置的分享按钮(
<button open-type="share">
); - 此事件需要 return 一个Object,用于自定义分享内容。
微信小程序平台的分享管理比较严格,请参考 小程序分享指引 (opens new window)。
平台差异说明
App | H5 | 微信小程序 | 支付宝小程序 | 百度小程序 | 字节跳动小程序、飞书小程序 | QQ小程序 | 快手小程序 | 京东小程序 |
---|---|---|---|---|---|---|---|---|
x | x | √ | √ | x | √ | √ | √ | √ |
参数 | 类型 | 说明 | 平台差异说明 |
---|---|---|---|
from | String | 分享事件来源:button(页面内分享按钮)、menu(右上角分享按钮) | |
target | Object | 如果 from 值是 button,则 target 是触发这次分享事件的 button,否则为 undefined | |
webViewUrl | String | 页面中包含 <web-view> 组件时,返回当前 <web-view> 的url |
微信小程序1.6.4+、支付宝小程序、京东小程序 |
此事件需要 return 一个 Object,用于自定义分享内容,其内容如下:
参数名 | 类型 | 必填 | 说明 | 平台差异说明 |
---|---|---|---|---|
title | String | 是 | 分享标题 | |
path | String | 是 | 页面 path ,必须是以 / 开头的完整路径。注意:京东小程序,开头不要加'/' | QQ小程序不支持 |
imageUrl | String | 否 | 分享图标,路径可以是本地文件路径、代码包文件路径或者网络图片路径。支持PNG及JPG。显示图片长宽比是 5:4 | |
content | String | 否 | 百度小程序表现为:分享内容;支付宝小程序表现为:吱口令文案 | 百度小程序、支付宝小程序 |
desc | String | 否 | 自定义分享描述 | 支付宝小程序、字节跳动小程序、京东小程序 |
bgImgUrl | String | 否 | 自定义分享二维码的背景图,建议大小750*950(网络图片路径) | 支付宝小程序 |
query | String | 否 | QQ小程序查询字符串,必须是 key1=val1&key2=val2 的格式。从这条转发消息进入后,可通过 qq.getLaunchOptionSync() 或 qq.onShow() 获取启动参数中的 query。 | QQ小程序 |
templateId | String | 否 | 开发者后台设置的分享素材模板 id | 字节跳动小程序 |
mpId | String | 否 | 微信小程序id,此场景用于分享到微信后,用户点击分享卡片,进入该appid对应的微信小程序,实现引流到微信小程序 | 京东小程序 |
type | Number | 否 | 转发形式(0 - 微信小程序正式版 ;1 - 微信小程序开发版;2 - 微信小程序体验版;京东App9.0.0开始不填或者其他值都会先判断是否有url参数,如果有打开分享后显示url对应页面,否则默认生成京东小程序官方的一个分享中间页面,点击可跳到京东app里面的对应小程序。) | 京东小程序 |
mpPath | String | 否 | 微信小程序路径 | 京东小程序 |
channel | String | 否 | 渠道(不写默认微信朋友,微信朋友圈) | 京东小程序 |
url | String | 否 | h5链接地址(h5分享填写,不填默认中间页) | 京东小程序 |
success | Function | 否 | 接口调用成功的回调函数 | 支付宝小程序、百度小程序 |
fail | Function | 否 | 接口调用失败的回调函数 | 支付宝小程序、百度小程序 |
complete | Function | 否 | 接口调用结束的回调函数(调用成功、失败都会执行) | 百度小程序 |
示例代码
export default {
onShareAppMessage(res) {
if (res.from === 'button') {// 来自页面内分享按钮
console.log(res.target)
}
return {
title: '自定义分享标题',
path: '/pages/test/test?id=123'
}
}
}
注意
- 微信、头条平台:只有定义了此事件处理函数,小程序右上角菜单才会显示“转发”按钮
- QQ小程序还支持通过qq.offShareAppMessage (opens new window)取消对系统分享按钮的监听。
六、uni.showShareMenu(OBJECT)
小程序的原生菜单中显示分享按钮
平台差异说明
App | H5 | 微信小程序 | 支付宝小程序 | 百度小程序 | 字节跳动小程序、飞书小程序 | QQ小程序 | 快手小程序 | 京东小程序 |
---|---|---|---|---|---|---|---|---|
x | x | √ | √ | √ | √ | √ | √ | √ |
属性 | 类型 | 必填 | 说明 | 平台差异说明 |
---|---|---|---|---|
withShareTicket | Boolean | 否 | 是否使用带 shareTicket 的转发,默认为 flase。详情(opens new window) | 微信小程序 |
title | String | 否 | 分享标题 | 百度小程序 |
content | String | 否 | 分享内容 | 百度小程序 |
imageUrl | String | 否 | 分享图标 | 百度小程序 |
path | String | 否 | 页面 path ,必须是以 / 开头的完整路径。 | 百度小程序 |
success | Function | 否 | 接口调用成功的回调函数 | |
fail | Function | 否 | 接口调用失败的回调函数 | |
complete | Function | 否 | 接口调用结束的回调函数(调用成功、失败都会执行) |
七、uni.hideShareMenu(OBJECT)
小程序的原生菜单中隐藏分享按钮
平台差异说明
App | H5 | 微信小程序 | 支付宝小程序 | 百度小程序 | 字节跳动小程序、飞书小程序 | QQ小程序 | 快手小程序 | 京东小程序 |
---|---|---|---|---|---|---|---|---|
x | x | √ | √(1.17.0+) | x | √ | √ | √ | √ |
属性 | 类型 | 必填 | 说明 | 平台差异说明 |
---|---|---|---|---|
hideShareItems | Array | 否 | ['qq']控制是否隐藏"转发",['qzone']控制是否隐藏"分享到空间",不带hideShareItems参数默认"转发"、"分享到空间"全隐藏。目前只支持'qq'、'qzone'。 | QQ小程序 |
success | function | 否 | 接口调用成功的回调函数 | |
fail | function | 否 | 接口调用失败的回调函数 | |
complete | function | 否 | 接口调用结束的回调函数(调用成功、失败都会执行) |
代码示例
uni.hideShareMenu()
注意
- QQ小程序可以单独控制隐藏分享到QQ好友或分享到QQ空间,详见其API文档