@realsee/live 0.7.3-alpha.0 → 0.7.4

package/dist/live/controller.d.ts

@@ -4,115 +4,236 @@ import { RobustWebSocketEventDetail } from '../utils/RobustWebSocket';
 import { Subscribe } from '../utils/subscribe';
 /**
  * 带看控制器事件映射
+ *
+ * 定义了 LiveController 可以触发的事件类型
  */
 export type LiveControllerEventMap = {
     /**
-     * 带看状态变更
-     * @param state
-     * @param prevState
-     * @returns
+     * 带看连接状态变更事件
+     *
+     * @param state 当前连接状态
+     * @param prevState 之前的连接状态
      */
     stateChange: (state: LiveState, prevState: LiveState) => void;
     /**
-     * 接收到带看消息
-     * @param message
-     * @returns
+     * 接收到带看消息事件
+     *
+     * @param message 接收到的消息对象
      */
     message: (message: LiveMsg) => void;
     /**
-     * 带看重连中
-     * @param detail
-     * @returns
+     * 带看重连中事件
+     *
+     * 当 WebSocket 连接断开并开始重连时触发
+     *
+     * @param detail 重连详情，包含重连次数等信息
      */
     reconnecting: (detail: RobustWebSocketEventDetail) => void;
     /**
-     * 带看重连成功
-     * @param detail
-     * @returns
+     * 带看重连成功事件
+     *
+     * 当 WebSocket 重连成功后触发
+     *
+     * @param detail 重连详情，包含重连次数等信息
      */
     reconnected: (detail: RobustWebSocketEventDetail) => void;
 };
 /**
- * 带看控制器
+ * 带看控制器类
+ *
+ * 负责管理 WebSocket 连接的建立、消息收发、重连等底层通信功能。
+ * 基于 RobustWebSocket 实现，提供自动重连能力。
+ *
+ * @example
+ * ```typescript
+ * const controller = new LiveController()
+ *
+ * // 监听状态变化
+ * controller.on('stateChange', (state, prevState) => {
+ *   console.log(`状态从 ${prevState} 变为 ${state}`)
+ * })
+ *
+ * // 监听消息
+ * controller.on('message', (message) => {
+ *   console.log('收到消息:', message)
+ * })
+ *
+ * // 打开连接
+ * controller.open('wss://example.com/live')
+ *
+ * // 发送消息
+ * controller.sendMessage({ command: 'test', data: {} })
+ *
+ * // 关闭连接
+ * await controller.close()
+ * ```
  */
 export declare class LiveController extends Subscribe<LiveControllerEventMap> {
     /**
-     * ws代理器
+     * WebSocket 代理器（内部使用）
+     * 基于 RobustWebSocket 实现，提供自动重连能力
      */
     private _ws;
     /**
-     * 带看连接状态
+     * 带看连接状态（内部存储）
      */
     private _state;
+    /**
+     * 设置连接状态
+     *
+     * 当状态改变时，会自动触发 stateChange 事件
+     *
+     * @param state 新的连接状态
+     */
     set state(state: LiveState);
+    /**
+     * 获取当前连接状态
+     *
+     * @returns 当前连接状态
+     */
     get state(): LiveState;
+    /**
+     * 创建带看控制器实例
+     *
+     * 会自动初始化 WebSocket 事件监听器
+     */
     constructor();
     /**
-     * 添加事件监听
+     * 添加 WebSocket 事件监听（内部方法）
+     * 监听 WebSocket 的各种事件并转换为控制器事件
      */
     private _addWebSocketEventListeners;
     /**
-     * 移除事件监听
+     * 移除 WebSocket 事件监听（内部方法）
+     * 在销毁实例时调用，清理所有事件监听器
      */
     private _removeWebSocketEventListeners;
     /**
-     * 处理房间关闭事件
-     * @param event
+     * 处理 WebSocket 关闭事件（内部方法）
+     *
+     * @param event WebSocket 关闭事件对象
      */
     private _handleCloseEvent;
     /**
-     * 处理房间正在关闭事件（这个时候可能是断网了）
+     * 处理 WebSocket 正在关闭事件（内部方法）
+     *
+     * 当连接正在关闭时触发，可能是由于网络断开等原因
      */
     private _handleClosingEvent;
     /**
-     * 连接中
-     * @param event
+     * 处理 WebSocket 连接中事件（内部方法）
+     *
+     * 当开始连接或重连时触发，如果是重连会触发 reconnecting 事件
+     *
+     * @param ev WebSocket 连接事件对象
      */
     private _handleConnectingEvent;
     /**
-     * 连接发送异常
-     * @param event
+     * 处理 WebSocket 错误事件（内部方法）
+     *
+     * @param event 错误事件对象
      */
     private _handleErrorEvent;
     /**
-     * 接收到消息
-     * @param event
+     * 处理 WebSocket 消息事件（内部方法）
+     *
+     * 解析接收到的消息并触发 message 事件
+     *
+     * @param event WebSocket 消息事件对象
      */
     private _handleMessageEvent;
     /**
-     * 连接建立成功
-     * @param event
+     * 处理 WebSocket 连接成功事件（内部方法）
+     *
+     * 当连接建立成功时触发，如果是重连成功会触发 reconnected 事件
+     *
+     * @param event WebSocket 打开事件对象
      */
     private _handleOpenEvent;
     /**
-     * 处理超时
-     * @param event
+     * 处理 WebSocket 连接超时事件（内部方法）
+     *
+     * @param event WebSocket 超时事件对象
      */
     private _handleTimeoutEvent;
     /**
-     * 释放资源，释放之后需要重新实例化
-     * @returns
+     * 释放控制器资源
+     *
+     * 移除所有事件监听器并关闭 WebSocket 连接。
+     * 释放后需要重新实例化才能使用。
+     *
+     * @returns Promise<boolean> 关闭是否成功
+     * @example
+     * ```typescript
+     * await controller.dispose()
+     * ```
      */
     dispose: () => Promise<boolean>;
     /**
-     * 开启房间链接
-     * @param url  房间链接
-     * @returns
+     * 打开 WebSocket 连接
+     *
+     * 开始建立与服务器的 WebSocket 连接。
+     *
+     * @param url WebSocket 连接地址（ws:// 或 wss://）
+     * @example
+     * ```typescript
+     * controller.open('wss://example.com/live?ticket=xxx')
+     * ```
      */
     open: (url: string) => void;
     /**
-     * 关闭房间
-     * @param code
-     * @param reason
+     * 关闭 WebSocket 连接
+     *
+     * 关闭与服务器的 WebSocket 连接。
+     *
+     * @param code 关闭代码（可选），WebSocket 关闭码
+     * @param reason 关闭原因（可选），关闭原因字符串
+     * @returns Promise<boolean> 关闭是否成功
+     * @example
+     * ```typescript
+     * // 正常关闭
+     * await controller.close()
+     *
+     * // 指定关闭码和原因
+     * await controller.close(1000, '正常关闭')
+     * ```
      */
     close: (code?: string | number | undefined, reason?: string | undefined) => Promise<boolean>;
     /**
-     * 发送数据
-     * @param data
+     * 发送消息到服务器
+     *
+     * 只有在连接状态为 OPEN 时才能发送消息。
+     * 消息会被自动序列化为 JSON 字符串。
+     *
+     * @param data 要发送的数据对象，不能为 undefined 或 null
+     * @returns 发送是否成功
+     * @throws {Error} 如果消息为空或连接未打开，会抛出错误
+     * @example
+     * ```typescript
+     * // 发送消息
+     * controller.sendMessage({
+     *   command: 'test',
+     *   data: { message: 'hello' }
+     * })
+     *
+     * // 检查连接状态
+     * if (controller.state === LiveState.OPEN) {
+     *   controller.sendMessage({ command: 'ping' })
+     * }
+     * ```
      */
     sendMessage: (data?: any) => void | undefined;
     /**
-     * 准备关闭带看
+     * 准备关闭带看连接
+     *
+     * 标记连接为显式关闭，防止自动重连。
+     * 通常在用户主动退出时调用。
+     *
+     * @example
+     * ```typescript
+     * controller.readyClose()
+     * await controller.close()
+     * ```
      */
     readyClose: () => void;
 }

