组件接口 | 微信开放文档

# 组件接口

名称	功能说明
订阅组件 subscribe	订阅组件可配置到小程序页面上，可对一场未开播的直播进行单次订阅，开播时会自动下发开播提醒给用户
挂件组件 pendant	挂件可配置在小程序页面上，用户可通过挂件进入当前小程序对应直播间
获取单次订阅状态 getSubscribeStatus	在直播组件版本 1.3.0 及以上版本通过该接口获取直播间单次订阅状态
获取直播状态 getLiveStatus	首次获取立马返回直播状态，往后间隔1分钟或更慢的频率去轮询获取直播状态
获取用户openid参数getOpenid	在直播组件版本 1.3.0 及以上版本通过该接口获取用户openid参数
获取分享卡片链接参数getShareParams	在直播组件版本 1.3.0 及以上版本通过该接口获取以下参数，开发者可以根据这些参数建立用户、直播间、商品之间的映射关系
直播小窗控制参数 close_picture_in_picture_mode	通过参数设置是否关闭小窗
携带参数（直播间到商详页面，从群分享卡片返回直播间）	直播组件版本 1.3.0 及以上支持携带以下参数，可用这些参数建立用户、直播间、商品之间的映射关系。

# 1. 【订阅】组件（注：若要使用该组件，需在主包/分包先引入直播组件）

功能解释：订阅组件可配置到小程序页面上，可对一场未开播的直播进行单次订阅，开播时会自动下发开播提醒给用户，无需开发者额外开发

组件使用：如果需要在直播页以外小程序其他页面也有同样的开播提醒的功能，可以引入【订阅】组件 subscribe（开播前才会显示，直播开始后自动消失该组件）；需在 page 页面（如 home 页面）的 home.json 引用订阅组件，可通过 stopPropagation 属性控制是否阻止事件冒泡（默认不阻止事件冒泡，stopPropagation 为 false）。

# 示例代码如下：

{
    "usingComponents": {
        "subscribe": "plugin-private://wx2b03c6e691cd7370/components/subscribe/subscribe"
    }
}

然后便可在 home.wxml 里使用订阅组件，其中直播房间 id 可通过下面获取直播房间列表 API 获取。同时，订阅组件支持自定义颜色和大小以及携带自定义参数，参数说明如下：

room-id：表示房间号，类型为 Number（默认为0）
width：表示宽度，类型为 Number（默认为120）
height：表示高度，类型为 Number（默认为41）
font-size：表示字号，类型为 Number（默认为17）
color：表示字体颜色，类型为 String（默认为'FFFFFF'）
background-color：表示背景色，类型为 String（默认为'#6467F0'）
custom-params：表示自定义参数，类型为 String（默认为空）
stop-propagation：表示阻止事件冒泡，类型为 Boolean（默认为false，不阻止事件冒泡）

// 传参
let roomId = 1
let width = 120
let height = 41
let fontSize = 17
let color = '#FFFFFF'
let backgroundColor = '#6467F0'
let customParams = encodeURIComponent(JSON.stringify({ path: 'pages/index/index', pid: 1 })) // 开发者在订阅组件上携带自定义参数（如示例中的path和pid参数），后续可以在 App onShow 生命周期的 options 里获取（上限600个字符，超过部分会被截断）
this.setData({
    width,
    height,
    fontSize,
    color,
    backgroundColor,
    customParams
})

// 监听订阅事件用于获取订阅状态
onSubscribe(e) {
    console.log('房间号：', e.detail.room_id)
    console.log('订阅用户openid', e.detail.openid)
    console.log('是否订阅', e.detail.is_subscribe)
}

<subscribe
    room-id="{{roomId}}"
    width="{{width}}"
    height="{{height}}"
    font-size="{{fontSize}}"
    color="{{color}}"
    background-color="{{backgroundColor}}"
    custom-params="{{customParams}}"
    bindsubscribe="onSubscribe">
</subscribe>

# 2.【获取单次订阅状态】接口（注：若要使用该接口，需在主包/分包先引入直播组件）

接口说明：获取直播间单次订阅状态

调用方法：若要调用【获取单次订阅状态】接口 getSubscribeStatus，需在小程序页面顶部引用【直播组件】 live-player-plugin。

# 示例代码如下：

let livePlayer = requirePlugin('live-player-plugin')

// 获取直播间单次订阅状态
const roomId = xxx // 房间 id
livePlayer.getSubscribeStatus({ room_id: roomId })
    .then(res => {
        console.log('房间号：', res.room_id)
        console.log('订阅用户openid', res.openid)
        console.log('是否订阅', res.is_subscribe)
    }).catch(err => {
        console.log('get subscribe status', err)
    })

