---
title: "协作中的感知"
description: "与协作结合，集成实时用户活动跟踪。将用户存在和光标位置添加到您的编辑器中。"
canonical_url: "https://tiptap.zhcndoc.com/collaboration/core-concepts/awareness"
---

# 协作中的感知

与协作结合，集成实时用户活动跟踪。将用户存在和光标位置添加到您的编辑器中。

Tiptap 协作中的感知，由 Yjs 提供支持，帮助您共享协作空间内用户活动的实时信息。这可以包括用户存在、光标位置以及自定义用户状态等详细信息。

在其核心，感知利用自身的无冲突复制数据类型（CRDT）来确保这一共享元信息在所有用户之间保持一致和即时，而无需维护这些状态的历史记录。

您可以在[Yjs 的感知文档](https://docs.yjs.dev/getting-started/adding-awareness)中了解有关感知的更多信息。

## 必需的提供者事件

感知更新会触发特定的[提供者事件](https://tiptap.zhcndoc.com/collaboration/provider/events.md)，以根据用户的操作和存在开发交互式功能：

- `awarenessUpdate`：此事件表示用户处于活动状态。即使没有实际状态变化，它也会触发，充当“心跳”以通知其他用户该用户正在文档中。
- `awarenessChange`：此事件提醒您感知状态中的任何新增、更新或删除，反映了您的本地更改以及远程用户的更改。

这些事件可以作为集成自定义感知功能的钩子。

## 集成感知

在设置好您的[协作环境](https://tiptap.zhcndoc.com/collaboration/getting-started/install.md)后，您可以集成感知功能，协作提供者原生支持该功能。

要开始，更新感知状态，提供任何相关信息。作为示例，我们将使用用户的姓名、光标颜色和鼠标位置。

### 设置感知字段

让我们为用户分配一个姓名、颜色和鼠标位置。这只是一个示例，您可以自由使用与您的应用相关的任何数据。

```typescript
// 为当前用户设置感知字段
provider.setAwarenessField('user', {
  // 分享您喜欢的任何信息
  name: 'Kevin James',
  color: '#ffcc00',
})
```

### 监听变化

设置事件监听器以跟踪所有连接用户的感知状态变化：

```typescript
// 监听所有用户状态的更新
provider.on('awarenessChange', ({ states }) => {
  console.log(states)
})
```

您现在可以在浏览器的控制台中查看这些更新，继续进行下一步。

### 跟踪鼠标移动

接下来，我们将为我们的应用添加一个事件监听器，以跟踪鼠标移动并相应更新感知的信息。

```typescript
document.addEventListener('mousemove', (event) => {
  // 分享您喜欢的任何信息
  provider.setAwarenessField('user', {
    name: 'Kevin James',
    color: '#ffcc00',
    mouseX: event.clientX,
    mouseY: event.clientY,
  })
})
```

检查您浏览器的控制台，查看用户移动鼠标时的事件流。

## 添加光标和选择

在建立基本感知之后，考虑将[协作光标](https://tiptap.zhcndoc.com/editor/extensions/functionality/collaboration-caret.md)扩展添加到您的编辑器中。此扩展将所有参与用户的光标位置、文本选择以及个性化详细信息（如姓名和颜色）添加到您的编辑器中。