快速开始

本教程将指导您创建一个支持在本地开发环境运行的实时协同的 SpreadJS 实例。用户可以在同一房间内同时编辑工作簿，所有更改将在其他客户端之间同步。

具体步骤

步骤 1：初始化项目

创建项目文件夹
在计算机上创建一个新文件夹，例如 spread-collaboration，并导航到该文件夹：
```
mkdir spread-collaboration
cd spread-collaboration
```

初始化 Node.js 项目

运行以下命令创建 package.json 文件：

npm init -y

编辑 package.json 并添加以下脚本：

{
  "name": "spread-collaboration",
  "version": "1.0.0",
  "type": "module",
  "scripts": {
    "start": "node server.js",
    "build": "webpack"
  },
  "dependencies": {}
}

安装依赖项

安装服务器和客户端所需的 npm 包：

npm install @grapecity-software/js-collaboration @grapecity-software/js-collaboration-ot
npm install @grapecity-software/js-collaboration-client @grapecity-software/js-collaboration-ot-client
npm install @grapecity-software/spread-sheets-collaboration @grapecity-software/spread-sheets-collaboration-client
npm install @grapecity-software/spread-sheets @grapecity-software/spread-sheets-collaboration-addon
npm install express

包说明：以上协同包按客户端 / 服务器分组，各自作用如下。

客户端：

包	作用
`spread-sheets`	SpreadJS 工作簿本体，提供表格的编辑、计算、渲染能力。
`spread-sheets-collaboration-addon`	工作簿的协同插件，监听表格变化、把变化打包成操作。
`spread-sheets-collaboration-client`	把工作簿和共享文档（SharedDoc）绑定，是 SpreadJS 接入协同的客户端入口。
`js-collaboration-client`	通信层客户端，负责和服务器建立长连接、收发消息、自动重连。
`js-collaboration-ot-client`	OT 客户端，接收服务器校准后的操作并应用到本地工作簿。

服务端：

包	作用
`js-collaboration`	通信核心，负责长连接、房间管理、消息广播、自动重连。
`js-collaboration-ot`	OT 算法核心，负责校准并发操作的位置。
`spread-sheets-collaboration`	SpreadJS 专用的协同扩展包：提供工作簿对应的 OT 类型（OT_Type），让服务器"懂得"如何处理表格操作；同时负责把工作簿和共享文档（SharedDoc）绑定。

以上是跑通最小协同闭环的必装包。若还需要别人光标 / 选区实时可见，见用户活动状态；若需要数据落库、服务重启不丢，见配置数据库适配器。

安装前端打包工具所需的 npm 包：

npm install webpack webpack-cli --save-dev

使用 style-loader 和 css-loader：

npm install --save-dev style-loader
npm install --save-dev css-loader

创建 Webpack 配置文件

在项目根目录创建 webpack.config.js，内容如下：

import path from "path";
import { fileURLToPath } from "url";
const __dirname = path.dirname(fileURLToPath(import.meta.url));

export default {
  entry: './public/client.js', // 入口文件
  output: {
    path: path.resolve(__dirname, 'public'), // 输出到 public 目录
    filename: 'client.bundle.js' // 输出文件名
  },
  mode: 'development',
      module: {
        rules: [
            {
                test: /\.css$/i,
                use: ["style-loader", "css-loader"],
            },
        ],
    },
};

创建 public 目录和空文件

在项目根目录创建一个 public 目录和一个 server.js 文件。在 public 目录内，创建 index.html、styles.css 和 client.js 文件。现在目录结构应该如下所示：

/ (项目根目录)
│── node_modules/        # 依赖模块目录
│── public/              # 公共资源目录
│   ├── client.js        # 客户端代码
│   ├── index.html       # 入口 HTML 文件
│── package.json         # 项目配置文件
│── server.js        # 服务器端代码
│── webpack.config.js    # Webpack 配置文件

步骤 2：设置服务器

创建服务器

在 server.js 文件中添加以下代码：

import express from 'express';
import http from 'http';
import { Server } from '@grapecity-software/js-collaboration';
import * as OT from '@grapecity-software/js-collaboration-ot';
import { type } from '@grapecity-software/spread-sheets-collaboration';

// 注册类型
OT.TypesManager.register(type);

const app = express();
const httpServer = http.createServer(app);
const server = new Server({ httpServer });
const port = 8080;

// 初始化 OT 文档服务
const documentServices = new OT.DocumentServices();
server.useFeature(OT.documentFeature(documentServices));

// 初始化 OT 文档服务
app.use(express.static('public'));

// 启动服务器
httpServer.listen(port, () => {
    console.log(`服务器正在监听端口 ${port}`);
    console.log(`http://127.0.0.1:${port}/index.html`);
});

代码说明：

使用 OT.TypesManager.register 注册 SpreadJS 的类型，支持 SpreadJS OT 操作。
OT.DocumentServices 提供默认的 OT 文档管理功能。
server.useFeature(OT.documentFeature()) 启用 OT 功能。

步骤 3：设置客户端

客户端将使用 SpreadJS、js-collaboration-ot-client 和 spread-sheets-collaboration-client 实现实时同步。

编写 HTML 文件 (public/index.html)

<!DOCTYPE html>
<html lang="zh-CN">
<head>
    <meta charset="UTF-8">
    <title>SpreadJS 协同</title>
    <script src="/client.bundle.js"></script>
</head>
<body>
    <div id="ss" style="width:100vw;height:95vh;border:1px solid darkgray;float:left"></div>
</body>
</html>

编写客户端 JavaScript (public/client.js)

import * as GC from '@grapecity-software/spread-sheets'
import '@grapecity-software/spread-sheets-collaboration-addon';
import { Client } from "@grapecity-software/js-collaboration-client";
import * as OT from "@grapecity-software/js-collaboration-ot-client";
import { type, bind } from '@grapecity-software/spread-sheets-collaboration-client';
import "@grapecity-software/spread-sheets/styles/gc.spread.sheets.excel2013white.css";

// 注册类型
OT.TypesManager.register(type);
window.onload = async function() {
    const workbook = new GC.Spread.Sheets.Workbook('ss');
    // 连接到服务器并加入房间
    const conn = new Client().connect('room1');
    const doc = new OT.SharedDoc(conn);
    // 监听错误
    doc.on('error', (err) => console.error(err));
    await doc.fetch();
    // 如果文档不存在，初始化内容
    if (!doc.type) {
        workbook.getActiveSheet().getCell(0, 0).value("默认内容");
        await doc.create(workbook.collaboration.toSnapshot(), type.uri, {});
        bind(workbook, doc);
    } else {
        bind(workbook, doc);
    }

}

代码说明：

使用 OT.SharedDoc 管理共享文档并将其与工作簿集成。
使用 bind 绑定文档和工作簿。如需手动绑定，请参考扩展包安装与绑定。
如果文档不存在，使用 doc.create 创建。

步骤 4：运行和测试

打包客户端代码
```
npm run build
```
启动服务器
```
npm run start
```
您应该会看到输出，指示服务器正在 http://localhost:8080 运行。
测试功能
1. 打开浏览器并访问 http://127.0.0.1:8080/index.html
2. 在多个窗口中打开相同地址，编辑内容并观察实时同步。

最终效果

如图所示，编辑操作可以实时同步至其他客户端：

协同演示.gif

SpreadJS 中文文档