# 小程序直播-直播挂件组件

## 一、挂件功能背景

为了减轻商家的开发和配置成本，小程序直播提供了直播挂件组件，让商家可以轻松的把直播挂件（直播间入口）挂在当前小程序页面上，为直播间汇聚分散在小程序其他页面的流量；特别是商品详情页这类有规律的页面，组件会自动匹配相关商品的直播间。

## 二、挂件功能说明

**功能解释**：直播间挂件状态系统默认的优先级是：直播中 > 预告 > 精彩片段 > 回放，也可以单独声明只取部分状态，同状态下离当前时间最近的直播间优先。开了官方收录的直播间才会被选取，可避免选取到商家测试的直播间。

**注意**：实现挂件能力需要直播组件更新到 1.3.0 及以上版本。

**组件使用**：商家只需要引入【直播挂件】组件 pendant，声明如下：

```json
{
    "usingComponents": {
        "pendant": "plugin-private://wx2b03c6e691cd7370/components/pendant/pendant"
    }
}
```

**可以被挂的小程序页面类型：**

### 1. 单一页面

针对要挂直播挂件的单一页面（如小程序首页），无需指定参数，默认挂最新房间。

可选参数使用说明如下：

- **type**：表示显示的直播挂件类型，类型为 Number（默认为 0，可选）
- **customParams**：表示自定义参数，类型为 String（默认为空，可选）
- **closePictureInPictureMode**：表示关闭小窗开关，类型为 Number（默认为0，可选）

```javascript
let type = 0 // 0. 显示直播、预告、商品讲解、回放其中之一的挂件；1. 只显示直播的挂件；2. 只显示预告的挂件；3. 只显示商品讲解的挂件；4. 只显示回放的挂件
let customParams = encodeURIComponent(JSON.stringify({ path: 'pages/index/index', pid: 1 })) // 开发者在直播间页面路径上携带自定义参数（如示例中的path和pid参数），后续可以在分享卡片链接和跳转至商详页时获取，详见【获取自定义参数】、【直播间到商详页面携带参数】章节（上限600个字符，超过部分会被截断）
let closePictureInPictureMode = 0 // 是否关闭小窗
this.setData({
    type, // 可选 
    customParams, // 可选
    closePictureInPictureMode, // 可选
})
```

```html
<pendant type="{{type}}" custom-params="{{customParams}}" close-picture-in-picture-mode="{{closePictureInPictureMode}}"></pendant>
```

### 2. 有规律同类型页面

针对有规律同类型页面（如小程序商品详情页），需要同时声明页面路径url及商品key列表参数（这里我们会把通过正常商家在直播间配置的商品来索引，把对应这个商品最新的直播间匹配挂到商详页）。

必填及可选参数使用说明如下：

- **url**：表示页面路径，类型为 String，必填
- **goodsKey**：表示商品key列表，类型为 Array，必填
- **type**：表示显示的直播挂件类型，类型为 Number（默认为 0，可选）
- **customParams**：表示自定义参数，类型为 String（默认为空，可选）
- **closePictureInPictureMode**：表示关闭小窗开关，类型为 Number（默认为0，可选）

```javascript
let url = 'pages/detail/detail?goods_id=1&pid=1', // 小程序商详页路径
let goodsKey = ['pid', 'sid'] // 商品key列表（支持多个key），需要在添加商品时用我们提供的api接口【详见第4节 挂件api接口】传入商品key列表（如示例的'pid', 'sid'）
let type = 0 // 0. 显示直播、预告、商品讲解、回放其中之一的挂件；1. 只显示直播的挂件；2. 只显示预告的挂件；3. 只显示商品讲解的挂件；4. 只显示回放的挂件
let customParams = encodeURIComponent(JSON.stringify({ path: 'pages/index/index', pid: 1 })) // 开发者在直播间页面路径上携带自定义参数（如示例中的path和pid参数），后续可以在分享卡片链接和跳转至商详页时获取，详见【获取自定义参数】、【直播间到商详页面携带参数】章节（上限600个字符，超过部分会被截断）
let closePictureInPictureMode = 0 // 是否关闭小窗
this.setData({
    url, // 必填
    goodsKey, // 必填
    type, // 可选 
    customParams, // 可选
    closePictureInPictureMode, // 可选
})
```

```html
<pendant url="{{url}}" goods-key="{{goodsKey}}" type="{{type}}" custom-params="{{customParams}}" close-picture-in-picture-mode="{{closePictureInPictureMode}}"></pendant>
```

### 3. 指定房间号类型页面
针对要挂指定房间号类型页面，只需要声明房间号参数。

必填及可选参数使用说明如下：

- **roomId**：表示直播房间号，类型为 Number，必填
- **type**：表示显示的直播挂件类型，类型为 Number（默认为 0，可选）
- **customParams**：表示自定义参数，类型为 String（默认为空，可选）
- **closePictureInPictureMode**：表示关闭小窗开关，类型为 Number（默认为0，可选）

```javascript
let roomId = 1, // 直播房间号
let type = 0 // 0. 显示直播、预告、商品讲解、回放其中之一的挂件；1. 只显示直播的挂件；2. 只显示预告的挂件；3. 只显示商品讲解的挂件；4. 只显示回放的挂件
let customParams = encodeURIComponent(JSON.stringify({ path: 'pages/index/index', pid: 1 })) // 开发者在直播间页面路径上携带自定义参数（如示例中的path和pid参数），后续可以在分享卡片链接和跳转至商详页时获取，详见【获取自定义参数】、【直播间到商详页面携带参数】章节（上限600个字符，超过部分会被截断）
let closePictureInPictureMode = 0 // 是否关闭小窗
this.setData({
    roomId, // 必填
    type, // 可选 
    customParams, // 可选
    closePictureInPictureMode, // 可选
})
```

```html
<pendant room-id="{{roomId}}" type="{{type}}" custom-params="{{customParams}}" close-picture-in-picture-mode="{{closePictureInPictureMode}}"></pendant>
```

## 三、挂件样式

目前样式只支持商家定义放在页面上的具体位置，样式和颜色暂不支持修改，如下图：

![](https://res.wx.qq.com/op_res/bwrJyRkzRh68p3x1oUni3PTKW2s7H32spQ3fAP75ZKZkrkphPqYHOMiO_Gcp7gODDqUEJdlMnDcSubIj7pg0MA)

## 四、挂件api接口

- [添加并提审商品](/miniprogram/dev/server/API/livebroadcast/commodity-management/api_addgoods.md)

    > 由于在商详页引用直播挂件时并不需要指定该页面对应的商品ID，而直播挂件搜索直播间展示时需要知道该页面对应的商品，所以引用直播挂件时需要有一种能唯一映射商品的方法。
    而商详页都会有唯一的url，因此商家在添加商品时需指定该url才能唯一映射此商品。
    >
    > goodsKey格式为json数组，其内容是url的参数key，我们将使用此goodsKey对应的url的value来唯一映射此商品，映射方式为：`%path%_%value1%_%value2%_... ==> 此页面商品`  
    例如`"url":"pages/index/index?pid=111&sid=222"`,`"goodsKey": ["pid", "sid"]`，则`%path%_%value1%_%value2%_...`为`pages/index/index_111_222`，其中`pages/index/index_111_222`的唯一性须商家保证。

- [直播挂件设置全局KEY](/miniprogram/dev/server/API/livebroadcast/studio-management/api_setdefault_goodskey.md)
- [直播挂件获取全局KEY](/miniprogram/dev/server/API/livebroadcast/studio-management/api_getdefault_goodskey.md)