# 鸿蒙应用开发手册

本文介绍如何在鸿蒙 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:歌曲时长,单位为毫秒
文档变更日志(1条)
2026 年 09 月 02 日
新增了音乐类型的分享