docs(useWebSocket): update heartbeat doc

alibaba · Sep 24, 2024 · 4fd8645 · 4fd8645
1 parent 03d87d3
commit 4fd8645
Show file tree

Hide file tree

Showing 3 changed files with 66 additions and 12 deletions.
diff --git a/packages/hooks/src/useWebSocket/demo/demo2.tsx b/packages/hooks/src/useWebSocket/demo/demo2.tsx
@@ -15,7 +15,10 @@ export default () => {
     'wss://ws.postman-echo.com/raw',
     {
       heartbeat: {
-        interval: 1000 * 3,
+        message: 'ping',
+        responseMessage: 'pong',
+        interval: 3000,
+        responseTimeout: 10000,
       },
     },
   );

diff --git a/packages/hooks/src/useWebSocket/index.en-US.md b/packages/hooks/src/useWebSocket/index.en-US.md
@@ -13,6 +13,28 @@ A hook for WebSocket.
 
 <code src="./demo/demo1.tsx" />
 
+### Heartbeat example
+
+By setting the `heartbeat`, you can enable the heartbeat mechanism. After a successful connection, `useWebSocket` will send a `message` every `interval` milliseconds. If no messages are received within the `responseTimeout`, it may indicate that there is an issue with the connection, and the connection will be closed.
+
+It is important to note that if a `responseMessage` is defined, it will be ignored, and it will not trigger the `onMessage` event or update the `latestMessage`.
+
+```tsx | pure
+useWebSocket(
+  'wss://ws.postman-echo.com/raw',
+  {
+    heartbeat: {
+      message: 'ping',
+      responseMessage: 'pong',
+      interval: 3000,
+      responseTimeout: 10000,
+    }
+  }
+);
+```
+
+<code src="./demo/demo2.tsx" />
+
 ## API
 
 ```typescript
@@ -23,6 +45,13 @@ enum ReadyState {
   Closed = 3,
 }
 
+interface HeartbeatOptions{
+  message?: string;
+  responseMessage?: string;
+  interval?: number;
+  responseTimeout? :number;
+}
+
 interface Options {
   reconnectLimit?: number;
   reconnectInterval?: number;
@@ -31,6 +60,7 @@ interface Options {
   onMessage?: (message: WebSocketEventMap['message'], instance: WebSocket) => void;
   onError?: (event: WebSocketEventMap['error'], instance: WebSocket) => void;
   protocols?: string | string[];
+  heartbeat?: boolean | HeartbeatOptions;
 }
 
 interface Result {
@@ -68,11 +98,12 @@ useWebSocket(socketUrl: string, options?: Options): Result;
 
 ### HeartbeatOptions
 
-| 参数            | 说明                                                                 | 类型     | 默认值 |
-| --------------- | -------------------------------------------------------------------- | -------- | ------ |
-| message         | Heartbeat message                                                    | `string` | `ping` |
-| responseMessage | Heartbeat response message, `latestMessage` will ignore this message | `string` | -      |
-| interval        | Heartbeat Interval(ms)                                               | `number` | `6000` |
+| 参数            | 说明                                                                                                                                                                                     | 类型     | 默认值  |
+| --------------- | ---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | -------- | ------- |
+| message         | Heartbeat message                                                                                                                                                                        | `string` | `ping`  |
+| responseMessage | Heartbeat response message; the `onMessage` and `latestMessage` will ignore this message.                                                                                                | `string` | `pong`  |
+| interval        | Heartbeat Interval(ms)                                                                                                                                                                   | `number` | `5000`  |
+| responseTimeout | The heartbeat timeout (ms) indicates that if no heartbeat messages or other messages are received within this time, the connection will be considered abnormal and will be disconnected. | `number` | `10000` |
 
 ### Result
 

diff --git a/packages/hooks/src/useWebSocket/index.zh-CN.md b/packages/hooks/src/useWebSocket/index.zh-CN.md
@@ -13,7 +13,25 @@ nav:
 
 <code src="./demo/demo1.tsx" />
 
-### 测试示例
+### 心跳示例
+
+通过设置 `heartbeat`，可以启用心跳机制，`useWebSocket` 在连接成功后，每隔 `interval` 毫秒发送一个 `message`，如果超过 `responseTimeout` 时间未收到任何消息，可能表示连接出问题，将关闭连接。
+
+需要注意的是，如果定义了 `responseMessage`，该消息将被忽略，不会触发 `onMessage` 事件，也不会更新 `latestMessage`。
+
+```tsx | pure
+useWebSocket(
+  'wss://ws.postman-echo.com/raw',
+  {
+    heartbeat: {
+      message: 'ping',
+      responseMessage: 'pong',
+      interval: 3000,
+      responseTimeout: 10000,
+    }
+  }
+);
+```
 
 <code src="./demo/demo2.tsx" />
 
@@ -31,6 +49,7 @@ interface HeartbeatOptions{
   message?: string;
   responseMessage?: string;
   interval?: number;
+  responseTimeout? :number;
 }
 
 interface Options {
@@ -79,11 +98,12 @@ useWebSocket(socketUrl: string, options?: Options): Result;
 
 ### HeartbeatOptions
 
-| 参数            | 说明                                       | 类型     | 默认值 |
-| --------------- | ------------------------------------------ | -------- | ------ |
-| message         | 心跳消息                                   | `string` | `ping` |
-| responseMessage | 心跳回复消息，`latestMessage` 会忽略该消息 | `string` | `pong` |
-| interval        | 心跳时间间隔（ms）                         | `number` | `6000` |
+| 参数            | 说明                                                                         | 类型     | 默认值  |
+| --------------- | ---------------------------------------------------------------------------- | -------- | ------- |
+| message         | 心跳消息                                                                     | `string` | `ping`  |
+| responseMessage | 心跳回复消息，`onMessage`、`latestMessage` 会忽略该消息                      | `string` | `pong`  |
+| interval        | 心跳时间间隔（ms）                                                           | `number` | `5000`  |
+| responseTimeout | 心跳超时时间(ms)，超过此时间未收到心跳消息或其他消息将视为连接异常并断开连接 | `number` | `10000` |
 
 ### Result