# 频道 (/zh-CN/api-reference/rtm/harmonyos/channel)

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

频道是 RTM 实时网络中一种数据传输的管理机制，任何订阅或加入频道的用户都可以在 100 毫秒内接收到频道中传输的消息和事件，RTM 允许客户端订阅数百甚至数千个频道。大多数 RTM API 都将以频道为基础进行发送、接收、加密等行为。

基于声网的能力，RTM 的频道分成三种类型以匹配不同的应用场景：

- Message Channel：遵循行业标准的 Pub/Sub （发布/订阅）模式，频道无需提前创建，订阅频道即可在频道内收发消息。频道内的发布者和订阅者数量没有上限。
- User Channel：基于 Pub/Sub （发布/订阅）模式的点对点消息收发。用户无需订阅频道操作，可以直接指定用户 ID 发送消息，接收消息也只需监听 `onMessageEvent` 事件。
- Stream Channel：遵循行业类似观察者模式的 Room （房间）概念，用户需要创建并加入频道才能在频道内收发消息。频道中允许创建不同的 Topic，消息通过 Topic 进行组织和管理。

想要了解 Message Channel 和 Stream Channel 的更多用法及适用场景，可以查看：

- [频道](/zh-CN/realtime-media/rtm/build/channels-and-topics/channel-basic)

## subscribe [#subscribe]

### 接口描述 [#接口描述]

