画布初始化相关

更新时间 2025/02/25 05:40:11

画布 Web SDK 在初始化时，可以通过给入配置项参数，来控制画布的默认行为或画布内的功能。

代码示例：

// 我们提供了类型声明文件，方便您正确定义画布初始化配置
import type { GetSdkInstanceConfigs } from "@plaso-infi/whiteboard-sdk";
// 设置您的配置项信息
const configs: GetSdkInstanceConfigs = {...};
// 通过配置项来初始化画布
InfiWebSdk.getSdkInstance(configs).then(res => {...});

必要配置项

部分配置项是启用 Web SDK 能力的必要参数，列表如下：

`getQueryString`

getQueryString: () => Promise<string>;

获取画布连接参数的请求函数，画布连接参数为初始化 & 链接服务器使用的加密字符串, 内含应用、白板、用户等信息，最终 resolve 的 string 通常需要由服务器生成，故这个函数通常也是一个请求您服务器的方法函数。由于画布连接参数对于画布而言过于重要，我们把它作为了一个单独的专题来叙述，详情请参考画布连接参数。

`initToken`

initToken: string;

画布初始化 Token，由应用 ID、用户信息、画布 ID、有效期等信息生成。

注：

本配置项自 @plaso-infi/whiteboard-sdk v0.7.2 版本起开始支持。

在功能层面与 getQueryString 配置项较为相似，二者为互斥关系，我们建议您基于本配置项完成画布的初始化动作。若与 getQueryString 配置项同时存在，则本配置项不生效。

为防止画布连接异常，Token过期时，请调用 refreshToken API 重新更新您的Token

`userInfo`

userInfo: UserInfoT;

当前画布使用者的信息，UserInfoT类型需要包括：

loginName: 画布使用者的 uuid，必填。
userName: 画布使用者在画布内的显示名称，必填。
avatarUrl: 画布使用者的头像图片 url，可选。缺省情况下画布会自动使用 userName 第一个名称及随机颜色默认绘制一个用户头像。比如用户名为“游客时”，用户头像可能如下图所示：
userType: 画布用户初始权限设置，选填。如果缺失，则用户默认权限为只读。类型支持：
- visitor：画布访客，仅有画布只读权限。
- editor：画布编辑者，拥有绝大部分画布编辑权限。
- owner：画布拥有者，拥有全部画布内编辑权限，相比 editor 在少量业务上有更高权限，例如可以对元素设置仅画布拥有者可以解锁元素。
  注：
  - @plaso-infi/whiteboard-sdk v0.6.0 版本起开始支持。开始支持 userType 字段。
  - 该设置仅会影响用户进入画布后的初始权限。后续可以通过权限控制 API 进行变更。

`containerDom`

containerDom: HTMLDivElement;

用以挂载白板 DOM 的 HTML DOM 元素, 白板相关元素会自动 appendChild 至这个元素之内。

`getUsersInfo`

getUsersInfo: (loginNames: string[]) => Promise<UserInfoT[]>;

画布的一大核心理念是“合作”，所以在在使用画布时，通常情况下我们希望能获取到其他在同一块画布中协作的同伴的用户信息，而这个配置项就是获取用户信息的请求函数。此配置项需要给入支持基于 loginName 获取该用户的用户名与头像 url 的方法，方法返回的用户信息用以于画布内作展示。注：如果是单人使用画布的场景，传入一个返回空数组的函数即可，如：

getUsersInfo: async () => [],

通过正确填入上述必要配置项，即可以启用画布能力，但如果想进一步控制画布的默认行为，或者对画布能力、UI 做定制化，则需要基于画布的初始化可配置项来控制。

可选配置项

`toolbarWidgetsConfigs`

toolbarWidgetsConfigs?: ToolBarWidgetsConfigsT

画布工具栏显示控制配置项，可以控制画布内大部分工具的显示/隐藏，详见画布工具。

`getTemplate`

getTemplate?: () => Promise<TemplateType | null>;

当画布工具中配置打开模板后，您可以自定义点击模板工具后的行为，详见模板工具

`uiSlots`

uiSlots?: { titleSlot?: React.ReactNode;  topRightSlot?: React.ReactNode }

画布内 UI 插槽，当前仅支持自定义位于画布左上角的标题栏内容部分，及画布右上角的工具栏内容部分，定制 UI 需要给入 React Node, 这需要您基于 React 来定义组件。其中：

titleSlot: 画布左上角的标题栏插槽，React 组件 maxHeight 为 48px; 与画布自带的搜索、下载等 UI 毗邻；通常可以用于展示 logo 或呈现 “返回” 按键等
topRightSlot: 画布右上角的 UI 插槽，React 组件 maxHeight 为 48px; 与画布自身的在线成员展示等 UI 毗邻。注意，因为这两个组件实际渲染的 parent 组件也受到 toolbarWidgetsConfigs 配置项的控制，所以如果您在 toolbarWidgetsConfigs 配置项中，将画布左上角及右上角的工具栏全部隐藏，则即便您设置了 titleSlot 和 topRightSlot，它们也不会显示。

