UI组件概览

从v3.8+版本开始，小程序SDK整体重写，功能更加强大和灵活，支持UI模式和无UI模式集成到项目；

UI模式基于SDK提供的<xylink-room />组件快速实现会议功能开发，支持自动布局和自定义布局，功能丰富且集成方便快捷；
无UI模式基于SDK提供的元数据自行实现多人音视频通话功能，整体灵活度更高，支持任意框架集成；

此篇文档将介绍UI模式下<xylink-room />组件的配置和使用方式；

提示

微信开发者工具不支持推/拉流，如需要查看视频画面，请使用真机调试；

组件介绍

<xylink-room /> 组件是基于 <live-pusher /> 和 <live-player /> 实现的用于多人音视频通话的自定义组件，其主要用于多人音视频通话场景下，以横屏的方式展示会议画面；

组件使用

在小程序项目下，每个Page页面存在一个json配置文件，在json文件中引入自定义组件：

// index.json文件中添加组件引用和横屏配置：

{
  ...
  "usingComponents": {
      "xylink-room": "@xylink/xy-mp-sdk/component"
   },
  "pageOrientation": "landscape",
}

在对应的wxml文件中使用组件：

// index.wxml文件中使用组件

<!-- 小鱼小程序SDK UI组件 -->
<xylink-room
  template="{{ template }}"
  beauty="{{ 5 }}"
  muted="{{ muted }}"
  camera="{{ camera }}"
  devicePosition="{{ devicePosition }}"
  id="xylink"
  bindonRoomEvent="onRoomEvent"
/>

组件属性

<xylink-room /> 组件可以配置以下的属性：

属性值	类型	可选值	说明	备注
template	object	见下方：template配置说明	布局模式设置，详情见template配置说明非必填默认为：`{ layout: "auto", detail: [] }`
beauty	number	0-9	美颜级别非必填默认为 5，不支持动态设置；
whiteness	number	0-9	美白级别非必填默认为 5，不支持动态设；
muted	boolean	true/false	是否静音麦克风非必填默认为 false，代表开启麦克风； true代表关闭麦克风支持动态设置；
mutedAtuoOperate	boolean	true/false	是否UI组件内部自动调用开启/关闭摄像头方法非必填默认是true，开启自动调用，false代表关闭，则需要业务上自行调用unmuteVideo/muteVideo方法
camera	boolean	true/false	是否开启摄像头非必填默认为 false，代表关闭摄像头； true代表开启摄像头支持动态设置；
devicePosition	string	front/back	使用前置/后置摄像头采集本地视频流；非必填 front 代表前置摄像头，默认值； back 代表后置摄像头；不支持动态设置，如果需要切换摄像头，调用 `switchCamera`方法；
waitingImage	string	null	视频被挂起时的等待画面；非必填默认可不用配置，内部设置了挂起时的图片；	如果设置，请确保图片的正确访问，否则会导致推流失败；
backgroundImage	string	null	当前画面背景图；支持网络地址和本地地址，本地图片是相对于SDK内部组件的位置为起始路径；非必填默认可不配置，内置了画面背景图片；	如果设置，请确保图片的正确访问；
onRoomEvent	function	N/A	必填监听房间内部的事件，详情见API概览-事件概览；

Template配置说明

template字段用来控制布局模式（layout）和布局模版数据（detail），是控制组件如何显示每个参会者大小、位置、分辨率画面等重要配置，包含以下配置内容：

参数	类型	可选值	说明	版本
layout	string	'auto' \| 'custom'	默认值为'auto'，指定布局模式；auto代表自动布局，custom代表自定义布局；
detail	obect[]	-	自定义布局模式下，配置参会者位置、分辨率、用户名称，支持动态设置; 自动布局不需要配置此字段；
└position	[number, number, number, number] 或 [string, string, string, string]	-	必填指定参会位置（x, y）和尺寸信息（width, height）; 类型是数字，数值对应的单位分别是：[x, y, width, height]，其中：x和width单位是: vw，y和height是: vh；类型是字符串，则用户自定义样式单位，例如可以指定"PX"、"px"、"vw"、"rpx"；
└callNumber	string	-	必填指定参会者的呼叫号码，此数据可以从roster事件中获取；
└name	string	-	必填指定参会者名称，此数据可以从roster事件中获取；
└quality	string	'normal' \| 'high' \| 'hd'	必填指定参会者画面清晰度，建议将大屏画面设置为 high，小屏画面设置为 normal，content 设置为 hd；
└isContent	boolean	-	必填指定当前位置是否是 Content 共享内容，从roster事件中的 isContent获取状态；
└style	string	-	非必填自定义样式，填写style样式字符串，用于指定当前画面效果；
└stateText	{ wating: string; videoMute: string; }	-	非必填自定义控制参会者视频请求中和视频关闭显示文本；

Template示例

自动布局下，默认只需要配置layout为auto即可，不需要配置detail模版详细数据：

// 自动布局
template: {
    layout: "auto",
    // 请注意，自动布局不需要配置detail
    detail: [],
}

自定义布局下，需要指定layout为custom，detail配置如下：

// 自定义布局
template: {
    layout: "custom",
    detail: [
        {
            position: [0, 0, 75, 90],
            callNumber: "+86-10098123862",
            name: "参会者1",
            // 大画面，质量设置为high            
            quality: "high",
            isContent: false,
            style: ""
        },
        {
            position: [75, 0, 25, 30],
            callNumber: "+86-10098123862",
            name: "参会者2",
            // 小画面，质量设置为normal
            quality: "normal",
            isContent: false,
            style: ""
        },        
        {
            // content内容，质量设置为HD
            position: [75, 30, 25, 30],
            // 此处和参会者2 callNumber相同，因为当前画面是内容共享，标记isContent为true
            callNumber: "+86-10098123862",
            name: "参会者2",
            quality: "hd",
            isContent: true,
            // 标记篮框
            style: "border: 2px solid #44b5ff;"            
        },
    ]
}

组件事件

UI组件模式下，组件通过属性bindonRoomEvent返回内部roomEvent事件；

在wxml文件中引用组件，并绑定事件函数：

<xylink-room ... bindonRoomEvent="onRoomEvent" />

在page页面的js文件中处理事件函数：

// js中定义接收函数
onRoomEvent(event) {
    const { type, detail } = event.detail;
    
  // 详细type见事件列表
}

详细的事件列表见：API概览-事件概览

2023-07-18 11:13:53