# @datalayer/lexical-loro 中文文档

规范地址：https://npmcn.com/package/%40datalayer/lexical-loro/

版本：1\.0\.8
npm 元数据更新时间：2026-10-28T04:13:39.395Z
中文译文更新时间：2026-11-11T14:54:27.190Z
软件包许可：未声明

本文由上游 README 翻译，可能存在偏差，请结合原文核对 API、命令与配置。版权与许可归原作者所有。

原始 npm 页面：https://www.npmjs.com/package/%40datalayer/lexical-loro
原文对照：https://npmcn.com/package/%40datalayer/lexical-loro/?lang=original
项目主页：https://github.com/datalayer/lexical-loro#readme
源码仓库：https://github.com/datalayer/lexical-loro

## 关键信息（来自 npm 元数据）

- 包体积（解压后）：542 kB，137 个文件
- 模块格式：CommonJS
- TypeScript 类型：包内自带
- 运行依赖：32 个
- 首次发布：2025-08-21T07:07:45.419Z
- 最新版本发布：2026-10-28T04:13:38.950Z
- 近 30 天下载量：6667（2026-10-12 至 2026-11-10，npm 官方下载统计）
- 已发布版本数：17（近 12 个月 12 个）

## 中文简介

[![Datalayer](https://images.datalayer.io/legacy/datalayer-25.svg)](https://datalayer.ai/)

## 安装

```sh
npm install @datalayer/lexical-loro
```

也可以使用：`pnpm add @datalayer/lexical-loro`、`yarn add @datalayer/lexical-loro`、`bun add @datalayer/lexical-loro`

## README

[![Datalayer](https://images.datalayer.io/legacy/datalayer-25.svg)](https://datalayer.ai/)

[![Become a Sponsor](https://img.shields.io/static/v1?label=Become%20a%20Sponsor&message=%E2%9D%A4&logo=GitHub&style=flat&color=1ABC9C)](https://github.com/sponsors/datalayer)

# 与 Loro CRDT 协作插件

协作编辑插件 [语法](https://github.com/facebook/lexical) 丰富的编辑器 [罗罗](https://github.com/loro-dev) CRDT,提供无冲突同步的实时协作编辑能力.

## 核心组成部分

这个软件包提供了构建协作文本编辑器的三个主要组成部分:

1.  **`LoroCollaborativePlugin.tsx`** - 用于实时协作编辑的Lexical插件
2.  **`LexicalModel` Python 库** - 具有CRDT能力的单行文件格式
3.  **`lexical-loro` WebSocket 服务器** - 使用 Python 服务器 [萝拉平](https://github.com/loro-dev/loro-py) 实时协作

## 快速启动

### 使用 Lexic 插件

```tsx
import { LoroCollaborativePlugin } from './src/LoroCollaborativePlugin';

function MyEditor() {
  return (
    <LexicalComposer initialConfig={editorConfig}>
      <RichTextPlugin />
      <LoroCollaborativePlugin 
        websocketUrl="ws://localhost:8081"
        docId="my-document"
        username="user1"
      />
    </LexicalComposer>
  );
}
```

### 使用 Lexical Model 图书馆

```python
from lexical_loro import LexicalModel

# Create a new document
model = LexicalModel.create_document("my-document")

# Add content
model.add_block({
    "text": "My Document",
    "format": 0,
    "style": ""
}, "heading1")

model.add_block({
    "text": "This is a paragraph.",
    "format": 0,
    "style": ""
}, "paragraph")

# Save to file
model.save_to_file("document.json")

# Load from file
loaded_model = LexicalModel.load_from_file("document.json")
```

### 使用 Python 服务器

```bash
# Install the Python package
pip install -e .

# Start the server
lexical-loro-server --port 8081
```

## 实例

关于完整的工作实例,见 `src/examples/` 包含:

-   双编辑器支持的完全反应应用程序
-   服务器选择界面
-   连接状态指标
-   丰富的文本格式化示例

**分会** 协作光标还需要修正,参见 [这个问题](https://github.com/datalayer/lexical-loro/issues/1)。 。 。 .

![](https://assets.datalayer.tech/lexical-loro.gif)

## 核心特征

-   🔄 **实时协作**:多个用户可以同时编辑同一文档
-   🚀 **无冲突**: 使用Loro CRDT自动解决冲突
-   📝 **语法整合**: 与 Lexical 丰富的文本编辑器无缝集成
-   📚 **独立图书馆**: 文件管理独立使用 Lexical Model
-   🌐 **WebSocket 服务器**: 用于维护文档状态的 Python 服务器
-   📡 **连接管理**: 强力 WebSocket 连接处理
-   ✨ **丰富的文本支持**: 协作编辑时保留格式
-   💾 **序列化**: JSON 出口/进口和文件持久性
-   🔧 **广泛**: 方便定制的以插件为基础的架构

## 技术堆栈

**核心依赖:**

-   **语法**: v0.33.1 (Facebook的可扩展文本编辑器框架)
-   **Loro CRDT 软件**: v1.5.10 (无冲突复制数据类型)
-   **反应**: 18/19 (用于插件钩和组件)
-   **蟒**: 3.8+ 并带有loro-py和websockets

**发展依赖:**

-   **类型脚本**: 类型安全
-   **维特**:用于建筑和开发(仅提供实例)
-   **测试**: Python 测试
-   **ESLint 语录**: 代码折叠

## 安装

### 核心插件

Lexical 插件是一个单一的 TypeScript/ React 组件, 您可以复制到您的工程中 :

```bash
# Copy the plugin file
cp src/LoroCollaborativePlugin.tsx your-project/src/
```

**所需依赖:**

```bash
npm install lexical @lexical/react @lexical/selection loro-crdt react react-dom
```

### Python 服务器

安装 Python WebSocket 服务器 :

```bash
# Install from this repository
pip install -e .

# Or install specific dependencies
pip install websockets click loro
```

## 使用量

### 1\. 词汇插件集成

将插件添加到您的 Lexical 编辑器 :

```tsx
import { LexicalComposer } from '@lexical/react/LexicalComposer';
import { RichTextPlugin } from '@lexical/react/LexicalRichTextPlugin';
import { ContentEditable } from '@lexical/react/LexicalContentEditable';
import { LoroCollaborativePlugin } from './LoroCollaborativePlugin';

const editorConfig = {
  namespace: 'MyEditor',
  theme: {},
  onError: console.error,
};

function CollaborativeEditor() {
  return (
    <LexicalComposer initialConfig={editorConfig}>
      <div className="editor-container">
        <RichTextPlugin
          contentEditable={<ContentEditable className="editor-input" />}
          placeholder={<div className="editor-placeholder">Start typing...</div>}
          ErrorBoundary={() => <div>Error occurred</div>}
        />
        <LoroCollaborativePlugin 
          websocketUrl="ws://localhost:8081"
          docId="shared-document"
          username="user123"
        />
      </div>
    </LexicalComposer>
  );
}
```

### 2\. 独立的词典模型图书馆

在文档管理中独立使用 Lexical Model 库 :

```python
from lexical_loro import LexicalModel

# Create a new document
model = LexicalModel.create_document("my-document")

# Add different types of content
model.add_block({
    "text": "My Document",
    "format": 0,
    "style": ""
}, "heading1")

model.add_block({
    "text": "This is a paragraph with **bold** text.",
    "format": 0,
    "style": ""
}, "paragraph")

model.add_block({
    "text": "",
    "format": 0,
    "style": ""
}, "list")

# Serialize to JSON
json_data = model.to_json()

# Save to file
model.save_to_file("document.json")

# Load from file
loaded_model = LexicalModel.load_from_file("document.json")

# Access blocks
for block in loaded_model.get_blocks():
    print(f"{block['type']}: {block.get('text', '')}")
```

更多例子见:

-   `examples/memory_only_example.py` - 基本文件的创建和操纵
-   `examples/file_sync_example.py` - 文件持久性和批量操作
-   `examples/collaboration_example.py` - 模拟协作编辑
-   `docs/LEXICAL_MODEL_GUIDE.md` - 综合文件

### 3\. Python 服务器设置

启动 WebSocket 服务器 :

```bash
# Default port (8081)
lexical-loro-server

# Custom port
lexical-loro-server --port 8082

# With debug logging
lexical-loro-server --port 8081 --log-level DEBUG
```

### 4\. 程序服务器的使用

```python
import asyncio
from lexical_loro import LoroWebSocketServer

async def main():
    server = LoroWebSocketServer(port=8081)
    await server.start()
    print("Server running on ws://localhost:8081")

if __name__ == "__main__":
    asyncio.run(main())
```

## 插件 API

关于详细的API文档,参见: [`docs/API.md`](https://npmcn.com/package/%40datalayer/lexical-loro/docs/API.md)。 。 。 .

### 快速引用

```tsx
interface LoroCollaborativePluginProps {
  websocketUrl: string;          // WebSocket server URL
  docId: string;                 // Unique document identifier
  username: string;              // User identifier
  userColor?: string;            // User cursor color (optional)
  debug?: boolean;               // Enable debug logging (optional)
}
```

## 初始化最佳做法

⚠️ **重要**: 总是等待协作初始化后才能启用其他插件.

见 [`docs/INITIALIZATION_GUIDE.md`](https://npmcn.com/package/%40datalayer/lexical-loro/docs/INITIALIZATION_GUIDE.md) 关于以下方面的全面指导意见:

-   适当的插件排序
-   初始化回调
-   处理错误
-   常见的防标剂

## 实例

完整的工作实例和演示,见 `src/examples/` 目录 :

```bash
# Run the example application
npm install
make example

# This starts both Node.js and Python servers plus a React demo app
# Open http://localhost:3000/split/index.html to see the 2 editors view
```

这些例子包括:

-   **完整回放应用程序**: 与 UI 完全合作编辑器
-   **服务器选择**: 在节点.js和Python后端之间切换
-   **双向编辑器**: 简单的文本区和丰富的 Lexical 编辑器
-   **实时演示**: 多用户协作测试

见 `src/examples/README.md` 例如,详细的文档.

## 建筑

```
EDITOR 1                                           EDITOR 2

loro                                               loro
- node(data: root(1))                              - node(data: root(12))
  - node(data: element(2))                           - node(data: element(22))
    - node(data: text(3))                              - node(data: text(13))
  - node(data: counter(4))                           - node(data: counter(4))

                <---- loro updates via websocket ------>
                <---- loro node ids are the same ------>
             <---- lexical node keys are different ------>

lexical                                            lexical
- root(1)                                          - root(12)
  - element(2)                                       - element(22)
    - text(3)                                          - text(13)
  - counter(4)                                       - counter(49)
```

## 实例

Loro 实例

-   http://localhost:3:00/?is Collab=real (英语)
    
-   http://localhost:3:00/split/?is Collab=real (中文(简体) )
    

Y.js实例(供参考)

-   http://localhost:3:00/?.isCollab=real&useYjs=real (英语)
    
-   http://localhost:3:00/split/?.is Collab=real&useYjs=real (英语)

## 常见问题

### 如何安装 @datalayer/lexical-loro？

在项目目录运行 npm install @datalayer/lexical-loro，或使用 pnpm add / yarn add / bun add。

### @datalayer/lexical-loro 支持 TypeScript 吗？

支持。包内自带 TypeScript 类型声明（package\.json 声明了 types 入口），安装后即可获得类型提示，无需再安装 @types 包。

### @datalayer/lexical-loro 支持 ESM 还是 CommonJS？

以 CommonJS 形式发布，可以直接 require\(\)；在 ES Module 项目中也可以用 import 引入（Node\.js 会把 module\.exports 作为默认导出）。

### @datalayer/lexical-loro 可以商用吗？

@datalayer/lexical-loro 使用 未声明 许可。package\.json 没有声明许可证。没有许可证的代码默认保留全部权利，商用前请联系作者或查看仓库中的 LICENSE 文件。以上为概括，不构成法律意见，请以许可原文为准。

### @datalayer/lexical-loro 的下载量有多少？

根据 npm 官方下载统计，@datalayer/lexical-loro 在 2026/10/12 – 2026/11/10 这 30 天内被下载 6,667 次，日均约 222 次。下载量会把 CI 构建、镜像同步和作为其他包依赖的安装一并计入，适合横向比较热度，不能直接等同于使用人数。

### @datalayer/lexical-loro 还在维护吗？

最新版本 1\.0\.8 发布于 2026/10/28（14 天前）；至今共发布 17 个版本，其中过去 12 个月发布了 12 个；首次发布于 2025/08/21。发布频率只是参考信号：功能稳定的工具可能很少需要更新，建议结合源码仓库的 issue 和提交记录判断。