帮你快速理解、总结文档立即下载
文档中心>实时音视频>视频会议 SDK>无 UI 集成>搭建多人会议>白板和批注>白板和批注（Web）

白板和批注（Web）

最近更新时间：2026-07-17 20:31:02

我的收藏

本页目录：

本文介绍如何使用 Atomicx API 为自己的会议界面接入白板或屏幕共享批注。
先选择您要实现的功能：
目标
是否需要先开启屏幕共享
接入顺序
白板：在空白画布上书写
不需要
显示区域准备好后，调用 startWhiteboard
屏幕共享批注：在屏幕共享画面上批注
需要
先调用 startScreenShare，再调用 startWhiteboard
说明：
接入屏幕共享批注，不需要先接入独立白板。两种功能都使用 startWhiteboard 创建绘制层，但接入流程彼此独立，按您的业务目标选择其中一种即可。

准备工作

开始前，请确认：
用户状态：用户已经通过 useLoginState 完成登录鉴权，参见 接入概览，并已作为一个房间的房主或成员在房间内，参考 房间管理。
环境依赖：项目已正确安装并引入 tuikit-atomicx-vue3（Vue 3），版本为 6.1.0 或更高
使用 Windows 或 macOS 桌面端的 Chrome、Edge 最新稳定版本。
本文代码中的“显示区域”，就是页面中用来显示白板或共享画面的一个 <div>。为它设置 id 后，将该 id 传给 API 即可。它既决定内容显示在哪里，也决定显示尺寸，不需要额外理解白板内部实现。

接入白板

白板不依赖屏幕共享。准备一个显示区域，并在用户点击“打开白板”时把它的 id 传给 startWhiteboard：
<template>
  <button @click="openWhiteboard">打开白板</button>
  <div id="whiteboard-view" class="content-view" />
</template>

<script setup lang="ts">
import { useWhiteboardState } from 'tuikit-atomicx-vue3/room';

const { startWhiteboard } = useWhiteboardState();

async function openWhiteboard() {
  await startWhiteboard({
    view: 'whiteboard-view',
    canvasColor: '#FFFFFF',
  });
}
</script>

<style scoped>
.content-view {
  position: relative;
  width: 100%;
  height: 600px;
  background: #fff;
}
</style>
调用成功后，当前用户可以在该区域绘制，房间内其他成员会实时看到白板画面。

接入屏幕共享批注

屏幕共享批注是在共享画面上增加一层透明的绘制区域。整个流程只有两步：
1. 把屏幕共享画面显示到页面中的 <div>。
2. 把同一个 <div> 的 id 传给 startWhiteboard，让笔迹覆盖在共享画面上。
以下示例提供“开始共享”和“开启批注”两个按钮：
<template>
  <button @click="shareScreen">开始共享</button>
  <button @click="openAnnotation">开启批注</button>
  <div id="screen-share-view" class="content-view" />
</template>

<script setup lang="ts">
import {
  DeviceStatus,
  useDeviceState,
  useWhiteboardState,
} from 'tuikit-atomicx-vue3/room';

const { screenStatus, startScreenShare } = useDeviceState();
const { startWhiteboard } = useWhiteboardState();

async function shareScreen() {
  await startScreenShare({
    screenAudio: true,
    view: 'screen-share-view',
  });
}

async function openAnnotation() {
  if (screenStatus.value !== DeviceStatus.On) {
    throw new Error('请先开启屏幕共享');
  }

  await startWhiteboard({
    view: 'screen-share-view',
  });
}
</script>

<style scoped>
.content-view {
  position: relative;
  width: 100%;
  height: 600px;
}
</style>

添加绘制工具

白板和屏幕共享批注使用同一套工具 API。将下面的方法连接到您的工具栏按钮即可：
import {
  useWhiteboardState,
  WhiteboardTool,
} from 'tuikit-atomicx-vue3/room';

const {
  setToolConfig,
  undo,
  redo,
  clear,
  snapshot,
} = useWhiteboardState();

// 画笔
setToolConfig({
  tool: WhiteboardTool.Pen,
  color: '#006EFF',
  lineWidth: 4,
});

// 矩形
setToolConfig({
  tool: WhiteboardTool.Shape,
  shapeType: 'rect',
  color: '#006EFF',
  lineWidth: 4,
});

await undo();           // 撤销
await redo();           // 重做
await clear();          // 清空
const image = await snapshot();
可用工具包括：
工具
枚举值
用途
选择
WhiteboardTool.None
停止绘制。
画笔
WhiteboardTool.Pen
自由书写。
激光笔
WhiteboardTool.Laser
短暂停留后自动消失。
形状
WhiteboardTool.Shape
通过 shapeType 绘制矩形或椭圆。
箭头
WhiteboardTool.Arrow
标记方向或重点。
橡皮擦
WhiteboardTool.EraserObject
擦除图形对象。
绘制形状时，在同一个配置对象中设置 shapeType：rect 表示矩形，ellipse 表示椭圆。

隐藏白板和批注入口

关闭白板或批注时调用 stopWhiteboard：
const { stopWhiteboard } = useWhiteboardState();

stopWhiteboard();

更新白板显示区域

当需要将白板切换到另一个显示区域时，可调用 updateWhiteboard 并传入新的元素 id。
const { updateWhiteboard } = useWhiteboardState();

updateWhiteboard({ view: 'whiteboard-new-view' });

使用范围

暂不支持移动端浏览器和研讨会（Webinar）房间。
当前由发起者绘制，其他成员实时观看，暂不支持多人同时绘制。
白板与普通屏幕共享使用同一路共享通道，不能同时开启。

常见问题

为什么调用 startWhiteboard 后页面没有显示内容？

请确认调用时已经通过 view 传入显示区域的 id，并且页面中存在对应的 <div>。如果该元素稍后才挂载，请在白板启动后调用 updateWhiteboard({ view })。

白板和普通屏幕共享可以同时开启吗？

不可以。白板与普通屏幕共享使用同一路共享通道；屏幕共享批注则是在屏幕共享画面上叠加绘制层，是支持的组合方式。
中国站