# 3. 【获取直播状态】接口（注：若要使用该接口，需在主包/分包先引入直播组件）

接口说明：首次获取立马返回直播状态，往后间隔1分钟或更慢的频率去轮询获取直播状态

# 直播状态说明：

101 直播中：表示主播正常开播，直播正常的状态
102 未开始：表示主播还未开播
103 已结束：表示在直播端点击【结束】按钮正常关闭的直播，或直播异常 15 分钟后系统强制结束的直播
104 禁播：表示因违规受到运营处罚被禁播
105 暂停中：表示在 MP 小程序后台-控制台内操作暂停了直播
106 异常：表示主播离开、切后台、断网等情况，该直播被判定为异常状态，15 分钟内恢复即可回到正常直播中的状态；如果 15 分钟后还未恢复，直播间会被系统强制结束直播
107 已过期：表示直播间一直未开播，且已达到在 MP 小程序后台创建直播间时填写的直播计划结束时间，则该直播被判定为过期不能再开播

调用方法：若要调用【获取直播状态】接口 getLiveStatus，需在小程序页面顶部引用【直播组件】 live-player-plugin。

# 示例代码如下：

let livePlayer = requirePlugin('live-player-plugin')

// 首次获取立马返回直播状态
const roomId = xxx // 房间 id
livePlayer.getLiveStatus({ room_id: roomId })
    .then(res => {
        // 101: 直播中, 102: 未开始, 103: 已结束, 104: 禁播, 105: 暂停中, 106: 异常，107：已过期 
        const liveStatus = res.liveStatus
        console.log('get live status', liveStatus)
    })
    .catch(err => {
        console.log('get live status', err)
    })
// 往后间隔1分钟或更慢的频率去轮询获取直播状态
setInterval(() => {
    livePlayer.getLiveStatus({ room_id: roomId })
        .then(res => {
            // 101: 直播中, 102: 未开始, 103: 已结束, 104: 禁播, 105: 暂停中, 106: 异常，107：已过期 
            const liveStatus = res.liveStatus
            console.log('get live status', liveStatus)
        })
        .catch(err => {
            console.log('get live status', err)
        })
}, 60000)

# 4. 【获取用户openid参数】接口（注：若要使用该接口，需在主包/分包先引入直播组件）

接口说明：在直播组件版本 1.3.0 及以上版本通过该接口获取用户openid参数。

调用方法：若要调用【获取用户openid参数】接口 getOpenid，需在小程序页面顶部引用【直播组件】 live-player-plugin。

# 示例代码如下：

let livePlayer = requirePlugin('live-player-plugin')

App({
    onShow(options) {
        livePlayer.getOpenid({ room_id: [直播房间id] }) // 该接口传入参数为房间号
            .then(res => {
                console.log('get openid', res.openid) // 用户openid
            }).catch(err => {
                console.log('get openid', err)
            })
    }
})

# 5. 【获取分享卡片链接参数】接口（注：若要使用该接口，需在主包/分包先引入直播组件）

接口说明：由于基础库数据安全策略，通过 App onShow（需在主包引入直播组件）或者 Page onShow（需在分包引入直播组件）生命周期里的query无法获取直播间分享卡片链接参数。在直播组件版本 1.3.0 及以上版本通过该接口获取以下参数，开发者可以根据这些参数建立用户、直播间、商品之间的映射关系。

分享卡片进入直播间：房间号 room_id + 进入者 openid + 分享者 share_openid + 开发者自定义参数 custom_params

调用方法：若要调用【获取分享卡片链接参数】接口 getShareParams，需在小程序页面顶部引用【直播组件】 live-player-plugin。

# 示例代码如下：

let livePlayer = requirePlugin('live-player-plugin')

App({
    onShow(options) {
        // 分享卡片/订阅消息/扫码二维码/广告/朋友圈等场景才能调用getShareParams接口获取以下参数
        const sceneList = [1007, 1008, 1014, 1044, 1045, 1046, 1047, 1048, 1049, 1073, 1154, 1155]
        if (sceneList.includes(options.scene)) {
            livePlayer.getShareParams()
                .then(res => {
                    // 房间号
                    console.log('get room id', res.room_id) 
                    // 用户openid
                    console.log('get openid', res.openid) 
                    // 分享者openid，分享卡片进入场景才有
                    console.log('get share openid', res.share_openid) 
                    // 开发者在跳转进入直播间页面时，页面路径上携带的自定义参数，这里传回给开发者
                    console.log('get custom params', res.custom_params) 
                }).catch(err => {
                    console.log('get share params', err)
                })
        }
    }
})