# User

## Content

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](https://developer.mescius.com/spreadjs/api/modules/GC.Spread.Sheets.Collaboration#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.

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

### IPermission

The **[IPermission](https://developer.mescius.com/spreadjs/api/modules/GC.Spread.Sheets.Collaboration#ipresence)** 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.

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

### Enumeration Types

#### [BrowsingMode](https://developer.mescius.com/spreadjs/api/enums/GC.Spread.Sheets.Collaboration.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.

```typescript
/**
 * 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](https://developer.mescius.com/spreadjs/api/enums/GC.Spread.Sheets.Collaboration.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.

```typescript
/**
 * 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](https://developer.mescius.com/spreadjs/api/classes/GC.Spread.Sheets.Collaboration.Collaboration#setuser)**: Binds the current user to use their identity and permissions.
* **[getUser](https://developer.mescius.com/spreadjs/api/classes/GC.Spread.Sheets.Collaboration.Collaboration#getuser)**: Get the current user.
* **[setPresences](https://developer.mescius.com/spreadjs/api/classes/GC.Spread.Sheets.Collaboration.Collaboration#setpresences)**: Synchronizes the presence status of other collaborative users.
* **[getPresences](https://developer.mescius.com/spreadjs/api/classes/GC.Spread.Sheets.Collaboration.Collaboration#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**

```typescript
/**
  * 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.

```typescript
/**
  * 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](/spreadjs/docs/v18/spreadjs-collaboration-server/spreadjs-sheets-collaboration/user/presence).