RtcWhiteboard

Properties

API List

Events

DingRTC global events

API details

open()

Opens the whiteboard and joins the whiteboard session.

Type signature

open(wrapperEle: HTMLElement): Promise<void>;

Parameters

Back

Promise<void>

leave()

Leaves the whiteboard session. Other users receive an event that the current user has left. You can use this method to leave a whiteboard session without affecting other users.

After this method is called, the current whiteboard instance is retained and can be retrieved by its ID. If you want to continue using the whiteboard, you can retrieve the whiteboard instance and call `joinSession` to rejoin the session.

Type signature

leave(): void;

Returns

void

close()

Closes the local whiteboard but does not stop the whiteboard session.

Type signature

close(): void;

Returns

void

stop()

Stops the whiteboard. Other users receive a signal that the whiteboard is stopped. You can use this method to end the whiteboard session for all users.

After this method is called, the current whiteboard instance is cleared and revoked.

Type signature

close(): void;

Returns

void

joinSession()

Rejoins the whiteboard session.

Type signature

joinSession(): void;

Returns

void

addBackgroundImages()

Imports a specified number of background images and creates a new document that uses these images as the background.

Type signature

addBackgroundImages(urls: string[], docName?: string, docId?: string): void;

Parameters

Returns

void

addImageShape()

Adds an image to the whiteboard.

Type signature

addImageShape(url: string): Promise<void>;

Parameters

Back

Promise<void>

addPdfDoc()

Adds a PDF document from a URL and returns the document ID.

Type signature

addPdfDoc(url: string, name: string, docId?: string, fileKey?: string): string;

Parameters

Back

string

addStamp()

Adds a stamp resource.

Type signature

addStamp(stampId: string, url: string, resizable: boolean): void;

Parameters

Back

void

addPage()

Adds a new page to the end of the current document.

Type signature

addPage: (autoSwitch?: boolean) => any;

Parameters

Returns

any

alignVision()

Performs a one-time synchronization of the view during the session. Other clients are forced to use the specified view. This setting is effective only for the current page.

Type signature

alignVision(): void;

Returns

void

clearContents()

Clears the content drawn by all users on the canvas. Admin permission is required.

Type signature

clearContents(curPage: boolean, clearType: 'all' | 'draws' |'backgroundImage'): void;

Parameters

Returns

void

clearDocContents()

Clears the content of a document. Admin permission is required.

Type signature

clearContents(docId: string, clearType: 'all' | 'draws' |'backgroundImage'): void;

Parameters

Returns

void

clearUserContents()

Clears the content drawn by a specific user. Admin permission is required to clear content drawn by other users.

Type signature

clearUserContents(userId: string, curPage: boolean, clearType: WBClearType): void;

Parameters

Returns

void

center()

Resets the whiteboard view to the center, which is the initial position.

Type signature

center(doc?: any): void;

Parameters

Back

void

createDoc()

Creates a document.

Type signature

createDoc(totalPages: number, docName: string, width?: number, height?: number, docId?: string): void;

Parameters

Returns

void

deleteDoc()

Deletes a document.

Type signature

deleteDoc(docId: string, switchDocId?: string): void;

Parameters

Back

void

disableCursorSync()

Disables cursor position synchronization.

Type signature

disableCursorSync(): void;

Returns

void

disableWheelScale()

Disables canvas scaling using the mouse wheel.

Type signature

disableWheelScale(): void;

Returns

void

disableScaleAndMove()

Disables scaling the panel and moving the canvas with gestures.

Type signature

disableScaleAndMove(): void;

Returns

void

enableCursorSync()

Enables cursor position synchronization.

Type signature

enableCursorSync(): void;

Back

void

enableScaleAndMove()

Enables scaling the panel and moving the canvas with gestures.

Type signature

enableScaleAndMove(): void;

Returns

void

enableWheelScale()

Enables canvas scaling using the mouse wheel.

Type signature

enableWheelScale(): void;

Returns

void

enumerateDocs()

Lists information about all documents.

Type signature

enumerateDocs(): {
        docId: string;
        name: string;
        creator: string;
        currentPage: number;
        fileKey: string;
    }[];

