# 鸿蒙应用开发手册
本文介绍如何在鸿蒙 HarmonyOS Next 移动应用中实现微信分享功能。
# 1、接入指南与支持类型
- 如何接入鸿蒙版 OpenSDK 可参考 鸿蒙应用微信登录接入指南,App 中在集成微信 SDK 后,可调用接口实现微信分享的功能
- 已发布分享对象和首次版本如下,使用前请确认所集成的 OpenSDK 版本。
# 已发布媒体对象速查
| 对象 | 首次版本 | 主要用途 | 目标场景提示 |
|---|---|---|---|
| WXTextObject | 1.0.0 | 文字 | 会话、朋友圈 |
| WXImageObject | 1.0.0 | 图片 | 会话、朋友圈 |
| WXWebpageObject | 1.0.6 | 网页 | 会话、朋友圈 |
| WXMiniProgramObject | 1.0.6 | 小程序卡片 | 会话 |
| WXFileObject | 1.0.9 | 一般文件(如 PDF) | 会话 |
| WXVideoObject | 1.0.12 | 网络视频 | 会话、朋友圈 |
| WXVideoFileObject | 1.0.12 | 本地视频 | 目前只支持朋友圈 |
# WXMediaMessage(微信媒体消息内容)说明
| 字段 | 类型 | 含义 | 备注 |
|---|---|---|---|
| title | string | 消息标题 | 限制长度不超过 512Bytes |
| description | string | 消息描述 | 限制长度不超过 1KB |
| thumbData | Uint8Array | 消息略缩图数据 | 大小不能超过 64K |
| mediaObject | IMediaObject | 消息对象 | 用于描述一个媒体对象的接口,媒体对象包括: WXTextObject、WXImageObject、WXWebpageObject、WXMiniProgramObject |
# SendMessageToWXReq(SendMessageToWX 请求类)
| 字段 | 类型 | 含义 | 备注 |
|---|---|---|---|
| message | WXMediaMessage | 发送消息的多媒体内容 | |
| scene | number | 发送的目标场景 | 分享到对话: SendMessageToWXReq.WXSceneSession 分享到朋友圈: SendMessageToWXReq.WXSceneTimeline |
补充说明:当前仅图片、文字、视频、网页支持分享到朋友圈。
# 示例
一、文字类型分享示例
WXTextObject:多媒体消息中包含的文本数据对象
| 字段 | 类型 | 含义 | 备注 |
|---|---|---|---|
| text | string | 文本数据 | 长度需大于 0 且不超过 10KB |
文字类型分享 demo
let textObject = new wxopensdk.WXTextObject
textObject.text = "分享的内容"
let mediaMessage = new wxopensdk.WXMediaMessage()
mediaMessage.mediaObject = textObject
let req = new wxopensdk.SendMessageToWXReq()
req.scene = wxopensdk.SendMessageToWXReq.WXSceneSession
req.message = mediaMessage
this.wxApi.sendReq(getContext(this) as common.UIAbilityContext, req
二、图片类型分享示例
WXImageObject:多媒体消息中包含的图片数据对象
| 字段 | 类型 | 含义 | 备注 |
|---|---|---|---|
| uri | string | 图片本地路径的 uri | 支持 jpeg/png 类型的图片 |
| imageData | string | 图片二进制数据的 base64 字符串 | 系统跳转限制大小不能超过 100KB,uri 和 imageData 同时存在时会优先使用 uri 字段,忽略 imageData |
使用 uri 发送图片
let imageObject = new wxopensdk.WXImageObject
imageObject.uri = fileUri.getUriFromPath(filePath);
let mediaMessage = new wxopensdk.WXMediaMessage()
mediaMessage.mediaObject = imageObject
let req = new wxopensdk.SendMessageToWXReq()
req.scene = wxopensdk.SendMessageToWXReq.WXSceneSession
req.message = mediaMessage
this.wxApi.sendReq(getContext(this) as common.UIAbilityContext, req)
使用 imageBase64 发送图片
let imageObject = new wxopensdk.WXImageObject
let buf: buffer.Buffer = buffer.from(data);
imageObject.imageData = buf.toString('base64', 0, buf.length);
let mediaMessage = new wxopensdk.WXMediaMessage()
mediaMessage.mediaObject = imageObject
let req = new wxopensdk.SendMessageToWXReq()
req.scene = wxopensdk.SendMessageToWXReq.WXSceneSession
req.message = mediaMessage
this.wxApi.sendReq(getContext(this) as common.UIAbilityContext, req)
三、网页类型分享示例
WXWebpageObject:多媒体消息中包含的网页数据对象
| 字段 | 类型 | 含义 | 备注 |
|---|---|---|---|
| webpageUrl | string | 网页链接 | 长度需大于 0 且不超过 10KB |
const webpageObject = new wxopensdk.WXWebpageObject()
webpageObject.webpageUrl = "http://www.qq.com"
const mediaMessage = new wxopensdk.WXMediaMessage()
mediaMessage.mediaObject = webpageObject
mediaMessage.title = "测试网页链接"
mediaMessage.description = "测试网页摘要"
const thumbData = await getContext(this).resourceManager.getMediaContent($r("app.media.thumb_img"))
const thumbPixel = image.createImageSource(thumbData.buffer).createPixelMapSync()
const thumbBuffer = await image.createImagePacker().packToData(thumbPixel, { format: "image/png", quality: 100 })
mediaMessage.thumbData = new Uint8Array(thumbBuffer)
const req = new wxopensdk.SendMessageToWXReq()
req.callbackAbility = kDemoEntryAbility
req.scene = wxopensdk.SendMessageToWXReq.WXSceneSession
req.message = mediaMessage
this.wxApi.sendReq(getContext(this) as common.UIAbilityContext, req)
四、小程序类型分享示例
WXMiniProgramObject:多媒体消息中包含的小程序数据对象
| 字段 | 类型 | 含义 | 备注 |
|---|---|---|---|
| userName | string | 小程序的原始 id(gh_xxxx 形式的 id) | 小程序原始 ID 获取方法:登录小程序管理后台-设置-基本设置-账号信息 |
| path | string | 小程序的 path | 小程序页面路径 |
| miniprogramType | int | 小程序的类型,默认正式版 | 正式版:WXMiniProgramType.RELEASE 测试版:WXMiniProgramType.TEST 预览版:WXMiniProgramType.PREVIEW |
| withShareTicket | boolean | 是否使用带 shareTicket 的分享 | 通常开发者希望分享出去的小程序被二次打开时可以获取到更多信息,例如群的标识,可以设置 withShareTicket 为 true,当分享卡片在群聊中被其他用户打开时,可以获取到 shareTicket,用于获取更多分享信息。详见 小程序获取更多分享信息 |
const miniProgramObject = new wxopensdk.WXMiniProgramObject()
miniProgramObject.userName = "gh_ac032d0848a9"
miniProgramObject.path = "pages/Home/Home"
miniProgramObject.miniprogramType = wxopensdk.WXMiniProgramType.RELEASE
const mediaMessage = new wxopensdk.WXMediaMessage()
mediaMessage.mediaObject = miniProgramObject
mediaMessage.title = "测试分享小程序 Title"
mediaMessage.description = "分享小程序描述信息"
const thumbData = await getContext(this).resourceManager.getMediaContent($r("app.media.thumb_img2"))
const thumbPixel = image.createImageSource(thumbData.buffer).createPixelMapSync()
const thumbBuffer = await image.createImagePacker().packToData(thumbPixel, { format: "image/png", quality: 100 })
mediaMessage.thumbData = new Uint8Array(thumbBuffer)
const req = new wxopensdk.SendMessageToWXReq()
req.callbackAbility = kDemoEntryAbility
req.scene = wxopensdk.SendMessageToWXReq.WXSceneSession
req.message = mediaMessage
this.wxApi.sendReq(getContext(this) as common.UIAbilityContext, req)
五、文件类型分享示例(含 PDF)
WXFileObject:多媒体消息中包含的文件数据对象,用于分享一般文件。PDF 只是示例,不是唯一支持的格式。OpenSDK 1.0.9 及以上版本支持。
| 字段 | 类型 | 含义 | 备注 |
|---|---|---|---|
| fileUri | string | 文件 URI | 必填;发送前确认文件存在且 URI 可读 |
文件类型分享 demo(以 PDF 分享到会话为例)
import { fileIo, fileUri } from '@kit.CoreFileKit'
const filePath = getContext(this).getApplicationContext().filesDir + "/example.pdf"
if (!fileIo.accessSync(filePath, fileIo.AccessModeType.EXIST)) {
return
}
const fileObject = new wxopensdk.WXFileObject()
fileObject.fileUri = fileUri.getUriFromPath(filePath)
const mediaMessage = new wxopensdk.WXMediaMessage()
mediaMessage.title = "example.pdf"
mediaMessage.mediaObject = fileObject
const req = new wxopensdk.SendMessageToWXReq()
req.callbackAbility = kDemoEntryAbility
req.scene = wxopensdk.SendMessageToWXReq.WXSceneSession
req.message = mediaMessage
const accepted = await this.wxApi.sendReq(getContext(this) as common.UIAbilityContext, req)
accepted 表示请求是否成功发起,最终结果以 OpenSDK 回调为准。鸿蒙公共对象未声明统一固定的文件大小字段,实际结果还取决于 SDK、微信客户端版本和运行时校验。
六、网络视频类型分享示例
WXVideoObject 用于分享网络视频,从 OpenSDK 1.0.12 起提供。
| 字段 | 类型 | 含义 | 备注 |
|---|---|---|---|
| videoUrl | string | 视频网页 URL | 与 videoLowBandUrl 至少填写一个;不超过 10KB |
| videoLowBandUrl | string | 低带宽视频网页 URL | 与 videoUrl 至少填写一个;不超过 10KB |
const videoObject = new wxopensdk.WXVideoObject()
videoObject.videoUrl = "https://example.com/video"
const mediaMessage = new wxopensdk.WXMediaMessage()
mediaMessage.title = "视频标题"
mediaMessage.description = "视频描述"
mediaMessage.mediaObject = videoObject
const req = new wxopensdk.SendMessageToWXReq()
req.callbackAbility = kDemoEntryAbility
req.scene = wxopensdk.SendMessageToWXReq.WXSceneSession
req.message = mediaMessage
this.wxApi.sendReq(getContext(this) as common.UIAbilityContext, req)
七、本地视频类型分享示例
WXVideoFileObject 用于分享本地视频,从 OpenSDK 1.0.12 起提供,目前只支持分享到朋友圈。
| 字段 | 类型 | 含义 | 备注 |
|---|---|---|---|
| fileUri | string | 本地视频 URI | 必填;发送前确认文件存在且 URI 可读 |
const videoPath = getContext(this).getApplicationContext().filesDir + "/example.mp4"
if (!fileIo.accessSync(videoPath, fileIo.AccessModeType.EXIST)) {
return
}
const videoFileObject = new wxopensdk.WXVideoFileObject()
videoFileObject.fileUri = fileUri.getUriFromPath(videoPath)
const mediaMessage = new wxopensdk.WXMediaMessage()
mediaMessage.mediaObject = videoFileObject
const req = new wxopensdk.SendMessageToWXReq()
req.callbackAbility = kDemoEntryAbility
req.scene = wxopensdk.SendMessageToWXReq.WXSceneTimeline
req.message = mediaMessage
this.wxApi.sendReq(getContext(this) as common.UIAbilityContext, req)
八、音乐视频类型分享示例
WXMusicVideoObject(WXMediaMessage.IMediaObject 的派生类,用于描述一个音乐视频对象),openSdk 1.0.21 及以上版本支持。
| 字段 | 类型 | 含义 | 备注 |
|---|---|---|---|
| musicUrl | string | 音频网页的 URL 地址 | 必填,不能为空,限制长度不超过 10KB |
| musicDataUrl | string | 音频数据的 URL 地址 | 必填,不能为空,限制长度不超过 10KB |
| singerName | string | 歌手名 | 必填,不能为空,限制长度不超过 1KB |
| duration | Int | 歌曲时长 | 必填,单位:毫秒 |
| songLyric | string | 歌词 | 建议填写,限制长度不超过 32KB |
| hdAlbumThumbFilePath | string | 高清专辑图本地文件路径 | 选填,文件名限制长度不超过 1KB, 文件限制长度不超过 1MB |
| albumName | string | 音乐专辑名 | 选填 |
| musicGenre | string | 音乐流派 | 选填,限制长度不超过 1KB |
| issueDate | Long | 发行时间 Unix 时间戳 | 选填,单位:秒 |
| identification | string | 音乐标识符 | 建议填写,用户在微信音乐播放器跳回应用时会携带该参数,可用于唯一标识一首歌,微信侧不理解,限制长度不超过 1KB |
| hdAlbumThumbFileHash | string | 高清专辑封面图 SHA256 | 用于签名,详情可见 OpenSDK 分享签名开发手册 |
| musicOperationUrl | string | 操作音乐的url | 选填,限制长度不超过 10KB |
| musicVipInfo | WXMusicVipInfo | 音乐Vip信息 | 选填 |
WXMusicVipInfo (WXMediaMessage.IWXMusicVipObject 的派生类,用于描述一个音乐vip对象),openSdk 1.0.21 及以上版本支持。
| 字段 | 类型 | 含义 | 备注 |
|---|---|---|---|
| musicId | WXMusicVipInfo | 付费音乐id | 必填,不能为空,限制长度不超过 10KB |
const musicVideo = new wxopensdk.WXMusicVideoObject();
musicVideo.musicUrl = "https://i.y.qq.com/v8/playsong.html?hosteuin=NK6koioPNK4A&sharefrom=toplist&from_id=427&from_idtype=10005&from_name=JUU2JTk2JUIwJUU2JUFEJThDJUU2JUE2JTlDJTIwMjAyMS0wMS0yNSUyMCVFNyVBQyVBQzE3JUU1JUIwJThGJUU2JTk3JUI2&songid=293695482&songmid=&type=0&platform=(10rpl)&appsongtype=(11rpl)&_wv=1&source=qq&appshare=iphone&media_mid=0042Cw752gLfrn&ADTAG=wxfshare";
musicVideo.musicDataUrl = "http://c6.y.qq.com/rsc/fcgi-bin/fcg_pyq_play.fcg?songid=0&songmid=002LNOds0rYvpK&songtype=1&fromtag=46&uin=915334952&code=6cbf3";
musicVideo.songLyric = "";
musicVideo.singerName = "来自QQ音乐新歌榜";
musicVideo.albumName = "album_xxx";
musicVideo.musicGenre = "流行歌曲";
musicVideo.issueDate = 1610713585;
musicVideo.identification = "has_mv_identification";
musicVideo.duration = 207 * 1000;
musicVideo.musicOperationUrl = "https://www.qq.com";
const filePath = getContext(this).getApplicationContext().filesDir + "/test_image.jpg";
musicVideo.hdAlbumThumbFilePath = filePath;
const mediaMessage = new wxopensdk.WXMediaMessage()
mediaMessage.mediaObject = musicVideo
mediaMessage.title = "星辰大海"
mediaMessage.description = "来自网页"
const thumbData = await getContext(this).resourceManager.getMediaContent($r("app.media.thumb_img"))
const thumbPixel = image.createImageSource(thumbData.buffer).createPixelMapSync({ desiredSize: { width: 60, height: 60 } })
const thumbDataCompressed = await image.createImagePacker().packToData(thumbPixel, { format: "image/png", quality: 100 })
mediaMessage.thumbData = new Uint8Array(thumbDataCompressed)
const req = new wxopensdk.SendMessageToWXReq()
req.callbackAbility = kDemoEntryAbility
req.scene = this.currentScene
req.message = mediaMessage
const finished = await this.wxApi.sendReq(getContext(this) as common.UIAbilityContext, req)
console.log("send request finished: ", finished)
音乐视频类型使用说明:
- 音乐视频类型分享,请开发者特别注意必填的字段有
- WXMediaMessage.title:歌曲名称
- WXMusicVideoObject.musicUrl:音频网页的 URL 地址
- WXMusicVideoObject.musicDataUrl:音频数据的 URL 地址
- WXMusicVideoObject.singerName:歌手名
- WXMusicVideoObject.duration:歌曲时长,单位为毫秒