package/dist/live/createLive.d.ts

@@ -1,8 +1,40 @@
 import { LiveOptions } from '../typings/live/LiveOptions';
 import { Live } from './live';
 /**
- * 创建`Live`实例
- * @param opts
- * @returns
+ * 创建 Live 带看实例
+ *
+ * 这是一个工厂函数，用于创建 Live 实例。在创建新实例前，会先清理全局的旧实例（如果存在）。
+ *
+ * @template KeyframesSnapshot 帧数据快照类型，必须是一个对象类型
+ * @param opts 带看配置选项，详见 {@link LiveOptions}
+ * @returns Live 实例
+ * @example
+ * ```typescript
+ * // 定义帧数据类型
+ * interface MyKeyframes {
+ *   camera: { position: [number, number, number] }
+ *   annotation: { text: string; position: [number, number] }
+ * }
+ *
+ * // 创建 Live 实例
+ * const live = createLive<MyKeyframes>({
+ *   url: 'wss://example.com/live',
+ *   getTicket: async () => {
+ *     const response = await fetch('/api/get-ticket')
+ *     return response.json().ticket
+ *   },
+ *   getVoiceSign: async (params) => {
+ *     const response = await fetch('/api/get-voice-sign', {
+ *       method: 'POST',
+ *       body: JSON.stringify(params)
+ *     })
+ *     return response.json()
+ *   },
+ *   useBuiltInRTC: true
+ * })
+ *
+ * // 连接带看
+ * await live.connect()
+ * ```
  */
 export declare const createLive: <KeyframesSnapshot extends Record<string, any>>(opts: LiveOptions) => Live<KeyframesSnapshot>;

