---
title: "状态和变化事件"
description: "使用事件监听器与 Tiptap 协作提供者有效管理实时状态和变化。在文档中了解更多信息！"
canonical_url: "https://tiptap.zhcndoc.com/collaboration/provider/events"
---

# 状态和变化事件

使用事件监听器与 Tiptap 协作提供者有效管理实时状态和变化。在文档中了解更多信息！

协作提供者中的事件让您能够响应各种状态和变化，例如成功的连接或身份验证更新。您可以在提供者初始化期间附加事件监听器，或者根据应用程序的需要稍后添加它们。

## 使用提供者事件

| 事件                     | 描述                   |
| ---------------------- | -------------------- |
| `open`                 | 在 WebSocket 连接打开时触发。 |
| `connect`              | 在提供者连接到服务器时触发。       |
| `authenticated`        | 表示客户端身份验证成功。         |
| `authenticationFailed` | 在客户端身份验证失败时触发。       |
| `status`               | 跟踪连接状态的变化。           |
| `close`                | 在 WebSocket 连接关闭时触发。 |
| `disconnect`           | 在提供者断开连接时触发。         |
| `destroy`              | 表示提供者即将被销毁。          |
| `message`              | 由传入消息触发。             |
| `outgoingMessage`      | 在消息发送之前触发。           |
| `synced`               | 表示 Yjs 文档的初始成功同步。    |
| `stateless`            | 在接收到无状态消息时触发。        |
| `awarenessUpdate`      | 在用户意识信息更新时触发。        |
| `awarenessChange`      | 在意识状态变化时触发。          |

## 配置事件监听器

要立即跟踪事件，请直接将事件监听器传递给提供者的构造函数。这确保监听器从一开始就处于活动状态。

```ts
const provider = new TiptapCollabProvider({
  appId: '', // 您的文档服务器 ID（用于云部署），本地部署时替换为 baseUrl
  name: 'example-document', // 文档标识符
  token: '', // 您的身份验证 JWT
  document: ydoc,
  onOpen() {
    console.log('WebSocket 连接已打开。')
  },
  onConnect() {
    console.log('已连接到服务器。')
  },
  // 下面还有更多事件监听器...
})
```

### 动态绑定事件

要在初始化后添加或删除监听器，提供者支持动态绑定和解绑事件处理程序。

**示例：** 在提供者初始化期间绑定事件监听器

```ts
const provider = new TiptapCollabProvider({
  // …
})

provider.on('synced', () => {
  console.log('文档已同步。')
})
```

**示例：** 在提供者初始化后绑定/解绑事件监听器

```typescript
const onMessage = () => {
  console.log('收到新消息。')
}

// 绑定
provider.on('message', onMessage)

// 解绑
provider.off('message', onMessage)
```

## 提供者事件示例

### 显示连接状态

使用 `onConnect` 和 `onDisconnect` 向用户提供实时连接状态反馈，提升用户体验。

```tsx
provider.on('connect', () => {
  showStatus('已连接')
})

provider.on('disconnect', () => {
  showStatus('已断开连接')
})
```

### 同步文档状态

使用 `synced` 在文档初次完全同步时提醒用户，确保他们开始使用最新版本。

```tsx
provider.on('synced', () => {
  alert('文档已初始化')
})
```

### 处理身份验证问题

使用 `authenticationFailed` 捕捉身份验证错误，并提示用户重新身份验证，以确保安全访问。

```tsx
provider.on('authenticationFailed', ({ reason }) => {
  console.error('身份验证失败：', reason)
  requestUserReauthentication()
})
```