# Topic (/zh-CN/api-reference/rtm/react-native/topic)
> For AI agents: see the complete documentation index at [llms.txt](/llms.txt).
Topic 是 Stream Channel 中的数据流管理机制。用户可以在 Stream Channel 中利用此特性进行数据流的订阅、分发、事件通知等。
:::info[信息]
Topic 只存在于 Stream Channel。所以用户在使用相关特性之前,需要先创建一个 `RTMStreamChannel` 对象实例。
:::
## joinTopic [#jointopic]
### 接口描述 [#接口描述]
加入 Topic 的目的在于注册成为该 Topic 的消息发布者之一,从而让用户具备发送消息的能力。是否执行该操作都不影响该用户是否成为该 Topic 的订阅者。
:::info[信息]
- 当前 RTM 支持单客户端在同一个 Stream Channel 中同时加入 8 个 Topic。
- 在执行此操作之前,用户需要首先创建 `RTMStreamChannel` 对象实例,并调用 `join` 方法加入频道。
:::
成功加入 Topic 后,订阅该 Topic 并添加事件监听的用户会收到 `remoteJoinTopic` 类型的 `topic` 事件通知。详见[事件监听](/zh-CN/api-reference/rtm/react-native/configuration#事件监听)。
### 接口方法 [#接口方法]
你可以通过以下方式调用 `joinTopic` 方法:
```typescript
joinTopic(
topicName: string,
options?: JoinTopicOptions
): Promise;
```
| 参数 | 类型 | 是否必填 | 默认值 | 描述 |
| -------- | --- | ----- | --- | ----------- |
| `topicName` | string | 必填 | - | Topic 名称。 |
| `options` | object | 选填 | - | 预留参数。 |
### 基本用法 [#基本用法]
```typescript
try {
const result = await stChannel.joinTopic( "gesture", options);
console.log( result);
} catch (status) {
console.log(status);
}
```
### 返回值 [#返回值]
如果方法调用成功,则返回一个 `JoinTopicResponse` 类型数据:
```typescript
type JoinTopicResponse = {
timestamp: number, // 预留字段
topicName: string // 注册的 Topic 的名称
}
```
如果方法调用失败,则返回一个 `ErrorInfo` 类型数据:
```typescript
type ErrorInfo = {
error: boolean; // 本次操作是否出错
reason: string; // 本次操作的 API 名称
operation: string; // 错误码
errorCode: number; // 错误描述
};
```
你可以通过检索 `errorCode` 字段的[错误码](/zh-CN/realtime-media/rtm/build/troubleshooting)了解错误原因,并找到对应的解决方法。
## publishTopicMessage [#publishtopicmessage]
### 接口描述 [#接口描述-1]
`publishTopicMessage` 方法用于向 Topic 发送消息,频道中订阅此 Topic 及此消息发布者的用户会在 100 毫秒内收到此消息。调用 `publishTopicMessage` 方法需要用户首先加入 Stream Channel 并且通过调用 `joinTopic` 方法注册成为该 Topic 的消息发布者。
用户发送的消息在传输的过程中会被 TLS 加密,数据链路加密默认开启且无法关闭。用户也可以在出初始化的时候开启端侧加密,以获得更高的数据安全等级,详见[初始配置](/zh-CN/api-reference/rtm/react-native/configuration)。
### 接口方法 [#接口方法-1]
你可以通过以下方式调用 `publishTopicMessage` 方法:
```typescript
publishTopicMessage(
topicName: string,
message: string | Uint8Array,
options?: TopicMessageOptions
): Promise;
```
| 参数 | 类型 | 是否必填 | 默认值 | 描述 |
| -------- | --- | ------- | --- | --------- |
| `topicName` | string | 必填 | - | Topic 名称。 |
| `message` | string \| Uint8Array | 必填 | - | 消息负载。支持任意 string 类型和 Uint8Array 类型。
| `options` | object | 选填 | - | 消息选项。 |
`options` 包含以下属性:
| 属性 | 类型 | 是否必填 | 默认值 | 描述 |
| --------- | --- | ----- | --- | ---------- |
| `messageType` | RtmMessageType | 选填 | - | RTM 消息类型。支持 `binary` 和 `string`。 |
| `sentTs` | string | 选填 | - | 和媒体流消息同步的时间戳。仅在加入 Stream 频道时将 `syncWithMedia` 设为 `true` 时有效。|
| `customType` | string | 选填 | - | 用户自定义字段。仅支持 string 型。 |
### 接口方法 [#接口方法-2]
示例 1:向指定频道发送 string 消息
```typescript
try {
const result = await stChannel.publishTopicMessage("Gesture", "message");
console.log(result);
} catch (status) {
console.log(status);
}
```
示例 2:向指定频道发送 Uint8Array 消息
```typescript
try {
const result = await stChannel.publishTopicMessage("Gesture", new Uint8Array(Buffer.from(your_message)));
console.log(result);
} catch (status) {
console.log(status);
}
```
### 返回值 [#返回值-1]
如果方法调用成功,则返回一个`PublishTopicMessageResponse` 类型数据:
```typescript
type PublishTopicMessageResponse = {
timestamp: number, // 预留字段
topicName: string // 发送消息的 Topic 的名称
}
```
如果方法调用失败,则返回一个 `ErrorInfo` 类型数据:
```typescript
type ErrorInfo = {
error: boolean; // 本次操作是否出错
reason: string; // 本次操作的 API 名称
operation: string; // 错误码
errorCode: number; // 错误描述
};
```
你可以通过检索 `errorCode` 字段的[错误码](/zh-CN/realtime-media/rtm/build/troubleshooting)了解错误原因,并找到对应的解决方法。
## leaveTopic [#leavetopic]
### 接口描述 [#接口描述-2]
当你不再需要向某个 Topic 发布消息,你可以调用 `leaveTopic` 方法取消注册为该 Topic 的消息发布者,从而释放资源。该方法不影响你是否订阅该 Topic,也不影响其他用户对该 Topic 的任何操作。
成功调用该方法后,订阅该频道并开启事件监听的用户会收到 `remoteLeaveTopic` 类型的 `topic` 事件通知,详见[事件监听](/zh-CN/api-reference/rtm/react-native/configuration#事件监听)。
### 接口方法 [#接口方法-3]
你可以通过以下方式调用 `leaveTopic` 方法:
```typescript
leaveTopic(topicName: string): Promise;
```
| 参数 | 类型 | 是否必填 | 默认值 | 描述 |
| -------- | --- | ----- | --- | ---------- |
| `topicName` | string | 必填 | - | Topic 名称。 |
### 基本用法 [#基本用法-1]
```typescript
try {
const result = await stChannel.leaveTopic("gesture");
console.log(result);
} catch (status) {
console.log(status);
}
```
### 返回值 [#返回值-2]
如果方法调用成功,则返回一个 `LeaveTopicResponse` 类型数据:
```typescript
type LeaveTopicResponse = {
timestamp: number, // 预留字段
topicName: string // 发送消息的 Topic 的名称
}
```
如果方法调用失败,则返回一个 `ErrorInfo` 类型数据:
```typescript
type ErrorInfo = {
error: boolean; // 本次操作是否出错
reason: string; // 本次操作的 API 名称
operation: string; // 错误码
errorCode: number; // 错误描述
};
```
你可以通过检索 `errorCode` 字段的[错误码](/zh-CN/realtime-media/rtm/build/troubleshooting)了解错误原因,并找到对应的解决方法。
## subscribeTopic [#subscribetopic]
### 接口描述 [#接口描述-3]
加入频道后,你可以调用 `subscribeTopic` 方法订阅该频道中 Topic 的消息发布者。
`subscribeTopic` 为增量方法。例如,第一次调用该方法时,订阅消息发布者列表为 `[UserA, UserB]`,第二次调用该方法时,订阅消息发布者列表为 `[UserB, UserC]`,则最后成功订阅的结果是 `[UserA, UserB, UserC]`。
同一个用户在同一个频道中最多只能同时订阅 50 个 Topic,且每个 Topic 中最多只能订阅 64 个消息发布者。
### 接口方法 [#接口方法-4]
你可以通过以下方式调用 `subscribeTopic` 方法:
```typescript
subscribeTopic(
topicName: string,
options?: TopicOptions
): Promise;
```
| 参数 | 类型 | 是否必填 | 默认值 | 描述 |
| -------- | --- | ----- | --- | ---------------- |
| `topicName` | string | 必填 | - | Topic 名称。 |
| `options` | object | 选填 | - | 订阅 Topic 选项。 |
`options` 对象中包含以下属性:
| 属性 | 类型 | 是否必填 | 默认值 | 描述 |
| ---- | ----- | ----- | --- | ------- |
| `users` | string[] | 选填 | - | 需要订阅的消息发布者(Publisher)的 `UserId` 列表,如果不设置,则默认随机订阅不超过 64 个用户。 |
| `userCount` | number | 选填 | 0 | 订阅的消息发布者的数量。|
### 基本用法 [#基本用法-2]
示例 1:订阅 Topic 中指定的消息发布者
```typescript
var UIDs = ["zhangsan", "lisi", "wangwu"];
try {
const result = await rtm.subscribeTopic("Gesture", { users: UIDs });
console.log(result);
} catch (status) {
console.log(status);
}
```
示例 2:随机订阅 Topic 中的 64 个消息发布者
```typescript
try {
const result = await stChannel.subscribeTopic("Gesture");
console.log(result);
}catch (status) {
console.log(status);
}
```
### 返回值 [#返回值-3]
如果方法调用成功,则返回一个 `SubscribeTopicResponse` 类型数据:
```typescript
type SubscribeTopicResponse = {
succeedUsers: string[], // 订阅成功的用户列表
failedUsers: string[], // 订阅失败的用户列表
timestamp: number, // 预留字段
topiclName: string // 订阅 Topic 的名称
}
```
如果方法调用失败,则返回一个 `ErrorInfo` 类型数据:
```typescript
type ErrorInfo = {
error: boolean; // 本次操作是否出错
reason: string; // 本次操作的 API 名称
operation: string; // 错误码
errorCode: number; // 错误描述
};
```
你可以通过检索 `errorCode` 字段的[错误码](/zh-CN/realtime-media/rtm/build/troubleshooting)了解错误原因,并找到对应的解决方法。
## unsubscribeTopic [#unsubscribetopic]
### 接口描述 [#接口描述-4]
如果你对某个 Topic 不再感兴趣,或者不再需要订阅 Topic 中的一个或多个消息发布者,你可以调用 `unsubscribeTopic` 方法取消订阅该 Topic 或取消订阅该 Topic 中指定的消息发布者。
### 接口方法 [#接口方法-5]
你可以通过以下方式调用 `unsubscribeTopic` 方法:
```typescript
unsubscribeTopic(
topicName: string,
options?: TopicOptions
): Promise;
```
| 参数 | 类型 | 是否必填 | 默认值 | 描述 |
| -------- | --- | ----- | --- | ----- |
| `topicName` | string | 必填 | - | Topic 名称。 |
| `options` | object | 选填 | - | 取消订阅 Topic 选项。如果不设置,则取消对整个 Topic 的订阅。 |
`options` 对象包含以下属性:
| 属性 | 类型 | 是否必填 | 默认值 | 描述 |
| ---- | ----- | ----- | --- | ------- |
| `users` | string[] | 选填 | - | 需要取消订阅的消息发布者的用户 ID 列表。如果不设置,则取消对整个 Topic 的订阅。 |
| `userCount` | number | 选填 | 0 | 取消订阅的消息发布者的数量。|
### 基本用法 [#基本用法-3]
示例 1:取消订阅 Topic 中指定的消息发布者
```typescript
try {
const result = await rtm.unsubscribeTopic("Gesture", { users: ["Tony", "Bo"] });
console.log("unsubscribe Topic success: ", result);
} catch (status) {
console.log("unsubscribe Topic failed: ", result);
}
```
示例 2:随机取消订阅 Topic 中的 64 个消息发布者
```typescript
try {
const result = await rtm.unsubscribeTopic("Gesture");
console.log("unsubscribe topic success: ", result);
} catch (status) {
console.log("unsubscribe topic failed: ", result);
}
```
### 返回值 [#返回值-4]
如果方法调用成功,则返回一个 `UnsubscribeTopicResponse` 类型数据:
```typescript
type UnsubscribeTopicResponse = {
timestamp: number // 预留字段
}
```
如果方法调用失败,则返回一个 `ErrorInfo` 类型数据:
```typescript
type ErrorInfo = {
error: boolean; // 本次操作是否出错
reason: string; // 本次操作的 API 名称
operation: string; // 错误码
errorCode: number; // 错误描述
};
```
你可以通过检索 `errorCode` 字段的[错误码](/zh-CN/realtime-media/rtm/build/troubleshooting)了解错误原因,并找到对应的解决方法。