tencent cloud

组件介绍

<trtc-room> 标签是基于 <live-pusher> 和 <live-player> 实现的用于 TRTC 互通的自定义组件，支持多种应用场景：

视频通话&语音通话（scene = "rtc"）

• 视频通话场景，支持 720P、1080P 高清画质。
• 视频通话场景，支持48kHz全频带，支持双声道。
• 单个房间最多支持300人同时在线，最高支持50人同时发言。
• 适用场景：1对1视频通话、300人视频会议、在线问诊、远程面试、视频客服、在线狼人杀等。
• 使用方法：需要您将 <trtc-room> 的 scene 属性设置为 rtc。

互动直播&语音聊天室（scene = "live"）

• 支持十万人级别观众同时播放，播放延时低至1000ms。
• 支持平滑上下麦，切换过程无需等待，主播延时小于300ms。
• 适用场景：视频低延时直播、十万人互动课堂、视频相亲、在线教育、远程培训、超大型会议等。
• 使用方法：使用时需要您将 <trtc-room> 的 scene 属性设置为 live。

API 概览

基础方法

发布订阅

视图控制

背景音乐

消息收发
消息收发功能需开通 即时通信 IM 服务并将 属性表 中的 enableIM 选项设置为 true 才有效。

其他功能

属性表

<trtc-room> 只有一个 config 属性，通过该属性可以传入以下参数：

示例代码：

 // index.wxml
<trtc-room id="trtcroom" config="{{trtcConfig}}"></trtc-room>

// videocall.js
trtcConfig = {
  sdkAppID: '1401000123', // 开通实时音视频服务创建应用后分配的 SDKAppID
  userID: 'test_user_001', // 用户 ID，可以由您的帐号系统指定
  userSig: 'xxxxxxxxxxxx', // 身份签名，相当于登录密码的作用
  template: 'grid', // 画面排版模式
}

组件方法

selectComponent()

您可以通过小程序提供的 this.selectComponent() 方法获取组件实例。

示例代码：

let trtcRoomContext = this.selectComponent('#trtcroom')
trtcRoomContext.enterRoom({roomID: 2233})

on(EventCode, handler, context)

说明：

用于监听组件派发的事件，详细事件请参考 事件表。

注意：

请在调用 enterRoom 前监听事件，避免漏掉组件派发的事件。

参数：

返回值：

无

示例代码：

function onLocalJoin(event) {
  // 本地进房成功
}
trtcRoomContext.on(trtcRoomContext.EVENT.LOCAL_JOIN, onLocalJoin, this)

off(EventCode, handler)

说明：

取消事件监听。

参数：

返回值：

无

示例代码：

function onLocalJoin(event) {
  // 本地进房成功
}
trtcRoomContext.off(trtcRoomContext.EVENT.LOCAL_JOIN, onLocalJoin)

enterRoom(params)

说明：
进入房间，调用参数必须传入 roomID。

参数：

返回值：
Promise

示例代码：

trtcRoomContext.enterRoom({roomID: 2233}).catch((error)=>{
  // 进入房间失败
  // 注意：进入房间成功通过事件 LOCAL_JOIN 通知
})

exitRoom()

说明：

停止推流和取消订阅所有远端音视频，并退出房间。

注意：

由于微信最新版本小程序引擎限制，请勿在 onHide() 回调函数中调用 exitRoom()，会导致各种状态紊乱的 bug。

参数：

无

返回值：

Promise

示例代码：

trtcRoomContext.exitRoom().then(()=>{
  // 退出房间成功
})

publishLocalVideo()

说明：

发布本地视频，即开启本地摄像头采集并启动视频推流。一般要配合 publishLocalAudio() 一起使用。

参数：

无

返回值：

Promise

示例代码：

trtcRoomContext.publishLocalVideo().then(()=>{
  // 发布成功
})

unpublishLocalVideo()

说明：

取消发布本地视频，关闭本地视频推流。

参数：

无

返回值：

Promise

示例代码：

trtcRoomContext.unpublishLocalVideo().then(()=>{
  // 取消发布成功
})

publishLocalAudio()

说明：

发布本地音频，即开启本地麦克风采集并启动音频推流。如果是纯音频沟通场景，则不需要调用publishLocalVideo()。

参数：

无

返回值：

Promise

示例代码：

trtcRoomContext.publishLocalAudio().then(()=>{
  // 发布成功
})

unpublishLocalAudio()

说明：

取消发布本地音频，关闭本地音频推流。

参数：

无

返回值：

Promise

示例代码：

trtcRoomContext.unpublishLocalAudio().then(()=>{
  // 取消发布成功
})

subscribeRemoteVideo(params)

说明：

订阅远端用户的视频流并进行播放。

参数：

返回值：

Promise

示例代码：