RTM 提供消息、状态等事件通知能力。通过设置事件监听，你可以接收已订阅频道中的消息和事件。关于如何添加和设置事件监听，详见[事件监听](/zh-CN/api-reference/rtm/harmonyos/configuration#事件监听)章节。

通过调用 `subscribe` 方法，客户端可以订阅 Message Channel 并开始接收频道中的消息和事件通知。成功调用该方法后，订阅该频道且开启 Presence 事件监听的用户会收到 `REMOTE_JOIN_CHANNEL` 类型的 `presence` 事件，详见[事件监听](/zh-CN/api-reference/rtm/harmonyos/configuration#事件监听)。

:::info[信息]
该方法仅适用于 Message Channel。
:::

### 接口方法 [#接口方法]

你可以通过以下方式调用 `subscribe` 方法：

```typescript
async subscribe(channelName: string, options?: SubscribeOptions): Promise<SubscribeResponse>
```

| 参数 | 类型 | 是否必填 | 默认值 | 描述 |
| --- | --- | --- | --- | --- |
| `channelName` | string | 必填 | - | 频道名称。 |
| `options` | `SubscribeOptions` | 选填 | `{}` | 订阅频道选项。 |

`SubscribeOptions` 包含以下属性：

| 属性 | 类型 | 是否必填 | 默认值 | 描述 |
| --- | --- | --- | --- | --- |
| `withMessage` | bool | 选填 | `true` | 是否订阅此频道中的消息事件通知。 |
| `withMetadata` | bool | 选填 | `false` | 是否订阅此频道中的 Storage 事件通知。 |
| `withPresence` | bool | 选填 | `true` | 是否订阅此频道中的 Presence 事件通知。 |
| `withLock` | bool | 选填 | `false` | 是否订阅此频道中的 Lock 事件通知。 |
| `beQuiet` | bool | 选填 | `false` | [channel-harmonyos-html-1-5-4 details](#table-slot-channel-harmonyos-html-1-5-4) |

<a id="table-slot-channel-harmonyos-html-1-5-4"></a>

**channel-harmonyos-html-1-5-4 details**

是否静默订阅频道。该参数设置为 `true` 时表示静默订阅频道，表现如下：

- 不影响你接收频道内其他用户的事件通知。
- 频道内其他用户不会收到你订阅/取消订阅频道、设置/获取/删除临时状态的事件通知。
- 调用 `whoNow` 方法查询不到自己。
- 调用 `whereNow` 方法查询不到自己静默订阅的频道。

### 返回值 [#返回值]

该方法返回一个 Promise，成功时 resolve 并返回 `SubscribeResponse` 对象，失败时 reject 并抛出 `RtmError` 异常。

`SubscribeResponse` 数据结构如下：

| 属性 | 类型 | 描述 |
| --- | --- | --- |
| `timestamp` | number | 操作的时间戳（保留字段，供未来使用）。 |
| `channelName` | string | 已订阅的频道名称。 |

### 基本用法 [#基本用法]

```typescript
import { RtmClient, RtmError } from '@shengwang/rtm-full';
import type { SubscribeOptions } from '@shengwang/rtm-full';

// 订阅频道并设置选项
const options: SubscribeOptions = {
  withMessage: true,
  withMetadata: true,
  withPresence: true,
  withLock: false,
  beQuiet: false
};

try {
  const response = await rtmClient.subscribe('my-channel', options);
  console.log('Subscribed to channel:', response.channelName);
} catch (error) {
  if (error instanceof RtmError) {
    console.error('Subscribe failed:', error.errorCode, error.reason);
  }
}
```

## unsubscribe [#unsubscribe]

### 接口描述 [#接口描述-1]

如果你不再需要关注某个频道，可调用 `unsubscribe` 方法取消订阅该频道。成功取消订阅该频道后，其他订阅该频道并开启事件监听的用户会收到 `REMOTE_LEAVE_CHANNEL` 类型的 `presence` 事件通知，详见[事件监听](/zh-CN/api-reference/rtm/harmonyos/configuration#事件监听)。

:::info[信息]
该方法仅适用于 Message Channel。
:::

### 接口方法 [#接口方法-1]

你可以通过以下方式调用 `unsubscribe` 方法：

```typescript
async unsubscribe(channelName: string): Promise<UnsubscribeResponse>
```

| 参数 | 类型 | 是否必填 | 默认值 | 描述 |
| --- | --- | --- | --- | --- |
| `channelName` | string | 必填 | - | 频道名称。 |

### 返回值 [#返回值-1]

该方法返回一个 Promise，成功时 resolve 并返回 `UnsubscribeResponse` 对象，失败时 reject 并抛出 `RtmError` 异常。

`UnsubscribeResponse` 数据结构如下：

| 属性 | 类型 | 描述 |
| --- | --- | --- |
| `timestamp` | number | 操作的时间戳（保留字段，供未来使用）。 |
| `channelName` | string | 已取消订阅的频道名称。 |

### 基本用法 [#基本用法-1]

```typescript
import { RtmClient, RtmError } from '@shengwang/rtm-full';

// 取消订阅频道
try {
  const response = await rtmClient.unsubscribe('my-channel');
  console.log('Unsubscribed from channel:', response.channelName);
} catch (error) {
  if (error instanceof RtmError) {
    console.error('Unsubscribe failed:', error.errorCode, error.reason);
  }
}
```

<a id="StreamChannel"></a>

## createStreamChannel [#createstreamchannel]

### 接口描述 [#接口描述-2]

在使用 Stream Channel 之前，你需要先调用 `createStreamChannel` 方法创建 `StreamChannel` 实例。成功创建实例后，你可以调用其相关方法，例如：加入频道、离开频道、发送 Topic 消息、订阅 Topic 消息等。

:::info[信息]
该方法仅适用于 Stream Channel。
:::

### 接口方法 [#接口方法-2]

你可以通过以下方式调用 `createStreamChannel` 方法：

```typescript
createStreamChannel(channelName: string): StreamChannel
```

|     参数      |  类型  | 是否必填 | 默认值 | 描述       |
| ---------- | --- | ----- | --- | ---------- |
| `channelName` | string |   必填   |   -    | 频道名称。 |

### 返回值 [#返回值-2]

返回一个 [`StreamChannel`](#StreamChannel) 对象实例。如果创建失败，会抛出 `RtmError` 异常。

:::info[信息]
- 对于同一个频道名称，多次调用该方法会返回同一个 StreamChannel 实例。
- StreamChannel 实例在内部被缓存管理，无需手动管理实例的生命周期。
:::

### 基本用法 [#基本用法-2]

```typescript
import { RtmClient, RtmError } from '@shengwang/rtm-full';

try {
  const streamChannel = rtmClient.createStreamChannel('game-room');
  console.log('Stream channel created successfully');
  
  // 多次调用返回同一个实例
  const sameChannel = rtmClient.createStreamChannel('game-room');
  console.log('Same instance:', streamChannel === sameChannel); // true
} catch (error) {
  if (error instanceof RtmError) {
    console.error('Create stream channel failed:', error.errorCode, error.reason);
  }
}
```

## join [#join]

### 接口描述 [#接口描述-3]

成功创建 Stream Channel 后，你可以调用 `join` 方法加入 Stream Channel。

成功加入频道后，你才能进行频道相关操作。此时，订阅该频道并添加事件监听的用户会收到如下事件通知：

- 本地用户：
  - `SNAPSHOT` 类型的 `presence` 事件通知。
  - `SNAPSHOT` 类型的 `topic` 事件通知。
- 远端用户：`REMOTE_JOIN_CHANNEL` 类型的 `presence` 事件通知。

:::info[信息]
该方法仅适用于 Stream Channel。
:::

### 接口方法 [#接口方法-3]

你可以通过以下方式调用 `join` 方法：

```typescript
async join(options?: JoinOptions): Promise<JoinResponse>
```

| 参数 | 类型 | 是否必填 | 默认值 | 描述 |
| --- | --- | --- | --- | --- |
| `options` | `JoinChannelOptions` | 选填 | `{}` | 加入频道选项。 |

`JoinChannelOptions` 包含以下属性：

| 属性 | 类型 | 是否必填 | 默认值 | 描述 |
| --- | --- | --- | --- | --- |
| `token` | string | 选填 | `''` | [channel-harmonyos-html-6-1-4 details](#table-slot-channel-harmonyos-html-6-1-4) |
| `withMetadata` | boolean | 选填 | `false` | 是否订阅此频道中的 Storage 事件通知。 |
| `withPresence` | boolean | 选填 | `true` | 是否订阅此频道中的 Presence 事件通知。 |
| `withLock` | boolean | 选填 | `false` | 是否订阅此频道中的 Lock 事件通知。 |
| `beQuiet` | boolean | 选填 | `false` | [channel-harmonyos-html-6-5-4 details](#table-slot-channel-harmonyos-html-6-5-4) |

<a id="table-slot-channel-harmonyos-html-6-1-4"></a>

**channel-harmonyos-html-6-1-4 details**

加入 Stream Channel 的 Token。

- 如果你的项目开启了 Token 鉴权，你可以填入 [RTC 临时 Token](/zh-CN/realtime-media/rtc/build/setup-and-access/enable-service#获取临时-token) 或 Token 服务器生成的 [RTC 正式 Token](/zh-CN/realtime-media/rtc/build/setup-and-access/token-authentication)。
- 如果你的项目未开启 Token 鉴权，你可以填入空字符串。

<a id="table-slot-channel-harmonyos-html-6-5-4"></a>

**channel-harmonyos-html-6-5-4 details**

是否静默加入频道。该参数设置为 `true` 时表示静默加入频道，表现如下：

- 不影响你接收频道内其他用户的事件通知。
- 频道内其他用户不会收到你加入/离开频道、设置/获取/删除临时状态的事件通知。
- 调用 `whoNow` 方法查询不到自己。
- 调用 `whereNow` 方法查询不到自己静默加入的频道。

### 返回值 [#返回值-3]

该方法返回一个 Promise，成功时 resolve 并返回 `JoinResponse` 对象，失败时 reject 并抛出 `RtmError` 异常。

`JoinResponse` 数据结构如下：

| 属性 | 类型 | 描述 |
| --- | --- | --- |
| `timestamp` | number | 操作的时间戳（保留字段，供未来使用）。 |
| `channelName` | string | 频道名称。 |

### 基本用法 [#基本用法-3]

```typescript
import { RtmClient, RtmError } from '@shengwang/rtm-full';
import type { JoinOptions } from '@shengwang/rtm-full';

// 创建 Stream Channel
const streamChannel = rtmClient.createStreamChannel('game-room');

// 加入频道
const options: JoinOptions = {
  token: 'your_token',
  withMetadata: false,
  withPresence: true,
  withLock: false,
  beQuiet: false
};

try {
  const response = await streamChannel.join(options);
  console.log('Joined channel:', response.channelName);
} catch (error) {
  if (error instanceof RtmError) {
    console.error('Join failed:', error.errorCode, error.reason);
  }
}
```

## leave [#leave]

### 接口描述 [#接口描述-4]

如果你不再需要待在某个频道中，你可以调用 `leave` 方法离开该频道。离开后你将不再会接收到此频道中的任何消息、状态及事件通知，你在该频道中创建的 Topic 发布者的角色及你与所有 Topic 的订阅关系都将自动解除。如果想再次恢复之前的发布者角色和订阅关系，你需要调用 `join` 方法再次进入该频道并自行调用 `joinTopic` 和 `subscribeTopic` 方法进行设置。

成功离开频道后，频道中的远端用户会收到 `REMOTE_LEAVE_CHANNEL` 类型的 `presence` 事件通知，详见[事件监听](/zh-CN/api-reference/rtm/harmonyos/configuration#事件监听)。

:::info[信息]
该方法仅适用于 Stream Channel。
:::

### 接口方法 [#接口方法-4]

你可以通过以下方式调用 `leave` 方法：

```typescript
async leave(): Promise<LeaveResponse>
```

该方法无需参数。

### 返回值 [#返回值-4]

该方法返回一个 Promise，成功时 resolve 并返回 `LeaveResponse` 对象，失败时 reject 并抛出 `RtmError` 异常。

`LeaveResponse` 数据结构如下：

| 属性 | 类型 | 描述 |
| --- | --- | --- |
| `timestamp` | number | 操作的时间戳（保留字段，供未来使用）。 |
| `channelName` | string | 频道名称。 |

### 基本用法 [#基本用法-4]

```typescript
import { RtmClient, RtmError } from '@shengwang/rtm-full';

// 创建并加入 Stream Channel
const streamChannel = rtmClient.createStreamChannel('game-room');
await streamChannel.join({ token: 'your_token' });

// 离开频道
try {
  const response = await streamChannel.leave();
  console.log('Left channel:', response.channelName);
} catch (error) {
  if (error instanceof RtmError) {
    console.error('Leave failed:', error.errorCode, error.reason);
  }
}
```

## release [#release]

### 接口描述 [#接口描述-5]

如果你不再需要某个频道，你可以调用 `release` 方法销毁对应的 Stream Channel 实例以释放资源。调用 `release` 方法销毁 Stream Channel 实例不会销毁该频道，后续可通过再次调用 `createStreamChannel` 和 `join` 重新加入该频道。

:::info[信息]
- 该方法仅适用于 Stream Channel。如果不先调用 `leave` 离开频道而直接调用 `release` 销毁频道实例，SDK 会自动调用 `leave` 并触发对应的事件。
- `release` 需要在非回调内的子线程调用，避免在回调中执行。
:::

### 接口方法 [#接口方法-5]

你可以通过以下方式调用 `release` 方法：

```typescript
release(): number
```

### 返回值 [#返回值-5]

返回错误码：

- `0`：方法调用成功。
- 非 `0`：方法调用失败，返回对应的错误码。详见[错误排查](/zh-CN/realtime-media/rtm/build/troubleshooting)。

### 基本用法 [#基本用法-5]

```typescript
import { RtmClient } from '@shengwang/rtm-full';

// 使用完毕后释放资源
const errorCode = streamChannel.release();

if (errorCode === 0) {
  console.log('Stream channel released successfully');
} else {
  console.error('Failed to release stream channel, error code:', errorCode);
}
```

- < 0：方法调用失败。