Permissions

SpreadJS Sheets Coollaboration provides two document modes: View Mode and Edit Mode. Through the Permissions feature, the workbook can configure specific operational permissions in View Mode, striking a balance between flexibility and security in a collaborative environment.

Functionality Description

IPermission

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

• mode: BrowsingMode

  Specifies the workbook access mode, taking values from the BrowsingMode enum:

  • BrowsingMode.edit: The workbook is editable.

  • BrowsingMode.view: The workbook is view-only but may have additional permissions.

• viewModePermissions: PermissionTypes (optional)

  Specifies additional permissions when the workbook 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 workbook's browsing mode:

• edit = 0: Edit mode, where the workbook can be modified.

  view = 1: View mode, where the workbook is read-only.

/**
 * Enumerates the browsing modes for document interaction.
 * @enum {number}
 */
export enum BrowsingMode {
    /** The workbook is editable.
     * @type {number}
     */
    edit,
    /** The workbook is view-only.
     * @type {number}
     */
    view,
}

Edit Mode

• The workbook has unrestricted editing permissions.

• All modifications are synchronized in real-time with other collaborators.

• This is the default mode for workbook.

View Mode

• The workbook is view-only.

• Certain UI operations (e.g., hiding rows, adjusting column width) can be enabled via permissions, but these operations only take effect locally and are not synchronized.

• In View Mode, by default, all reversible commands are disabled. However, users can customize the following permissions to allow specific operations, optimizing the viewing experience without compromising data integrity:

  • allowNonDataModifyingOperations: Allows viewer could execute non-data modifying operations.

  • allowHideRowsOrColumns: Allows hiding or showing rows or columns.

  • allowResizeRowsOrColumns: Allows resizing rows or columns.

  • allowFilter: Allows filtering data.

  • allowSort: Allows sorting data.

Policy Points

• In View Mode, all Command operations (including built-in commands and custom Commands) are restricted, but APIs are not limited.

• In View Mode, any data changes resulting from permission-enabled operations take effect only locally and are not synchronized.

Application Scenarios

• Data Viewing: The workbook in View Mode can adjust the UI (e.g., hide rows, filter data) to analyze data without affecting other users’ workbooks.

• Security: Fine-grained permission controls prevent unauthorized modifications, protecting data in the collaborative environment.

• Team Collaboration: Combined with status tracking, users can see others’ operations while retaining control over their own capabilities.

Methods

Users can bind user information to the workbook using the UserManager.current and setPermission method or simultaneously bind presence and user information to the workbook using the bindPresence method.

Usage

The following example demonstrates how to set the active user and workbook permission to View Mode and allow them to hide/show rows/columns, resize rows/columns, and filter data:

• Initialize workbook and user information.

  //Set current user.
  GC.Spread.Common.UserManager.current("896736#B1WZd2yQ");
  
  const workbook = new GC.Spread.Sheets.Workbook("ss");
  //Set the workbook permission.
  workbook.collaboration.setPermission({
    mode: GC.Spread.Sheets.Collaboration.BrowsingMode.view,
    viewModePermissions: GC.Spread.Sheets.Collaboration.PermissionTypes.allowHideRowsOrColumns
      | GC.Spread.Sheets.Collaboration.PermissionTypes.allowResizeRowsOrColumns
      | GC.Spread.Sheets.Collaboration.PermissionTypes.allowFilter
  });

• Bind both presence and user information with permission information to the workbook.

  const presence = new Presence<IPresence>(conn);
  const workbook = new GC.Spread.Sheets.Workbook(document.getElementById("ss"), { sheetCount: 2 });
  const user = {
      id: "896736#B1WZd2yQ",
      name: "chris",
      color: "#FF0000",
      permission: {
        mode: GC.Spread.Sheets.Collaboration.BrowsingMode.view,
        viewModePermissions: GC.Spread.Sheets.Collaboration.PermissionTypes.allowHideRowsOrColumns
        | GC.Spread.Sheets.Collaboration.PermissionTypes.allowResizeRowsOrColumns
        | GC.Spread.Sheets.Collaboration.PermissionTypes.allowFilter
      }
  };
  bindPresence(workbook, presence, user);

API

• spread-sheets-collaboration-client

  /**
   * Defines the BrowsingMode
   * @enum {number}
   */
  export enum BrowsingMode {
      /** Specifies that the user could edit the document.
       * @type {number}
       */
      edit,
      /** Specifies that the user could only view the document.
       * @type {number}
       */
      view,
  }
  /**
   * Defines the PermissionTypes
   * @enum {number}
   */
  export enum PermissionTypes {
      /** Specifies that viewer could execute non-data modifying operations.
       * @type {number}
       */
      allowNonDataModifyingOperations,
      /** Specifies that viewer could hide/unhide rows/columns.
       * @type {number}
       */
      allowHideRowsOrColumns,
      /** Specifies that viewer could resize rows/columns.
       * @type {number}
       */
      allowResizeRowsOrColumns,
      /** Specifies that viewer could filter range.
       * @type {number}
       */
      allowFilter,
      /** Specifies that viewer could sort.
       * @type {number}
       */
      allowSort,
  }
  export interface IPermission {
      mode: BrowsingMode;
      viewModePermissions?: PermissionTypes;
  }

• GC.Spread.Sheets.Collaboration.Collaboration

  ///* function setPermission(permission: GC.Spread.Sheets.Collaboration.IPermission): void
  /**
    * Set the permission info.
    * @param {GC.Spread.Sheets.Collaboration.IPermission} permission - The permission info.
    * @example
    * //This example updates the current permission.
    * let permission = {
    *     mode: GC.Spread.Sheets.Collaboration.BrowsingMode.view,
    * };
    * spread.collaboration.setPermission(permission);
    */
  setPermission (permission: IPermission): void;
  ///* function getPermission(): GC.Spread.Sheets.Collaboration.IPermission
  /**
    * Get the permission for the workbook
    * @returns {GC.Spread.Sheets.Collaboration.IPermission} permission - The permission info.
    * @example
    * ```typescript
    * // This example gets permission.
    * const permission = spread.collaboration.getPermission();
    */
  getPermission (): GC.Spread.Sheets.Collaboration.IPermission;

• GC.Spread.Sheets.Events

  ///* field static PermissionChanged: string
  /**
   * Occurs when the workbook permission changed.
   * @name GC.Spread.Sheets.Workbook#PermissionChanged
   * @event
   * @param {GC.Spread.Sheets.Collaboration.IPermission} permission The sheet that triggered the event.  * @example
   * ```javascript
   * //This example uses the ThreadedCommentChanged event.
   * spread.bind(GC.Spread.Sheets.Events.PermissionChanged, function (e, info) {
   *     console.log(info.permission);
   * });
   * ```
   */
  static PermissionChanged = 'PermissionChanged';

• GC.Spread.Sheets.ContextMenu

  interface GC.Spread.Sheets.ContextMenu.IMenuItemData {
    ...
    metaData?:  GC.Spread.Sheets.ICommandMetaData; // metaData is an Object used to attach some information to the menuItemData. 
  }
  export interface ICommandMetaData{
      viewModePermissions: GC.Spread.Sheets.Collaboration.PermissionTypes; // whether the menuItem is available when browsingMode is in viewMode. 
  }