活动状态

基于 js-collaboration-presence 框架，spread-sheets-collaboration 提供了专为 SpreadJS 表格协同编辑场景设计的 在线状态（Presence） 功能。该功能支持实时显示用户在线状态（如光标位置、选区等），用于呈现其他协同者的活动状态。您可以通过 setPresences/getPresences 或 bindPresence 将工作簿与在线状态关联。

核心特性：实时用户状态共享

功能描述

在活跃工作表中，实时渲染所有协同用户在当前工作表的选区或选中单元格：

为每个用户分配唯一颜色，并在选区右上角显示用户名。
用户颜色来源（优先级从高到低）：
1. 用户信息中指定的颜色
2. 自定义 colorScheme
3. 默认配色方案（['#0000ff', '#008000', '#9900cc', '#800000', '#00cc33', '#cc6600', '#cc0099']）

use-presence

应用场景

多用户编辑时，清晰查看他人正在操作的单元格或区域，避免冲突。
团队协同中，实时感知其他成员在财务表格中的编辑位置。

接口定义

ISelections

ISelections 接口定义了表示工作簿中特定选区信息的对象结构：

//* typedef GC.Spread.Sheets.Collaboration.ISelections
/**
 * @property {GC.Spread.Sheets.Range[]} [selections]
 * @property {string} [sheetId]
 */
export interface ISelections {
    selections?: GC.Spread.Sheets.Range[];
    sheetId?: string;
}

属性说明

属性名	类型	描述
selections (可选)	GC.Spread.Sheets.Range[]	SpreadSheets 中的所有选区。
sheetId (可选)	string	选区所在的工作表 ID。

IStatus

IStatus 接口定义了所有状态对象的结构：

//* typedef GC.Spread.Sheets.Collaboration.IStatus
/**
 * @property {GC.Spread.Sheets.Collaboration.ISelections} [selections]
 */
export interface IStatus {
    selections?: GC.Spread.Sheets.Collaboration.ISelections;
}

属性说明

属性名	类型	描述
selections	GC.SpreadSheets.Collaboration.ISelections	所有选区状态。

IPresence

IPresence 接口定义了工作簿中用户在线状态对象的结构：

//* typedef GC.Spread.Sheets.Collaboration.IPresence
/**
 * @property {GC.Spread.Sheets.Collaboration.IUser} [user]
 * @property {GC.Spread.Sheets.Collaboration.IStatus} [status]
 */
export interface IPresence {
    user: GC.Spread.Sheets.Collaboration.IUser;
    status: GC.Spread.Sheets.Collaboration.IStatus;
}

属性说明

属性名	类型	描述
user (可选)	GC.Spread.Sheets.Collaboration.IUser	用户对象信息。
status (可选)	GC.Spread.Sheets.Collaboration.IStatus	在线状态信息。

IBindPresenceOptions

IBindPresenceOptions 接口定义了 bindPresences 的配置选项：

export interface IBindPresenceOptions {
    onPresencesUpdate?: (presences?: IPresence[]) => void
}

属性说明

属性名	类型	描述
onPresencesUpdate (可选)	(presences?: IPresence[]) => void	通过 bindPresences 更新在线状态后的回调方法。

方法说明

setPresences

setPresences 方法更新用户在线状态信息：

function setPresences(presences: GC.Spread.Sheets.Collaboration.IPresence[]): void

参数

presences (GC.Spread.Sheets.Collaboration.IPresence[]): 需要设置的用户在线状态。

示例

let presences = [{
	user: {
		id: '1',
		name: 'User1',
		color: '#FF0000'
	},
	status: {
		selections: {
			selections: [new GC.Spread.Sheets.Range(0, 0, 1, 1)],
			sheetId: 'sheet1'
		}
	}
}];
spread.collaboration.setPresences(presences);

getPresences

getPresences 方法获取当前在线状态：

function getPresences(): GC.Spread.Sheets.Collaboration.IPresence[]

返回值

presences(GC.Spread.Sheets.Collaboration.IPresence[]): 当前的在线状态。

示例

const presences = spread.collaboration.getPresences();

bindPresence

bindPresence 方法将在线状态和用户信息绑定到当前工作簿，提供了一种更简便的方式同时绑定在线状态和用户信息：

export interface IUserWithPermission extends GC.Spread.Common.IUser {
    permission?: IPermission;
}
export declare function bindPresence(workbook: any, presence: Presence<IPresence>, user: IUserWithPermission, options?: IBindPresenceOptions): Promise<void>;

参数

workbook (GC.Spread.Sheets.Workbook): 工作簿实例。
presence (GC.Spread.Sheets.Collaboration.IPresence): 在线状态实例。
user (GC.Spread.Sheets.Collaboration.IUser): 用户信息。
options (IBindPresenceOptions): 绑定用户在线状态的配置选项。

返回值

Promise<void>: 将返回一个 Promise，绑定完成后会 resolve。

示例

