The Presence class is the core class provided by js-collaboration-presence-client, used to manage the local user's presence state and communicate with the server. It establishes a connection with the server through a Connection object, allowing users to:

• Submit local state (e.g., selected area)

• Listen for changes in other users' states

• Reflect the states of all collaborators on the interface

Properties

Methods

submitLocalState

Sends the local state to the server, which will broadcast it to other clients. The message type is "presence".

submitLocalState(p: P): void;

Parameter

p (P)：The local user's Presence state object.

Example

presence.submitLocalState({ userId: xxx, selection: xxx }); // Submit the user ID and selection information.

submitLocalStateField

Updates a specified field of the local Presence object and submits it to the server. The server will broadcast the updated information to other clients. The message type is "presence".

submitLocalStateField(name: string, value: unknown): void;

Parameters

• name (string)：The name of the field in the Presence object to update.

• value (unknown)：The new value to set.

Example

presence.submitLocalState({ userId: 'id1', selection: 'range1' }); // presence.localState is { userId: 'id1', selection: 'range1' }
presence.submitLocalStateField('selection', 'range2') // presence.localState is { userId: 'id1', selection: 'range2' }

removeLocalState

Removes the local presence object from the server, and the server will broadcast this to other clients.

removeLocalState(): void;

subscribe

Subscribes to other users' states.

subscribe(): Promise<void>;

Return

Promise<void>：Returns a promise that resolves when subscription is complete; access other states via "presence.otherStates".

Example

const uiComponent = new xxx.uiComponent(); // Replace with your UI component
await presence.subscribe();
uiComponent.showPresences(presence.otherStates);// Replace with your UI component's function to display presences.

destroy

Destroys the instance and releases all resources.

destroy: () => void;

Events

Presence supports the following events, managed using the on, once, and off methods:

on

Registers an event listener.

on<NAME extends keyof IPresenceEvents<P>>(name: NAME, f: IPresenceEvents<P>[NAME]): IPresenceEvents<P>[NAME]

Parameters

• name (NAME): name of the event, must be a key in the IPresenceEvents<P> interface.

• f (IPresenceEvents<P>[NAME]): The event handler function.

Return

IPresenceEvents<P>[NAME]: The registered event handler.

Example

presence.on('add', (addedPresences) => {
    console.log(addedPresences);
});

once

Registers an event listener that triggers only once.

once<NAME extends keyof IPresenceEvents<P>>(name: NAME, f: IPresenceEvents<P>[NAME]): void

Parameters

• name (NAME): The name of the event, must be a key in the IPresenceEvents<P> interface.

• f (IPresenceEvents<P>[NAME]): The event handler function.

Example

presence.once('update', (updatedPresences) => {
    console.log(updatedPresences);
});

off

Removes a specified event listener.

off<NAME extends keyof IPresenceEvents<P>>(name: NAME, f: IPresenceEvents<P>[NAME]): void

Parameters

• name (NAME): The name of the event, must be a key in the IPresenceEvents<P> interface.

• f (IPresenceEvents<P>[NAME]): The event handler function.

Usage

1. Install npm Packages

   npm install @mescius/js-collaboration-client @mescius/js-collaboration-presence-client

2. Create a Presence Instance

   import { Client } from "@mescius/js-collaboration-client";
   import { Presence } from "@mescius/js-collaboration-presence-client";
   
   const conn = new Client('ws://localhost:8080/').connect('room1');
   const presence = new Presence(conn);

3. Subscribe to "Presence" States

   const uiComponent = new xxx.uiComponent(); // Replace with your UI component
   await presence.subscribe();
   uiComponent.showPresences(presence.otherStates); // Replace with your UI component's function to display presences.

4. Listen for "Presence" State Changes

   presence.on('add', () => {
       uiComponent.showPresences(presence.otherStates);
   });
   presence.on('update', () => {
       uiComponent.showPresences(presence.otherStates);
   });
   presence.on('remove', () => {
       uiComponent.showPresences(presence.otherStates);
   });

5. Submit Local "Presence" State on Initialization

   presence.submitLocalState({ userId: xxx, selection: xxx }); // Replace with actual user ID and selection information

6. Submit "Presence" State on UI Component State Changes

   uiComponent.on('selectionChanges', () => {
       // Partial update of presence, only updating selection. Replace with actual selection information.
       presence.submitLocalStateField('selection', xxx);
   });

Complete Example

import { Client } from "@mescius/js-collaboration-client";
import { Presence } from "@mescius/js-collaboration-presence-client";

const conn = new Client('ws://localhost:8080/').connect('room1');
const presence = new Presence(conn);
const uiComponent = new xxx.uiComponent(); // Replace with your UI component

presence.subscribe().then(() => {
    uiComponent.showPresences(presence.otherStates); // Replace with your UI component's function to display presences.

    presence.submitLocalState({ userId: xxx, selection: xxx }); // Replace with actual user ID and selection information

    uiComponent.on('selectionChanges', () => {
        // Partial update of presence, only updating selection, Replace with actual selection information.
        presence.submitLocalStateField('selection', xxx);
    });

    presence.on('add', () => {
        uiComponent.showPresences(presence.otherStates);
    });
    presence.on('update', () => {
        uiComponent.showPresences(presence.otherStates);
    });
    presence.on('remove', () => {
        uiComponent.showPresences(presence.otherStates);
    });
});

API

For a complete API introduction, see: Interface of js-collaboration-presence-client