拉流和自动布局

使用小鱼易连Web SDK加入多人音视频会议后，需要展示参会者的画面。SDK 提供两种布局方式：自动布局和自定义布局，分别适用于不同的需求。

布局方式

优势

局限

自动布局

集成简单快捷；
自动处理画面数据流和布局计算；
提供丰富的内置功能：

宫格模式、演讲者模式、Content模式
支持桌面端和移动端布局
翻页查看更多画面
主会场模式
轮询多画面功能
...

不支持业务扩展布局模式

自定义布局

提供参会者元数据，支持自定义画面位置、分辨率、旋转角度等；
灵活控制拉流数量和布局计算；

需要自行处理参会者的请流、布局计算等逻辑；
开发难度相对较大；

本文将重点介绍如何使用小鱼易连 Web SDK 进行自动布局，快速完成多人会议画面的接入和展示。

功能说明

自动布局：SDK 提供了桌面端和移动端浏览器下的布局模板，会基于参会人数和会控控制状态自动请求画面数据流并计算布局。并通过layout事件上报布局结果数据，开发者只需根据该数据进行渲染画面即可。

自动布局下，单页最多支持展示 9 个画面，超过 9 人的会议仅接收音频。移动端最多支持 7 个画面；

桌面端和移动端浏览器下支持的布局模型如下所示；

桌面浏览器布局模型

移动端浏览器布局模型

备注：

L 表示本地画面，P 表示参会者画面，Q 表示视频质量，P 为优先级；
每路画面以 16:9 比例显示，容器的比例计算基于此，例如桌面端宫格2画面布局，对应的容器比例是：(16*2)/9，以确保画面填充容器的最大高度或宽度，避免出现上下左右空白区域；

功能示意图

实现方法

1. 配置布局模式和容器

通过 XYRTC.createClient 创建客户端时：

配置 layout: "AUTO"，即开启自动布局模式；
配置 container.elementId 字段指定自动布局容器信息，默认使用body容器计算；
配置 container.offset 字段指定自动布局容器上、下、左、右的偏移值，默认是0，类似样式中的padding效果，单位是px；

const XYClient = XYRTC.createClient({
  ...
  layout: 'AUTO',
  container: {
    // 配置显示容器节点 ID
    elementId: 'meeting',
    offset: [0, 0, 0, 0]
  }
});

2. 监听布局容器尺寸信息

监听 screen-info 事件，实时获取显示容器的大小，支持响应屏幕和容器大小变化；

// AUTO模式回调数据，推送最新的Layout容器大小信息
XYClient.on('screen-info', (e) => {
  console.log('screen info: ', e);

  // 以style样式的形式更新到显示容器上，见下示意图
  // 此处使用JS处理样式更新
  updateLayoutContainerStyle(e);
});

// 处理容器样式函数
const updateLayoutContainerStyle = (style) => {
  const container = document.getElementById('layout');

  container.style.width = `${style.rateWidth}px`;
  container.style.height = `${style.rateHeight}px`;
};

示意图：

3. 监听布局列表数据并渲染画面

当参会人员的状态或数量发生变化时，SDK 会自动拉取画面流并计算布局。开发者通过监听 layout 事件获取布局数据，进行画面渲染。

每一路参会者画面在初始渲染时需要调用一次 setVideoRenderer 方法，用来绑定渲染的容器信息，由SDK内部管理渲染操作，后续如果 id 没有变化，则无需重新调用；

提示

1、此处使用JS+HTML演示集成流程

2、正式开发时，建议使用React、Vue等框架实现，更便捷，可参考Demo示例程序；

let layoutList = [];

// 参会成员布局列表数据，包含参会者基本信息、位置、尺寸、旋转等数据
XYClient.on('layout', (e: ILayout[]) => {
  console.log('layout: ', e);
  
  layoutList = e;
  // 获取成员列表布局数据，直接渲染使用即可
  renderLayoutList();
});

// 此处使用JS+HTML演示集成流程
// 正式开发时，建议使用React、Vue等框架实现，更便捷，可参考Demo示例程序
const renderLayoutList = () => {
  const meetingContainer = document.getElementById('layout');

  layoutList.forEach((item) => {
    const { positionStyle = {}, rotate = {}, id, state } = item;
    const { displayName = '' } = item?.roster || {};
    const layoutItemId = 'wrap-' + id;
    const isExist = document.getElementById(layoutItemId);
    const { width, height, left, top } = positionStyle;
    // Layout外围容器样式
    const layoutItemStyle = `width: ${width}; height: ${height}; left: ${left}; top: ${top}`;
    const isPause = state === 'MUTE';

    // video样式，包含竖屏旋转样式
    let layoutVideoStyle = '';
    for (let key in rotate) {
      layoutVideoStyle += `${key}: ${rotate[key]};`;
    }

    // 判断layout id对应的元素是否已经渲染过
    if (!isExist) {
      // 初始渲染
      const layoutItemString = `
          <div class="layout_item" style="${layoutItemStyle}" id=${layoutItemId}>
            <div class="layout_name">${displayName}</div>
            <div class="layout_pause center ${isPause ? 'show' : 'hidden'}">视频暂停</div>
            <div class="center layout_video">
              <video class="video" style="${layoutVideoStyle}" playsinline autoplay muted></video>
            </div>
          </div>`;

      // 向布局容器中追加新的参会者画面Dom
      meetingContainer.insertAdjacentHTML('beforeend', layoutItemString);
      
      // 不变的情况下，执行一次渲染方法即可
      XYClient.setVideoRenderer(id, layoutItemId);
    } else {
      // 已渲染，更新样式和状态
      const layoutItemEle = document.getElementById(layoutItemId);
      const layoutNameEle = layoutItemEle.querySelector('.layout_name');
      const layoutVideoEle = layoutItemEle.querySelector('.video');
      const layoutPauseEle = layoutItemEle.querySelector('.layout_pause');

      layoutItemEle.style.cssText = layoutItemStyle;
      layoutNameEle.innerHTML = displayName;
      layoutVideoEle.style.cssText = layoutVideoStyle;
      layoutPauseEle.className = `center layout_pause ${isPause ? 'show' : 'hidden'}`;
    }
  });
};

// UI信息
<div id="meeting">
  <div id="layout"></div>
</div>

回调参数类型：ILayout

4. 分页处理

监听 page-info 事件，获取页码信息，并使用

XYClient.on('page-info', (pageInfo: IPageInfo) => {
  console.log('page info: ', pageInfo);
})

const nextPage = async () => {
  await XYClient.setPageInfo(1);
}

// 模拟
<div onClick={nextPage}>下一页</div>

调用完成后，通过第三步获取布局列表数据并渲染即可；

API 参考

2025-01-09 11:01:56

导出PDF文档

事件	是否订阅	描述
layout	必须	监听布局列表数据实时获取拉流和布局的结果数据，开发者使用此列表数据进行渲染视频画面即可；调用 setVideoRenderer 方法渲染视频画面；
page-info	必须	自动布局时上报参会者页码数据

事件	描述
XYRTC.createClient	配置 container 容器信息，SDK 会响应屏幕和容器大小变化，自动调整布局
setPageInfo	翻页查看更多参会者画面
switchLayout	快速切换宫格布局和演讲者布局模式
setLayoutOrientation	设置桌面端布局、移动端横/竖屏布局方式，建议在移动端下响应横竖屏切换时调用
setLayoutConfig	配置共享时宫格布局模式
setVideoRenderer	设置视频播放容器元素，SDK接管控制视频的播放和画面渲染