// 有可以订阅的远端视频流
function onRemoteVideoAdd(event) {
  trtcRoomContext.subscribeRemoteVideo({
    userID: event.data.userID,
    streamType: event.data.streamType
  }).then(()=>{
    // 订阅成功
  })
}

trtcRoomContext.on(trtcRoomContext.EVENT.REMOTE_VIDEO_ADD, onRemoteVideoAdd)

unsubscribeRemoteVideo(params)

说明：

取消订阅远端用户的视频并停止播放。

参数：

返回值：

Promise

示例代码：

// 有一路远端视频流关闭了
function onRemoteVideoRemove(event) {
  trtcRoomContext.unsubscribeRemoteVideo({
    userID: event.data.userID,
    streamType: event.data.streamType
  }).then(()=>{
    // 取消订阅成功
  })
}
trtcRoomContext.on(trtcRoomContext.EVENT.REMOTE_VIDEO_REMOVE, onRemoteVideoRemove)

subscribeRemoteAudio(params)

说明：

订阅远端用户的音频并进行播放。

参数：

返回值：

Promise

示例代码：

// 有可以订阅的远端音频流
function onRemoteAudioAdd(event) {
  trtcRoomContext.subscribeRemoteAudio({
    userID: event.data.userID
  }).then(()=>{
    // 订阅成功
  })
}

trtcRoomContext.on(trtcRoomContext.EVENT.REMOTE_AUDIO_ADD, onRemoteAudioAdd)

unsubscribeRemoteAudio(params)

说明：

取消订阅远端用户的音频并停止播放 。

参数：

返回值：

Promise

示例代码：

// 有一路远端音频流关闭了
function onRemoteAudioRemove(event) {
  trtcRoomContext.unsubscribeRemoteAudio({
    userID: event.data.userID
  }).then(()=>{
    // 取消订阅成功
  })
}

trtcRoomContext.on(trtcRoomContext.EVENT.REMOTE_AUDIO_REMOVE, onRemoteAudioRemove)

switchCamera()

说明：

切换本地前后摄像头。

参数：

无

返回值：

无

示例代码：

trtcRoomContext.switchCamera()

getRemoteUserList()

说明：

获取远端用户列表。

参数：

无

返回值：

Array[Object]

示例代码：

let userList = trtcRoomContext.getRemoteUserList()
// 数据格式示例
// userList = [
//   {
//     userID:'xxx',       // 该用户 ID 
//     hasMainVideo: true, // 该用户是否有主流视频
//     hasMainAudio: true, // 该用户是否有主流音频
//     hasAuxVideo: false  // 该用户是否有辅流（屏幕分享）视频
//   }
//   ...
// ]

enterFullscreen(params)

说明：

将远端视频切换为全屏播放，辅路（即屏幕分享）的画面一般适合全屏播放。

参数：

返回值：

Promise

示例代码：

trtcRoomContext.enterFullscreen({
  userID: 'xxx',
  streamType: 'main'
}).then((event)=>{
  // 全屏成功
}).catch((event)=>{
  // 全屏失败
})

exitFullscreen(params)

说明：

取消远端视频的全屏模式。

参数：

返回值：

Promise

示例代码：

trtcRoomContext.exitFullscreen({
  userID: 'xxx',
  streamType: 'main'
}).then((event)=>{
  // 退出全屏成功
}).catch((event)=>{
  // 退出全屏失败
})

setViewOrientation(params)

说明：

设置指定远端画面的显示方向。

参数：

返回值：

Promise

示例代码：

trtcRoomContext.setViewOrientation({
  userID: 'xxx',
  streamType: 'main',
  orientation: 'vertical'
}).then((event)=>{
  // 设置成功
})

setViewFillMode(params)

说明：

设置指定远端画面的填充模式。

参数：

返回值：

Promise

示例代码：

trtcRoomContext.setViewFillMode({
  userID: 'xxx',
  streamType: 'main',
  fillMode: 'contain'
}).then((event)=>{
  // 设置成功
})

setViewVisible(params)

说明：
显示或者隐藏某一路视频画面。

注意：

该方法仅在 template:"custom" 时才有效。

参数：

返回值：

Promise

示例代码：

trtcRoomContext.setViewVisible({
  userID: 'xxx',
  streamType: 'main',
  isVisible: true
}).then((event)=>{
  // 设置成功
})

setViewRect(params)

说明：

设置指定视频画面的坐标和尺寸。

注意：

该方法仅在 template:"custom" 时才有效。

参数：

返回值：

Promise

示例代码：

trtcRoomContext.setViewRect({
  userID: 'xxx',
  streamType: 'main',
  xAxis: '480rpx', 
  yAxis: '160rpx', 
  width: '240rpx', 
  height: '320rpx',
}).then((event)=>{
  // 设置成功
})

setViewZIndex(params)

说明：

设置指定视频画面的层级。

注意：

• 该方法仅在 template:"custom" 时才有效。
• 该方法仅在小程序同层模式下有效，微信7.0.8以上的版本支持同层模式。

