User

To support collaboration features, SpreadJS's workbook introduces the User concept, defining a user as IUser to facilitate managing user permissions and identities. This document provides a detailed explanation of the IUser interface structure, its properties, and related capabilities.

IUser

The IUser interface defines the structure of a user object in SpreadJS collaboration. Below is an explanation of its properties:

Properties

• id: string

  The unique identifier for the user, used to distinguish different collaborative users.

• name: string

  The name of the user.

• color: string (optional)

  The color associated with the user, used for visual identification in the collaborative interface (e.g., the color of selection areas).

• permission: IPermission (optional)

  An object specifying the user's permission settings in the workbook.

export type IUser {
  id?: string;
  name: string;
  color?: string;
  permission?: GC.Spread.Sheets.Collaboration.IPermission;
}

IPermission

The IPermission interface defines the specific permissions of a user, including the following properties:

• mode: BrowsingMode

  Specifies the user's primary access mode, taking values from the BrowsingMode enum:

  • BrowsingMode.edit: The user can edit the document.

  • BrowsingMode.view: The user can only view the document but may have additional permissions.

• viewModePermissions: PermissionTypes (optional)

  Specifies additional permissions when the user is in view mode. This property is a bit field, allowing multiple PermissionTypes values to be combined using bitwise operations.

export type IPermission {
    mode?: GC.Spread.Sheets.Collaboration.BrowsingMode;
    viewModePermissions?: GC.Spread.Sheets.Collaboration.PermissionTypes;
}

Enumeration Types

BrowsingMode

Defines the user's browsing mode:

• edit = 0: Edit mode, where the user can modify the document.

• view = 1: View mode, where the user can only view the document.

/**
 * Enumerates the browsing modes for document interaction.
 * @enum {number}
 */
export enum BrowsingMode {
    /** Allows the user to edit the document.
     * @type {number}
     */
    edit,
    /** Restricts the user to viewing the document only.
     * @type {number}
     */
    view,
}

PermissionTypes

Defines additional permission options in view mode, supporting combination via bitwise operations:

• allowNonDataModifyingOperations = 1: Allows operations that do not modify data.

• allowHideRowsOrColumns = 2: Allows hiding or showing rows and columns.

• allowResizeRowsOrColumns = 4: Allows resizing rows and columns.

• allowFilter = 8: Allows filtering ranges.

• allowSort = 16: Allows sorting.

/**
 * Defines the PermissionTypes
 * @enum {number}
 * @public
 */
export enum PermissionTypes {
  /**
    * Permits non-data-modifying operations
    */
  allowNonDataModifyingOperations= 1,
  /**
    * Permits hide or unhide rows/columns.
    */
  allowHideRowsOrColumns= 2,
  /**
    * Permits resizing rows/columns.
    */
  allowResizeRowsOrColumns= 4,
  /**
    * Permits filtering ranges.
    */
  allowFilter= 8,
  /**
    * Permits sorting.
    */
  allowSort= 16
}

User Capabilities

SpreadJS currently provides four APIs related to User:

• setUser: Binds the current user to use their identity and permissions.

• getUser: Get the current user.

• setPresences: Synchronizes the presence status of other collaborative users.

• getPresences: Get the current presences.

setUser

The setUser method binds a user to the current workbook instance, enabling the use of that user’s identity and permissions.

Method Signature

/**
  * Sets the current user.
  * @param {GC.Spread.Sheets.Collaboration.IUser} user The current user.
  * @example
  * ```
  * //This example sets the current user.
  * let user = {
  *     id: '1',
  *     name: 'User1',
  *     color: '#FF0000',
  *     permission: {
  *         mode: GC.Spread.Sheets.Collaboration.BrowsingMode.edit,
  *     }
  * }
  * spread.collaboration.setUser(user);
  * ```
  */
setUser(user: GC.Spread.Sheets.Collaboration.IUser): void;

Parameter

user: GC.Spread.Sheets.Collaboration.IUser

The user object to bind to the workbook, conforming to the IUser interface definition.

Functionality Description

By calling the setUser method, you can set a user as the active user for the current workbook instance. This operation determines the user’s identity and permissions within the workbook, suitable for multi-user collaborative editing scenarios. After binding, the workbook restricts or allows specific operations based on the user’s permissions, and the user’s id, name, and color properties may be used to identify the source of operations or display user status in the interface.

getUser

The getUser method get the current user.

/**
  * Get user for workbook
  * @returns {GC.Spread.Sheets.Collaboration.IUser}
  * @example
  * ```
  * ```typescript
  * // this example gets the current user.
  * const user = spread.collaboration.getUser();
  * ```
  */
getUser(): GC.Spread.Sheets.Collaboration.IUser;

setPresences/getPresences

The setPresences/getPresences method is primarily used in multi-user collaboration to display the real-time presence status of other users (e.g., cursor position, selection areas).

For details, see Presence.