Returns

{

docId: string;

name: string;

creator: string;

currentPage: number;

fileKey: string;

}[];

getCurrentPageNumber()

Retrieves the current page number.

Type signature

getCurrentPageNumber(): number;

Returns

number

getCursorSyncType()

Retrieves the cursor synchronization type. The cursor can be synchronized for all movements or only when drawing.

Type signature

getCursorSyncType(): "all" | "write";

Returns

"all" | "write"

getToolType()

Retrieves the current tool type.

Type signature

getToolType(): ShapeType;

Returns

ShapeType

getStatistics()

Retrieves statistics on the shapes created by users.

Type signature

getStatistics(): {
        userId: string;
        shapes: {
            shapeStyle?: ShapeStyle;
            shapeId: string;
            visible: boolean;
            type: ShapeType;
            fontStyle?: FontStyle;
            text?: string;
            creator: string;
        }[];
    }[];

Returns

{ userId: string; shapes: { shapeStyle?: ShapeStyle; shapeId: string; visible: boolean; type: ShapeType; fontStyle?: FontStyle; text?: string; creator: string; }[]; }[]

getTotalNumberOfPages()

Retrieves the total number of pages in the currently active whiteboard document.

Type signature

getTotalNumberOfPages(): number;

Returns

number

getTranslate()

Retrieves the current horizontal and vertical offset of the canvas.

Type signature

getTranslate(): {
        x: number;
        y: number;
    };

Returns

{

x: number;

y: number;

}

gotoPage()

Goes to a specified page number. The page number is 0-indexed.

Type signature

gotoPage(pageIndex: number, docId?: string, autoSwitchToDoc?: boolean): void;

Parameters

Returns

void

insertPage()

Insert a document

Type signature

insertPage(pageIndex: number, autoSwitch?: boolean, docId?: string, autoSwitchToDoc?: boolean): any;

Parameters

Returns

void

nextPage()

Switches to the next page.

Type signature

nextPage(): void;

Returns

void

prevPage()

Switches to the previous page.

Type signature

prevPage(): void;

Returns

void

removePage()

Deletes a specified page.

Type signature

removePage: (index?: number, docId?: string) => void;

Parameters

Returns

void

initVision()

Sets the position of the whiteboard viewport. The canvas automatically scales to an appropriate ratio to ensure that the selected viewport is centered in the current visible area. This is a global setting for the whiteboard session. After this is set, other users also follow this configuration.

After `sizeConfig` is specified, newly created blank whiteboard pages also follow this configuration. This does not apply to dynamic courseware, transcoded documents, or pages that contain background images. These layouts are scaled appropriately based on the courseware or background image.

Type signature

initVision(width: number, height: number, limited?: boolean): void;

Parameters

Returns

void

redo()

Redoes the last undone operation on the whiteboard.

Type signature

redo(): void;

Returns

void

undo()

Undoes the last operation on the whiteboard.

Type signature

undo(): void;

Returns

void

reset()

Clears the whiteboard state and restores it to the initial state.

Type signature

reset(): void;

Returns

void

setToolType()

Sets the tool type.

Type signature

setToolType(insertType: ShapeType): void;

Parameters

Returns

void

setBackgroundImage()

Sets the background image.

Type signature

setBackgroundImage(url: string): any;

Parameters

Back

any

setBackgroundImageScalingMode()

Sets the scaling mode for the whiteboard background image.

Type signature

setBackgroundImageScalingMode(scaleMode: ImageScalingMode): void;

Parameters

Returns

void

setCursorSyncType()

Sets the cursor synchronization type.

Type signature

setCursorSyncType(type: 'write' | 'all'): void;

Parameters

Returns

void

setRoleType()

Sets the whiteboard role type.

Type signature

setRoleType(roleType: WBRoleType): void;

Parameters

Back

void

setScale()

Sets the scaling ratio of the current whiteboard view. The valid range is 0.1 to 5.

Type signature

setScale(scale: number): void;

Parameters

Returns

void

snapshot()

Takes a snapshot of the current whiteboard content.

Type signature