用法示例：
```
const Settings: React.FC = () => { ... };
const ShareBtn: React.FC = () => { ... };

InfiWebSdk.getSdkInstance({
  ...,
  uiSlots: {
    titleSlot: <Settings />,
    topRightSlot: <ShareBtn />,
  }
})
```

`displayMode`

displayMode?: 'normal' | 'phone' | 'bigScreen';

配置初始画布显示模式。不同画布显示模式下，画布的布局和交互方式会有所不同。详情请参考画布显示模式。

利用画布实例 API 可以动态改变画布显示模式，详见改变画布显示模式。

`defaultBehaviors`

defaultBehaviors?: DefaultBehaviorsT;

配置画布初始化后默认的行为，DefaultBehaviorsT 包含多项内容，详见下表。

配置项

说明

类型

默认值

showFrameList

默认显示帧框列表

boolean

false

presentationMode

默认进入帧框播放模式

boolean

false

laserMode

默认启用激光笔

boolean

false

defaultGrid

默认的画布网格设置

GridType 详见下方描述

defaultDrawStyles

默认画笔偏好

object 详见下方描述

undefined

showOthersCursorByDefault

默认是否显示其他合作者光标

boolean

false

画布网格类型 GridType 有三类：

enum GridType {
  NONE = 0, // 无
  LINE = 1, // 线条网络
  DOT = 2, // 点阵网络
}

画笔偏好 object
```
type defaultDrawStyles? = {
  pen?: { lineColor?: number; lineWidth?: number }[];
  mark?: { lineColor?: number; lineWidth?: number; lineOpacity?: number }[];
};
```
- 请确保设置的画笔颜色是画笔默认颜色，包括：0xffffff, 0xfef445, 0xfac710, 0xf24726, 0xe6e6e6, 0xcee741, 0x8fd14f, 0xda0063, 0x808080, 0x12cdd4, 0x0ca789, 0x9510ac, 0x1a1a1a, 0x2d9bf0, 0x414bb2, 0x652cb3
- pen 及 mark 的默认配置数组长度应 <= 3
- 手机或大屏模式下，仅第一个配置有效。

`operationGuide`

operationGuide? OperationGuideT;

画布用户引导相关，详情请参考用户引导文档。

`enableAi`

enableAi?: boolean;

画布 AI 功能开关，关闭后会隐藏全部 AI 功能入口。

`aiConfig`

aiConfig?: AiConfigT;

画布 AI 功能相关配置，详情请参考 AI 配置文档。

注：@plaso-infi/whiteboard-sdk v0.6.0 版本起开始支持本配置项。

`usePortal`

usePortal?: boolean;

在 React 环境下，开启该配置能够将画布渲染到与其他节点同一DOM树中，使 Web SDK 组件与您的项目组件共享 React 状态

注：

本配置项自@plaso-infi/whiteboard-sdk v0.6.0 起开始支持

该配置需要与initPortal配合使用，获取DOM节点后，手动加载

`initPortal`

initPortal?: (portal: ReactNode) => void;

初始化DOM节点后，会通过该配置回调出来手动加载。用法示例：

import ReactDOM from 'react-dom';
function App() {
  const [portal, setPortal] = useState<ReactNode>();
  const boardDomRef = useRef<HTMLDivElement>(null);

  // 配置初始化
  const initRes = await InfiWebSdk.getSdkInstance({
    ..., // 其他配置
    containerDom: boardDomRef.current,
    usePortal: true,
    initPortal: setPortal
  })

  // 组件加载完毕
  ins.on('sdk_dom_ready', () => {
    console.log('sdk dom ready');
  });

  // 组件渲染
  return <div>
    <div ref={boardDomRef}>{portal}</div>
  </div>
}

ReactDOM.render(<App />, document.getElementById('app'));

注：

本配置项自@plaso-infi/whiteboard-sdk v0.6.0 起开始支持

为避免 api 调用无效，请在监听到 sdk_dom_ready 或 resource_ready 消息后执行

必要配置项​

getQueryString​

initToken​

userInfo​

containerDom​

getUsersInfo​

可选配置项​

toolbarWidgetsConfigs​

getTemplate​

uiSlots​

displayMode​

defaultBehaviors​

operationGuide​

enableAi​

aiConfig​

usePortal​

initPortal​

必要配置项

`getQueryString`

`initToken`

`userInfo`

`containerDom`

`getUsersInfo`

可选配置项

`toolbarWidgetsConfigs`

`getTemplate`

`uiSlots`

`displayMode`

`defaultBehaviors`

`operationGuide`

`enableAi`

`aiConfig`

`usePortal`

`initPortal`