参数：

返回值：

Promise

示例代码：

trtcRoomContext.setViewZIndex({
  userID: 'xxx',
  streamType: 'main',
  zIndex: 10
}).then((event)=>{
  // 设置成功
})

playBGM(params)

说明：

播放背景音乐。背景音乐会同麦克风采集的人声混合在一起发布到云端，即“背景混音”。

参数：

返回值：

Promise

示例代码：

trtcRoomContext.playBGM({
  url: 'https://a.xxx.com/bgm.mp3' 
}).then(()=>{
    // 播放成功
}).catch(()=>{
    // 播放失败
})

stopBGM()

说明：

停止播放背景音乐。

参数：

无

返回值：

无

示例代码：

trtcRoomContext.stopBGM()

pauseBGM()

说明：

暂停播放背景音乐。

参数：

无

返回值：

无

示例代码：

trtcRoomContext.pauseBGM()

resumeBGM()

说明：

恢复播放背景音乐。

参数：

无

返回值：

无

示例代码：

trtcRoomContext.resumeBGM()

setBGMVolume(params)

说明：

设置混音中背景音乐的音量。

参数：

返回值：

无

示例代码：

trtcRoomContext.setBGMVolume({
  volume: 0.5
})

setMICVolume(params)

说明：

设置混音中麦克风采集的音量。

参数：

返回值：

无

示例代码：

trtcRoomContext.setMICVolume({
  volume: 0.5
})

snapshot(params)

说明：

截取指定远端视频或本地视频的图像，并保存到系统相册中。

参数：

返回值：

无

示例代码：

// 截取远端用户视频图像
trtcRoomContext.snapshot({
  userID: 'xxx',            // 远端用户 ID
  streamType: 'main'        // 远端用户流类型
}).then((event)=>{
  // 截图成功
})

// 截取本地用户视频图像
trtcRoomContext.snapshot({
  userID: 'xxx',            // 本地用户 ID
  streamType: 'main'        // 本地用户流类型仅支持 'main'：主流 
}).then((event)=>{
  // 截图成功
})

sendC2CTextMessage(params)

说明：

发送 C2C（即定向发给某个人）文本消息，需开通 即时通信 IM 服务并将 属性表 中的 enableIM 选项设置为 true 才有效。

参数：

返回值：

Promise

示例代码：

trtcRoomContext.sendC2CTextMessage({
  userID: 'xxx',
  message: 'Hello!'
})

sendC2CCustomMessage(params)

说明：

发送 C2C 自定义消息，自定义消息可以用来发送控制信令（例如邀请发言、申请上麦等）。
需开通 即时通信 IM 服务并将 属性表 中的 enableIM 选项设置为 true 才有效。

参数：

payload 支持三个参数：

返回值：

Promise

示例代码：

trtcRoomContext.sendC2CCustomMessage({
  userID: 'xxx',
  payload: {
    data: '自定义消息的数据字段',
    description: '自定义消息的说明字段',
    extension: '自定义消息的扩展字段'
  } 
})

sendGroupTextMessage(params)

说明：

发送群组文本消息，需开通 即时通信 IM 服务并将 属性表 中的 enableIM 选项设置为 true 才有效。

参数：

返回值：

Promise

示例代码：

trtcRoomContext.sendGroupTextMessage({
  roomID: 'xxx', // 房间 ID
  message: 'Hello!'
})

sendGroupCustomMessage(params)

说明：

发送群组自定义消息，需开通 即时通信 IM 服务并将 属性表 中的 enableIM 选项设置为 true 才有效。

参数：

payload 支持三个参数：

返回值：

Promise

示例代码：

trtcRoomContext.sendGroupCustomMessage({
  roomID: 'xxx', // 房间 ID
  payload: {
    data: '自定义消息的数据字段'，
    description: '自定义消息的说明字段'，
    extension: '自定义消息的扩展字段'
  }
})

事件表

## 事件表 通过组件实例的 EVENT 属性可以获取到事件常量字段，示例：

let EVENT = trtcRoomContext.EVENT
trtcRoomContext.on(EVENT.REMOTE_VIDEO_ADD,(event)=>{
    // 远端视频流添加事件，当远端用户发布视频流后会收到该通知
})

// 接收 IM 消息
trtcRoomContext.on(EVENT.IM_MESSAGE_RECEIVED,(event)=>{
  let messageEvent = event.data
  // 收到推送的单聊、群聊、群提示、群系统通知的新消息，可通过遍历 messageEvent.data 获取消息列表数据并渲染到页面
  // messageEvent.data - 存储 Message 对象的数组
})

错误码

ERROR 事件触发时会返回响应的错误码，错误码含义如下

let EVENT = trtcRoomContext.EVENT
trtcRoomContext.on(EVENT.ERROR,(event)=>{
  console.log(event.data.code)
})