snapshot(autoDownload?: boolean, mode?: 'all' | 'view', format?: 'png' | 'jpeg', quality?: number): Promise<string>;

Parameters

Returns

Promise<string>

setBackgroundImageScalingMode()

Sets the scaling mode for the whiteboard background image.

Type signature

setBackgroundImageScalingMode(scaleMode: ImageScalingMode): void;

Parameters

Returns

void

startFollowVision()

Enable Camera Follow

Type signature

startFollowVision(): void;

Returns

void

stopFollowVision()

Stops following another user's view.

Type signature

stopFollowVision(): void;

Returns

void

startVisionShare()

Starts sharing your view. Your view is synchronized with other users, and they receive an invitation to follow your view.

Other users can also start following your view while you are sharing it. If another user starts sharing their view, your view sharing is terminated.

You can listen for the `"user-vision-share-start"` event to receive view sharing requests from others.

You can listen for the `"user-vision-share-stop"` event to receive notifications when others stop sharing their view.

You can listen for the `"vision-lock-stop"` event. This event is triggered when your view sharing permission is preempted by another user while you are sharing.

Type signature

startVisionShare(): void;

Back

void

stopVisionShare()

Stops sharing your view and sends a message to clear your view resource information.

Type signature

stopVisionShare(): void;

Returns

void

switchToDoc()

Switches the active whiteboard document.

Type signature

switchToDoc(docId: string): void;

Parameters

Returns

void

transcodeFile()

Transcodes a file.

Type signature

transcodeFile(params: {
        targetType: 'png' | 'jpg' | 'pdf';
        onUploadProgress?: (state: {
            total: number;
            loaded: number;
        }) => void;
        onTranscodeProgress?: (status: 'init' | 'processing' | 'success' | 'failed') => void;
    }): Promise<{
        pageCount: number;
        url: string[];
        fileName: string;
        docId: string;
    }>;

Parameters

Returns

Promise<{

pageCount: number;

url: string[];

fileName: string;

docId: string;

}>

setTranslate()

Sets the canvas offset.

Type signature

setTranslate(x: number, y: number, smooth?: boolean, duration?: number): void;

Parameters

Returns

void

setSelectedShapeFontStyle()

Sets the font style of the currently selected shape.

Type signature

setSelectedShapeFontStyle(style: {
        italic?: boolean;
        bold?: boolean;
        fontSize?: number;
    }): void;

Parameters

Returns

void

setSelectedShapeStyle()

Sets the style of the currently selected shape.

Type signature

setSelectedShapeStyle(style: {
        lineWidth?: number;
        strokeStyle?: string;
        fillStyle?: string;
        fillType?: string;
    }): void;

Parameters

Returns

void

setShapesVisible()

Hides the drawn paths on the whiteboard. You can use this method to hide all paths and optionally hide the background image.

Type signature

setShapesVisible(enabled: boolean, hideBackgroundImg?: boolean): void;

Parameters

Back

void

setStamp()

Selects a stamp to use. Before you select a stamp, you must add the corresponding stamp resource.

Type signature

setStamp(stampId: string): void;

Parameters

Returns

void

uploadImage()

Uploads an image.

Type signature

uploadImage(setAsBackground?: boolean, onProgress?: (state: {
        total: number;
        loaded: number;
    }) => void): Promise<void>;

Parameters

Returns

Promise<void>

uploadPDF()

Uploads a PDF file.

Type signature

uploadPDF(onProgress?: (state: {
        total: number;
        loaded: number;
    }) => void): Promise<{
        url: string;
        fileName: string;
        docId: string;
    }>;

Parameters

Back

Promise<{

url: string;

fileName: string;

docId: string;

}>

usePdf()

Using the PDF plugin

Type signature

static usePdf(plugin: PdfPlugin): void;

Parameters

Returns

void

updateCanvasSize()

Manually updates the canvas size. You can typically call this method to update the canvas size information after the external canvas container changes.

Type signature

updateCanvasSize: (autoAdjust?: boolean, keepScale?: boolean) => void;

Parameters

Returns

void

on()

Listens for a specified event and sets a callback function.

