用于WebSocket通信的React Hook-React开发

# React useWebSocket v2 [Live Demo](https://robtaussig.com/socket/) Note: `wss://demos.kaazing.com/echo` has been down lately, so the demo will fail to connect when using that as the endpoint. On the plus side, this demonstrates the behavior of a connection failure. [Test in StackBlitz](https://stackblitz.com/edit/react-huzf9f) React Hook designed to provide robust WebSocket integrations to your React Components. Experimental support for SocketIO (read documentation below for more information) Pull requests welcomed! ## New in v2 - `useWebSocket` now returns an object instead of an array. This allows you to pick out specific features/properties to suit your use-case as well as removing mental overhead of keeping track of item order. - `lastJsonMessage` and `sendJsonMessage` added to return value to reduce need to stringify and parse outgoing and incoming messages at the component level. - The optional object passed as the second parameter no longer needs to be static. - Components can close/unsubscribe from a WebSocket by passing `false` as the third parameter. This provides a more explicit solution than the previous method of setting the `socketUrl` to `null`. Both methods work and are supported usage. ## Example Implementation ```js import React, { useState, useCallback, useMemo, useRef } from 'react'; import useWebSocket, { ReadyState } from 'react-use-websocket'; export const WebSocketDemo = () => { //Public API that will echo messages sent to it back to the client const [socketUrl, setSocketUrl] = useState('wss://echo.websocket.org'); const messageHistory = useRef([]); const { sendMessage, lastMessage, readyState, } = useWebSocket(socketUrl); messageHistory.current = useMemo(() => messageHistory.current.concat(lastMessage),[lastMessage]); const handleClickChangeSocketUrl = useCallback(() => setSocketUrl('wss://demos.kaazing.com/echo'), []); const handleClickSendMessage = useCallback(() => sendMessage('Hello'), []); const connectionStatus = { [ReadyState.CONNECTING]: 'Connecting', [ReadyState.OPEN]: 'Open', [ReadyState.CLOSING]: 'Closing', [ReadyState.CLOSED]: 'Closed', [ReadyState.UNINSTANTIATED]: 'Uninstantiated', }[readyState]; return ( <div> <button onClick={handleClickChangeSocketUrl} > Click Me to change Socket Url </button> <button onClick={handleClickSendMessage} disabled={readyState !== ReadyState.OPEN} > Click Me to send 'Hello' </button> <span>The WebSocket is currently {connectionStatus}</span> {lastMessage ? <span>Last message: {lastMessage.data}</span> : null} <ul> {messageHistory.current .map((message, idx) => <span key={idx}>{message ? message.data : null}</span>)} </ul> </div> ); }; ``` From the example above, the component will rerender every time the `readyState` of the WebSocket changes, as well as when the WebSocket receives a message (which will change `lastMessage`). `sendMessage` is a memoized callback that will pass the message to the current WebSocket (referenced to internally with `useRef`). A demo of this can be found [here](https://robtaussig.com/socket/). Each component uses its own `useWebSocket` hook. This implementation takes advantage of passing an optional options object (documented below). Among setting event callbacks (for `onmessage`, `onclose`, `onerror`, and `onopen`) that will log to the console, it is using the `share` option -- if multiple components pass the same socketUrl to `useWebSocket` and with `share` set to true, then only a single WebSocket will be created and `useWebSocket` will manage subscriptions/unsubscriptions internally. `useWebSocket` will keep track of how many subscribers any given WebSocket has and will automatically free it from memory once there are no subscribers remaining (a subscriber unsubscribes when it either unmounts or changes its socketUrl). Of course, multiple WebSockets can be created with the same target url, and so components are not required to share the same communication pipeline. ## Features - Handles reconnect logic - Multiple components can (optionally) use a single WebSocket, which is closed and cleaned up when all subscribed components have unsubscribed/unmounted - Written in TypeScript - Socket.io support - No more waiting for the WebSocket to open before messages can be sent. Pre-connection messages are queued up and sent on connection - Provides direct access to unshared WebSockets, while proxying shared WebSockets. Proxied WebSockets provide subscribers controlled access to the underlying (shared) WebSocket, without allowing unsafe behavior - Seamlessly works with server-sent-events and the [EventSource API](https://developer.mozilla.org/en-US/docs/Web/API/EventSource) ## Getting Started ```sh npm install react-use-websocket ``` ```js import useWebSocket from 'react-use-websocket'; // In functional React component // This can also be an async getter function. See notes below on Async Urls. const socketUrl = 'wss://echo.websocket.org'; const { sendMessage, sendJsonMessage, lastMessage, lastJsonMessage, readyState, getWebSocket } = useWebSocket(socketUrl, { onOpen: () => console.log('opened'), //Will attempt to reconnect on all close events, such as server shutting down shouldReconnect: (closeEvent) => true, }); ``` ## Interface ```ts type UseWebSocket = ( //Url can be return value of a memoized async function. url: string | () => Promise<string>, options: { fromSocketIO?: boolean; queryParams?: { [field: string]: any }; protocols?: string | string[]; share?: boolean; onOpen?: (event: WebSocketEventMap['open']) => void; onClose?: (event: WebSocketEventMap['close']) => void; onMessage?: (event: WebSocketEventMap['message']) => void; onError?: (event: WebSocketEventMap['error']) => void; onReconnectStop?: (numAttempts: number) => void; shouldReconnect?: (event: WebSocketEventMap['close']) => boolean; reconnectInterval?: number; reconnectAttempts?: number; filter?: (message: WebSocketEventMap['message']) => boolean; retryOnError?: boolean; eventSourceOptions?: EventSourceInit; } = {}, shouldConnect: boolean = true, ): { sendMessage: (message: string) => void, //jsonMessage must be JSON-parsable sendJsonMessage: (jsonMessage: any) => void, //null before first received message lastMessage: WebSocketEventMap['message'] | null, //null before first received message. If message.data is not JSON parsable, then this will be a static empty object lastJsonMessage: WebSocketEventMap['message']['data'] | null, // -1 if uninstantiated, otherwise follows WebSocket readyState mapping: 0: 'Connecting', 1 'OPEN', 2: 'CLOSING', 3: 'CLOSED' readyState: number, // If using a shared websocket, return value will be a proxy-wrapped websocket, with certain properties/methods protected getWebSocket: () => (WebSocket | null), } ``` ## Requirements - React 16.8+ - Cannot be used within a class component (must be a functional component that supports React Hooks) ## Async Urls Instead of passing a string as the first argument to useWebSocket, you can pass a function that returns a string (or a promise that resolves to a string). It's important to note, however, that other rules still apply -- namely, that if the function reference changes, then it will be called again, potentially instantiating a new WebSocket if the returned url changes. ```js import useWebSocket from 'react-use-websocket'; // In functional React component const getSocketUrl = useCallback(() => { return new Promise(resolve => { setTimeout(() => { resolve('wss://echo.websocket.org'); }, 2000); }); }, []); const { sendMessage, lastMessage, readyState, getWebSocket } = useWebSocket(getSocketUrl, STATIC_OPTIONS); ``` ## API ### sendMessage ```ts type sendMessage = (messa