package/dist/live/createLiveReact.d.ts

@@ -2,14 +2,62 @@ import { default as React } from 'react';
 import { BuiltinActionType, BuiltinEventType, KeyframeEventType, LiveConnectOptions, LiveEventType, LiveOptions, MicroStatus, RTCEventType, RTCType, UserInfo } from '../typings';
 import { LiveState } from '../typings/live/LiveState';
 import { Live } from './live';
+/**
+ * LiveProvider 组件的属性类型
+ *
+ * @template KeyframesSnapshot 帧数据快照类型
+ */
 export type LiveProviderPropTypes<KeyframesSnapshot extends Record<string, any>> = {
+    /**
+     * 子组件
+     */
     children?: React.ReactNode;
+    /**
+     * 自定义 Live 实例（可选，默认使用内部创建的实例）
+     */
     live?: Live<KeyframesSnapshot>;
 };
 /**
- * 创建 LiveReact 实例，并提供 `React` 技术栈相关工具链。
- * @param options 带看配置
- * @returns 返回当前的带看上下文实例
+ * 创建 LiveReact 实例，并提供 React 技术栈相关工具链
+ *
+ * 这个函数会创建一个 Live 实例和一系列 React Hooks，用于在 React 组件中方便地使用带看功能。
+ * 返回的对象包含 LiveProvider 组件和各种 Hooks。
+ *
+ * @template KeyframesSnapshot 帧数据快照类型，必须是一个对象类型
+ * @param options 带看配置选项，详见 {@link LiveOptions}
+ * @returns 包含 LiveProvider 组件和各种 Hooks 的对象
+ * @example
+ * ```typescript
+ * // 定义帧数据类型
+ * interface MyKeyframes {
+ *   camera: { position: [number, number, number] }
+ *   annotation: { text: string; position: [number, number] }
+ * }
+ *
+ * // 创建 LiveReact 实例
+ * const { LiveProvider, useLiveAction, useKeyframe } = createLiveReact<MyKeyframes>({
+ *   url: 'wss://example.com/live',
+ *   getTicket: async () => 'ticket',
+ *   getVoiceSign: async (params) => ({ sdkAppId: 0, userId: '', userSig: '', roomId: '' }),
+ *   useBuiltInRTC: true
+ * })
+ *
+ * // 在组件中使用
+ * function App() {
+ *   return (
+ *     <LiveProvider>
+ *       <MyComponent />
+ *     </LiveProvider>
+ *   )
+ * }
+ *
+ * function MyComponent() {
+ *   const { connect, sendKeyframe } = useLiveAction()
+ *   const [camera, setCamera] = useKeyframe('camera')
+ *
+ *   // 使用带看功能...
+ * }
+ * ```
  */
 export declare function createLiveReact<KeyframesSnapshot extends Record<string, any>>(options: LiveOptions): {
     live: Live<KeyframesSnapshot>;