Type signature

on(event: string, fn: Function): void;

Parameters

Returns

void

off()

Removes the listener for a specified event.

Type signature

off(event: string, fn: Function): void;

Parameters

Returns

void

once()

Listens for a specified event once. The listener is removed after the callback function is triggered.

Type signature

once(event: string, fn: Function): void;

Parameters

Returns

void

removeAllListeners()

Removes the listeners for a specified event or all events on this object.

Type signature

removeAllListeners(event?: string): void;

Parameters

Returns

void

Event details

"user-join"

The user joined the whiteboard.

Type signature

'user-join': (uid: string) => void;

Example

RtcWhiteboard.on('user-join', (uid) => {
 console.log(uid);
});

"user-leave"

The user has left the whiteboard.

Type signature

'user-leave': (uid: string) => void;

Example

RtcWhiteboard.on('user-leave', (uid) => {
 console.log(uid);
});

"doc-load-failed"

The document failed to load.

Type signature

'doc-load-failed': (docId: string, docName: string) => void;

Example

RtcWhiteboard.on('doc-load-failed', (docId, docName) => {
 console.log(docId, docName);
});

"doc-ready"

The document loaded successfully.

Type signature

'doc-ready': (docId: string) => void;

Example

RtcWhiteboard.on('doc-ready', (docId) => {
 console.log(docId);
});

"user-vision-share-start"

User view sharing has started.

Type signature

'user-vision-share-start': (userId: string) => void;

Example

RtcWhiteboard.on('user-vision-share-start', (userId) => {
 console.log(userId);
});

"vision-lock-stop"

Local view sharing has stopped.

Type signature

'vision-lock-stop': () => void;

Example

RtcWhiteboard.on('vision-lock-stop', () => {
});

"user-vision-share-stop"

The user view is no longer shared.

Type signature

'user-vision-share-stop': (userId: string) => void;

Example

RtcWhiteboard.on('user-vision-share-stop', (userId) => {
 console.log(userId);
});

"user-vision-share-stop"

The user's view is no longer being shared.

Type signature

'user-vision-share-stop': (userId: string) => void;

Example

RtcWhiteboard.on('user-vision-share-stop', (userId) => {
 console.log(userId);
});

"viewport-updated"

Viewing window changes

Type signature

'viewport-updated': (
    scale: number,
    viewport: {
      minx: number;
      miny: number;
      maxx: number;
      maxy: number;
    },
  ) => void;

Example

RtcWhiteboard.on('viewport-updated', (scale, viewport) => {
 console.log(scale, viewport);
});

"doc-switched"

The document has been switched.

Type signature

'doc-switched': (docId: string) => void;

Example

RtcWhiteboard.on('doc-switched', (docId) => {
 console.log(docId);
});

"doc-created"

Add a document

Type signature

'doc-created': (docId: string) => void;

Example

RtcWhiteboard.on('doc-created', (docId) => {
 console.log(docId);
});

"doc-deleted"

The document has been deleted.

Type signature

'doc-deleted': (userId: string) => void;

Example

RtcWhiteboard.on('doc-deleted', (userId) => {
 console.log(userId);
});

"background-image-updated"

Updating the background image

Type signature

  'background-image-updated': (docId: string, pageIndex: number, imgUrl: string) => void;

Example

RtcWhiteboard.on('background-image-updated', (docId) => {
 console.log(docId);
});

"page-index-changed"

Changes to document page numbers

Type signature

'page-index-changed': (activeDocId: string, pageIndex: number, totalPages: number) => void;

Example

RtcWhiteboard.on('page-index-changed', (docId) => {
 console.log(docId);
});

"viewport-updated-by-self"

Viewing window changes

Type signature

'viewport-updated-by-self': () => void;

Example

RtcWhiteboard.on('viewport-updated-by-self', () => {
});

"history-changed"

Triggered when the undo or redo history changes.

Type signature

'history-changed': (canUndo: boolean, canRedo: boolean) => void;

Example

RtcWhiteboard.on('history-changed', (canUndo, canRedo) => {
 console.log(canUndo, canRedo);
});