import { Client } from "@grapecity-software/js-collaboration-client";
import { Presence } from "@grapecity-software/js-collaboration-presence-client";
import { bindPresence, IUserWithPermission} from 'spread-sheets-collaboration-client';

const conn = new Client('ws://localhost:8080/').connect('room1');
const presence = new Presence(conn);

const user:IUserWithPermission = {
    id: '1',
    name: "user1",
    permission: {
        mode: GC.Spread.Sheets.Collaboration.BrowsingMode.edit,
    }
}

bindPresence(workbook, presence, user);

使用方法

客户端实现

安装 Npm 包

npm install @grapecity-software/js-collaboration-client @grapecity-software/js-collaboration-presence-client @grapecity-software/spread-sheets-collaboration-client

创建在线状态实例

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

const conn = new Client('ws://localhost:8080/').connect('room1');
const presence = new Presence(conn);

绑定工作簿和在线状态（不包含用户信息）此方法不包含用户信息，如需用户信息，请使用步骤 4 的方法。

const presences: IPresence[] = Object.values(presence.otherStates);
workbook.collaboration.setPresences(presences.map(p => ({ user: p.user, status: p.status })));

获取用户实例并绑定工作簿、在线状态和用户

此为示例，生产环境中请替换为实际用户信息。

```typescript
import { bindPresence, IUserWithPermission } from 'spread-sheets-collaboration-client';
var seed = new Date().valueOf() + "";
const user: IUserWithPermission = {
    id: seed,
    name: "user" + seed,
    permission: {
        mode: GC.Spread.Sheets.Collaboration.BrowsingMode.edit,
    }
}
bindPresence(workbook, presence, user);
```

服务器端实现

服务器端使用方法请参考 Presence 服务器。

API 参考

`spread-sheets-collaboration-client`

/**
 * 表示协作系统中的用户
 */
export interface IUserWithPermission extends GC.Spread.Common.IUser {
    permission?: IPermission;
}
/**
 * 表示工作表的选区数据
 */
export interface ISelections {
    selections?: Range[];
    sheetId?: string;
}
/**
 * 表示用户的在线状态信息
 */
export interface IPresence {
    user: GC.Spread.Common.IUser;
    status: { selections?: ISelections };
}
/**
 * 将工作簿与在线状态实例绑定
 * @param {any} workbook - GC.Spread.Sheets.Workbook 实例
 * @param {Presence<IPresence>} presence - 在线状态实例
 * @param {IUserWithPermission} user - 包含权限的用户信息
 * @param {IBindPresenceOptions} [options] - 绑定配置项（可选）
 * @returns {Promise<void>} 绑定完成后解析的 Promise
 */
export declare function bindPresence(workbook: any, presence: Presence<IPresence>, user: IUserWithPermission, options?: IBindPresenceOptions): Promise<void>;
/**
 * 工作簿在线状态绑定的配置项
 */
export interface IBindPresenceOptions {
    onPresencesUpdate?: (presences?: IPresence[]) => void;
}

`GC.Spread.Sheets.@Workbook`

///* function setPresences(presences: GC.Spread.Sheets.Collaboration.IPresence[]): void
/**
  * 设置在线状态信息。
  * @param {GC.Spread.Sheets.Collaboration.IPresence[]} presences - 在线状态信息。
  * @example
  * // 此示例更新当前在线状态。
  * let presences = [{
  *     user: {
  *         id: '1',
  *         name: 'User1',
  *         color: '#FF0000',
  *         permission: {
  *             mode: GC.Spread.Sheets.Collaboration.BrowsingMode.edit,
  *         }
  *     },
  *     status: {
  *         selections: {
  *              selections: [new GC.Spread.Sheets.Range(0, 0, 1, 1)],
  *              sheetId: 'sheet1'
  *         }
  *     }
  * }, {
  *     user: {
  *         id: '2',
  *         name: 'User2',
  *         permission: {
  *             mode: GC.Spread.Sheets.Collaboration.BrowsingMode.edit,
  *         }
  *     },
  *     status: {
  *         selections: {
  *              selections: [new GC.Spread.Sheets.Range(2, 2, 3, 5)],
  *              sheetId: 'sheet1'
  *         }
  *     }
  * }]
  * spread.collaboration.setPresences(presences);
  */
setPresences (presences: IPresence[]): void;

///* function getPresences(): GC.Spread.Sheets.Collaboration.IPresence[]
/**
  * 获取工作簿的在线状态
  * @returns {GC.Spread.Sheets.Collaboration.IPresence[]} presences - 在线状态信息。
  * @example
  * ```typescript
  * // 此示例获取在线状态。
  * const presences = spread.collaboration.getPresences();
  */
getPresences (): GC.Spread.Sheets.Collaboration.IPresence[];

底层 API

本章节的在线状态功能构建于 js-collaboration-presence 之上。如需了解 Presence 的客户端/服务器通用接口（submitLocalState / subscribe / 事件监听等），参见底层协同框架中的 js-collaboration-presence。