# @100mslive/hms-whiteboard 中文文档
规范地址：https://npmcn.com/package/%40100mslive/hms-whiteboard/
版本：0\.3\.3
npm 元数据更新时间：2026-09-30T17:35:19.188Z
中文译文更新时间：2026-11-05T20:29:12.899Z
软件包许可：MIT
本文由上游 README 翻译，可能存在偏差，请结合原文核对 API、命令与配置。版权与许可归原作者所有。
原始 npm 页面：https://www.npmjs.com/package/%40100mslive/hms-whiteboard
原文对照：https://npmcn.com/package/%40100mslive/hms-whiteboard/?lang=original
项目主页：https://github.com/100mslive/web-sdks#readme
源码仓库：https://github.com/100mslive/web-sdks
## 关键信息（来自 npm 元数据）
- 包体积（解压后）：859 kB，24 个文件
- 模块格式：ESM + CJS
- TypeScript 类型：包内自带
- 运行依赖：4 个
- peer 依赖：react \>=17\.0\.2 \<19\.0\.0，react-dom \>=17\.0\.2 \<19\.0\.0
- 首次发布：2024-04-09T04:29:10.090Z
- 最新版本发布：2026-09-30T17:35:18.764Z
- 近 30 天下载量：28112（2026-10-04 至 2026-11-02，npm 官方下载统计）
- 已发布版本数：303（近 12 个月 81 个）
## 中文简介
[](https://github.com/100mslive/web-sdks/actions/workflows/lint-test-build.yml) \[!\]\[Bundle Size\] (https://badgen.net/bundle Phobiado/minzip/@100mslive\] (中文(简体) )
## 安装
```sh
npm install @100mslive/hms-whiteboard
```
也可以使用：`pnpm add @100mslive/hms-whiteboard`、`yarn add @100mslive/hms-whiteboard`、`bun add @100mslive/hms-whiteboard`
## README
# 100米白板
[](https://github.com/100mslive/web-sdks/actions/workflows/lint-test-build.yml) [](https://bundlephobia.com/result?p=@100mslive/hms-whiteboard) [](https://www.100ms.live/) 
100ms SDK提供强大的API,用于将白板协作纳入您的会话. 与会者可以通过绘画、写作和在共享数字白板上合作进行实时参与。 该文件概述了如何实施白板的起动和停止功能,并将它显示在iframe内或嵌入为回放组件.
## 所需资源
- 反应 18 或以上
- 如果你是用它来捆绑你的应用软件 5 或更多
- 用户角色必须配置,以便通过100ms仪表板来启用白板功能来启动或查看白板. [参考这里](https://www.100ms.live/docs/get-started/v2/get-started/features/whiteboard#enabling-and-configuring-the-whiteboard)。 。 。 .
- 如果你在反应中,没有使用 `@100mslive/roomkit-react` 软件包,安装 `@100mslive/hms-whiteboard` 软件包.
```bash
yarn add @100mslive/hms-whiteboard
```
## 打开并关闭白板
JavaScript 用户可以使用 `selectPermissions` 从本地对等方的角色权限获取白板特定权限数组的选择器 .
反应用户可以检查 `toggle` 函数由工具钩返回 `useWhiteboard`。 。 。 .
```js
// Vanilla JavaScript Example
import { selectPermissions, selectWhiteboard } from '@100mslive/hms-video-store';
const permissions = hmsStore.getState(selectPermissions)?.whiteboard; // Array<'read' | 'write' | 'admin'>
const isAdmin = !!permissions?.includes('admin');
const whiteboard = hmsStore.getState(selectWhiteboard);
const isOwner = whiteboard?.owner === localPeerUserId;
const toggle = async () => {
if (!isAdmin) {
return;
}
if (whiteboard?.open) {
isOwner && (await actions.interactivityCenter.whiteboard.close());
} else {
await actions.interactivityCenter.whiteboard.open();
}
};
// usage
const toggleButton = document.getElementById('toggle-whiteboard');
// non-admin users cannot toggle the whiteboard
toggleButton.disabled = !isAdmin;
toggleButton.onclick = toggle;
```
```jsx
// React Example
import React from 'react';
import { useWhiteboard } from '@100mslive/react-sdk';
export const WhiteboardToggle = () => {
const { toggle, open, isOwner } = useWhiteboard();
// non-admin users cannot toggle the whiteboard
if (!toggle) {
return null;
}
return (
);
};
```
## 显示协作白板
您可以在打开时显示白板, 将它嵌入为iframe或作为反应组件, 用于更精细的控件, 如果您的应用是使用 React 构建的 .
```js
// Vanilla JavaScript Example
import { selectWhiteboard } from '@100mslive/hms-video-store';
const whiteboard = hmsStore.subscribe((whiteboard) => {
if (whiteboard?.open && whiteboard?.url) {
const whiteboardIframe = document.createElement('iframe');
whiteboardIframe.src = whiteboard.url;
} else {
const whiteboardIframe = document.getElementById('whiteboard');
whiteboardIframe?.remove();
}
}, selectWhiteboard);
```
```jsx
// React Example
import React from 'react';
import { useWhiteboard } from '@100mslive/react-sdk';
import { Whiteboard } from '@100mslive/hms-whiteboard';
import '@100mslive/hms-whiteboard/index.css';
const WhiteboardEmbed = () => {
const { token, endpoint } = useWhiteboard();
if (!token) {
return null;
}
return (
{
console.log(store, editor);
}}
/>
);
};
```
白板相关的 CSS 需要导入到您的应用程序的顶级 CSS 文件 `@import '@100mslive/hms-whiteboard/index.css';`(建议)或者在您的顶级JS文件中使用 `import '@100mslive/hms-whiteboard/index.css';`。 。 。 .
注意,如果你使用 `@100mslive/roomkit-react` 您需要导入 `@100mslive/roomkit-react/index.css` 相应.
## 常见问题
### @100mslive/hms-whiteboard 是什么？
\[\!\]\[Bundle Size\] \(https://badgen\.net/bundle Phobiado/minzip/@100mslive\] \(中文\(简体\) \)
### 如何安装 @100mslive/hms-whiteboard？
在项目目录运行 npm install @100mslive/hms-whiteboard，或使用 pnpm add / yarn add / bun add。它还需要宿主项目提供 peer 依赖：react（\>=17\.0\.2 \<19\.0\.0）、react-dom（\>=17\.0\.2 \<19\.0\.0）。npm 7 及以上与 pnpm 8 及以上默认会自动安装必需的 peer 依赖，Yarn 需要手动安装。
### @100mslive/hms-whiteboard 支持 TypeScript 吗？
支持。包内自带 TypeScript 类型声明（package\.json 声明了 types 入口），安装后即可获得类型提示，无需再安装 @types 包。
### @100mslive/hms-whiteboard 支持 ESM 还是 CommonJS？
同时提供 ES Module 与 CommonJS 入口，import 和 require\(\) 都可以使用，打包工具会自动选择合适的版本。
### @100mslive/hms-whiteboard 可以商用吗？
@100mslive/hms-whiteboard 使用 MIT 许可。宽松许可：允许商业使用、修改和再分发，通常只需在分发时保留原版权与许可声明。以上为概括，不构成法律意见，请以许可原文为准。
### @100mslive/hms-whiteboard 的下载量有多少？
根据 npm 官方下载统计，@100mslive/hms-whiteboard 在 2026/10/04 – 2026/11/02 这 30 天内被下载 28,112 次，日均约 937 次。下载量会把 CI 构建、镜像同步和作为其他包依赖的安装一并计入，适合横向比较热度，不能直接等同于使用人数。
### @100mslive/hms-whiteboard 还在维护吗？
最新版本 0\.3\.3 发布于 2026/10/01（1 个月前）；至今共发布 303 个版本，其中过去 12 个月发布了 81 个；首次发布于 2024/04/09。发布频率只是参考信号：功能稳定的工具可能很少需要更新，建议结合源码仓库的 issue 和提交记录判断。