# 管理房间连接状态 (/zh-CN/realtime-media/whiteboard/whiteboard-sdk/build/manage-whiteboard/manage-room-phase)

> For AI agents: see the complete documentation index at [llms.txt](/llms.txt).

本文介绍如何管理互动白板房间的连接状态。

## 功能介绍 [#功能介绍]

互动白板房间的连接状态 (`RoomPhase`)，包括以下几种：

- `Connecting`：正在连接房间。
- `Connected`：已连接房间。仅该状态下可进行白板房间内的实时互动。
- `Disconnecting`：正在断开房间连接。
- `Reconnecting`：正在重新连接房间。
- `Disconnected`：已断开房间连接。

五种状态之间的切换关系如下图所示：

<DocsImage alt="房间连接状态切换关系图" src="https://web-cdn.agora.io/docs-portal/img/whiteboard/room-phase.png" displayWidth="89%" />

其中，改变房间状态的事件描述如下：

- join room：加入房间，由用户主动调用来触发。
- fail：连接房间失败，具体原因需要根据抛出的错误描述信息来确定。
- success：成功加入房间。
- leave room：离开房间，由用户主动调用来触发。
- disconnect：由于网络原因断开连接，这会触发断线重连流程。
- connected：断线重连成功，重新进入房间。
- catch error：实时房间发生错误，这个错误无法忽视和处理，必须离开房间。

:::info[不可写状态]
除了 `Connected` 状态外，其他状态都是不可写状态，意味着此时房间既没有准备好接收房间里其他用户发出的信令，也没有准备好发送信令。此时，设备操作会被自动禁止。任何修改房间状态的操作（例如修改 Global State、插入图片/场景，PPT 翻页等）都会报错。
:::

## 前提条件 [#前提条件]

开始前，请确保你已在项目中集成声网 Whiteboard SDK 并加入房间，详见[加入白板房间](/zh-CN/realtime-media/whiteboard/whiteboard-sdk/get-started/join-room-wb)。

## 实现方法 [#实现方法]

### 获取当前房间状态 [#获取当前房间状态]

在前端/客户端，随时可以通过如下代码获取当前的房间状态。

```javascript
var phase = room.phase;
```

### 监听房间状态变化 [#监听房间状态变化]

你可以在加入房间时，添加监听器，以监听房间状态变化。

```javascript
import { RoomPhase } from "white-web-sdk";

var joinRoomParams = {
    uuid: uuid,
    roomToken: roomToken,
};
whiteWebSdk.joinRoom(joinRoomParams, {
    onPhaseChanged: function(phase) {
        // 获取房间状态，根据房间状态执行业务代码
        switch (phase) {
            case RoomPhase.Connecting: {
                break;
            }
            case RoomPhase.Connected: {
                break;
            }
            case RoomPhase.Reconnecting: {
                break;
            }
            case RoomPhase.Disconnecting: {
                break;
            }
            case RoomPhase.Disconnected: {
                break;
            }
        }
    },
});
```

### 处理房间异常流程 [#处理房间异常流程]

实时房间可能因为各种异常情况，不得不中断服务。为了保障 App 的稳定性，在设计业务逻辑之初，就应该把异常流程考虑在内。

你可以在加入房间时，通过添加监听器，来处理异常流程。

```javascript
var joinRoomParams = {
    uuid: roomUUID,
    roomToken: roomToken,
};

whiteWebSdk.joinRoom(joinRoomParams, {

    onDisconnectWithError: function(err) {
        // 房间因为错误，和服务端断开连接
    },

    onKickedWithReason: function(err) {
        // 用户被踢出房间
    },
});
```

### 主动离开房间 [#主动离开房间]

声网互动白板不会自动离开房间。如果你不再需要使用白板，就应该离开房间。出于如下理由，你应当确保主动离开房间：

- 不离开房间的话，浏览器将维持与声网服务器的长连接。这将消耗终端用户设备的各种资源，包括网络带宽等。
- 声网会对没有离开房间的用户继续收费。维持不必要的长连接将导致你所在的团队或公司产生不必要的开支。

:::info[信息]
如果用户直接关闭浏览器，或关闭当前网页标签页，SDK 会自动释放房间。
:::

参考以下代码，主动离开房间：

```javascript
room.disconnect().then(function() {
    // 成功离开房间
}).catch(function(err) {
    // 离开房间失败，获得报错 err
});
```

## 参考信息 [#参考信息]

### API 参考 [#api-参考]

- [`RoomPhase`](/zh-CN/api-reference/whiteboard/whiteboard-sdk/web/enums/roomphase)
- [`RoomCallbacks`](/zh-CN/api-reference/whiteboard/whiteboard-sdk/web/globals#roomcallbacks)
- [`joinRoom`](/zh-CN/api-reference/whiteboard/whiteboard-sdk/web/classes/whitewebsdk#joinroom)
- [`disconnect`](/zh-CN/api-reference/whiteboard/whiteboard-sdk/web/interfaces/room#disconnect)