request-iframe 0.0.2 → 0.0.3

package/README.CN.md

@@ -34,6 +34,13 @@
   - [追踪模式](#追踪模式)
   - [多语言支持](#多语言支持)
 - [API 参考](#api-参考)
+- [React Hooks](#react-hooks)
+  - [useClient](#useclienttargetfnorref-options-deps)
+  - [useServer](#useserveroptions-deps)
+  - [useServerHandler](#useserverhandlerserver-path-handler-deps)
+  - [useServerHandlerMap](#useserverhandlermapserver-map-deps)
+  - [完整示例](#完整示例)
+  - [最佳实践](#最佳实践)
 - [错误处理](#错误处理)
 - [FAQ](#faq)
 - [开发](#开发)
@@ -167,7 +174,7 @@ request-iframe 采用三阶段超时策略，智能适应不同场景：
 
 ```typescript
 client.send('/api/getData', data, {
-  ackTimeout: 500,        // 阶段1：等待 ACK 的超时时间（默认 500ms）
+  ackTimeout: 1000,       // 阶段1：等待 ACK 的超时时间（默认 1000ms）
   timeout: 5000,          // 阶段2：请求超时时间（默认 5s）
   asyncTimeout: 120000    // 阶段3：异步请求超时时间（默认 120s）
 });
@@ -207,7 +214,7 @@ client.send('/api/getData', data, {
 
 | 阶段 | 超时时间 | 场景 |
 |------|----------|------|
-| ackTimeout | 较短（500ms） | 快速检测 Server 是否在线，避免长时间等待不可达的 iframe |
+| ackTimeout | 较短（1000ms） | 快速检测 Server 是否在线，避免长时间等待不可达的 iframe。从 500ms 增加到 1000ms，以适应性能较差的环境或浏览器繁忙的场景 |
 | timeout | 中等（5s） | 适用于简单的同步处理，如读取数据、参数校验等 |
 | asyncTimeout | 较长（120s） | 适用于复杂异步操作，如文件处理、批量操作、第三方 API 调用等 |
 
@@ -804,7 +811,7 @@ setMessages({
 | `target` | `HTMLIFrameElement \| Window` | 目标 iframe 元素或 window 对象 |
 | `options.secretKey` | `string` | 消息隔离标识（可选） |
 | `options.trace` | `boolean` | 是否开启追踪模式（可选） |
-| `options.ackTimeout` | `number` | 全局默认 ACK 确认超时（ms），默认 500 |
+| `options.ackTimeout` | `number` | 全局默认 ACK 确认超时（ms），默认 1000 |
 | `options.timeout` | `number` | 全局默认请求超时（ms），默认 5000 |
 | `options.asyncTimeout` | `number` | 全局默认异步超时（ms），默认 120000 |
 
@@ -837,7 +844,7 @@ await client.send('/api/longTask', {}, {
 |------|------|------|
 | `options.secretKey` | `string` | 消息隔离标识（可选） |
 | `options.trace` | `boolean` | 是否开启追踪模式（可选） |
-| `options.ackTimeout` | `number` | 等待客户端确认超时（ms），默认 5000 |
+| `options.ackTimeout` | `number` | 等待客户端确认超时（ms），默认 1000 |
 
 **返回值：** `RequestIframeServer`
 
@@ -853,7 +860,7 @@ await client.send('/api/longTask', {}, {
 |------|------|------|
 | `path` | `string` | 请求路径 |
 | `body` | `object` | 请求数据（可选） |
-| `options.ackTimeout` | `number` | ACK 确认超时（ms），默认 500 |
+| `options.ackTimeout` | `number` | ACK 确认超时（ms），默认 1000 |
 | `options.timeout` | `number` | 请求超时（ms），默认 5000 |
 | `options.asyncTimeout` | `number` | 异步超时（ms），默认 120000 |
 | `options.headers` | `object` | 请求 headers（可选） |
@@ -864,16 +871,11 @@ await client.send('/api/longTask', {}, {
 
 ```typescript
 interface Response<T = any> {
-  data: T;                    // 响应数据
+  data: T;                    // 响应数据（自动解析的文件流为 File/Blob）
   status: number;             // 状态码
   statusText: string;         // 状态文本
   requestId: string;          // 请求 ID
   headers?: Record<string, string | string[]>;  // 响应 headers（Set-Cookie 为数组）
-  fileData?: {                // 文件数据（如果有）
-    content: string;          // base64 编码内容
-    mimeType?: string;
-    fileName?: string;
-  };
   stream?: IIframeReadableStream<T>;  // 流响应（如果有）
 }
 ```
@@ -984,7 +986,262 @@ server.use(['/a', '/b'], (req, res, next) => { ... });
 
 销毁 Server 实例，移除所有监听器。
 
-### ServerRequest 对象
+---
+
+## React Hooks
+
+request-iframe 提供了 React hooks，方便在 React 应用中使用。从 `request-iframe/react` 导入 hooks：
+
+```typescript
+import { useClient, useServer, useServerHandler, useServerHandlerMap } from 'request-iframe/react';
+```
+
+### useClient(targetFnOrRef, options?, deps?)
+
+用于使用 request-iframe client 的 React hook。
+
+**参数：**
+
+| 参数 | 类型 | 说明 |
+|------|------|------|
+| `targetFnOrRef` | `(() => HTMLIFrameElement \| Window \| null) \| RefObject<HTMLIFrameElement \| Window>` | 返回 iframe 元素或 Window 对象的函数，或 React ref 对象 |
+| `options` | `RequestIframeClientOptions` | Client 选项（可选） |
+| `deps` | `readonly unknown[]` | 依赖数组（可选，当依赖变化时重新创建 client） |
+
+**返回值：** `RequestIframeClient | null`
+
+**示例：**
+
+```tsx
+import { useClient } from 'request-iframe/react';
+import { useRef } from 'react';
+
+const MyComponent = () => {
+  const iframeRef = useRef<HTMLIFrameElement>(null);
+  const client = useClient(iframeRef, { secretKey: 'my-app' });
+
+  const handleClick = async () => {
+    if (client) {
+      const response = await client.send('/api/data', { id: 1 });
+      console.log(response.data);
+    }
+  };
+
+  return (
+    <div>
+      <iframe ref={iframeRef} src="/iframe.html" />
+      <button onClick={handleClick}>发送请求</button>
+    </div>
+  );
+};
+```
+
+**使用函数而不是 ref：**
+
+```tsx
+const MyComponent = () => {
+  const iframeRef = useRef<HTMLIFrameElement>(null);
+  const client = useClient(() => iframeRef.current, { secretKey: 'my-app' });
+  // ...
+};
+```
+
+### useServer(options?, deps?)
+
+用于使用 request-iframe server 的 React hook。
+
+**参数：**
+
+| 参数 | 类型 | 说明 |
+|------|------|------|
+| `options` | `RequestIframeServerOptions` | Server 选项（可选） |
+| `deps` | `readonly unknown[]` | 依赖数组（可选，当依赖变化时重新创建 server） |
+
+**返回值：** `RequestIframeServer | null`
+
+**示例：**
+
+```tsx
+import { useServer } from 'request-iframe/react';
+
+const MyComponent = () => {
+  const server = useServer({ secretKey: 'my-app' });
+
+  useEffect(() => {
+    if (!server) return;
+
+    const off = server.on('/api/data', (req, res) => {
+      res.send({ data: 'Hello' });
+    });
+
+    return off; // 组件卸载时清理
+  }, [server]);
+
+  return <div>Server 组件</div>;
+};
+```
+
+### useServerHandler(server, path, handler, deps?)
+
+用于注册单个 server handler 的 React hook，自动处理清理和闭包问题。
+
+**参数：**
+
+| 参数 | 类型 | 说明 |
+|------|------|------|
+| `server` | `RequestIframeServer \| null` | Server 实例（来自 `useServer`） |
+| `path` | `string` | 路由路径 |
+| `handler` | `ServerHandler` | 处理函数 |
+| `deps` | `readonly unknown[]` | 依赖数组（可选，当依赖变化时重新注册） |
+
+**示例：**
+
+```tsx
+import { useServer, useServerHandler } from 'request-iframe/react';
+import { useState } from 'react';
+
+const MyComponent = () => {
+  const server = useServer();
+  const [userId, setUserId] = useState(1);
+
+  // Handler 自动使用最新的 userId 值
+  useServerHandler(server, '/api/user', (req, res) => {
+    res.send({ userId, data: 'Hello' });
+  }, [userId]); // 当 userId 变化时重新注册
+
+  return <div>Server 组件</div>;
+};
+```
+
+**关键特性：**
+- 自动处理闭包问题 - 始终使用依赖项的最新值
+- 组件卸载或依赖变化时自动取消注册 handler
+- 无需手动管理 handler 的注册/清理
+
+### useServerHandlerMap(server, map, deps?)
+
+用于批量注册多个 server handlers 的 React hook，自动处理清理。
+
+**参数：**
+
+| 参数 | 类型 | 说明 |
+|------|------|------|
+| `server` | `RequestIframeServer \| null` | Server 实例（来自 `useServer`） |
+| `map` | `Record<string, ServerHandler>` | 路由路径和处理函数的映射 |
+| `deps` | `readonly unknown[]` | 依赖数组（可选，当依赖变化时重新注册） |
+
+**示例：**
+
+```tsx
+import { useServer, useServerHandlerMap } from 'request-iframe/react';
+import { useState } from 'react';
+
+const MyComponent = () => {
+  const server = useServer();
+  const [userId, setUserId] = useState(1);
+
+  // 一次性注册多个 handlers
+  useServerHandlerMap(server, {
+    '/api/user': (req, res) => {
+      res.send({ userId, data: '用户数据' });
+    },
+    '/api/posts': (req, res) => {
+      res.send({ userId, data: '文章数据' });
+    }
+  }, [userId]); // 当 userId 变化时重新注册所有 handlers
+
+  return <div>Server 组件</div>;
+};
+```
+
+**关键特性：**
+- 批量注册多个 handlers
+- 自动处理闭包问题 - 始终使用依赖项的最新值
+- 组件卸载或依赖变化时自动取消注册所有 handlers
+- 高效 - 仅在 map 的键变化时重新注册
+
+### 完整示例
+
+以下是一个完整的示例，展示如何在真实应用中使用 React hooks：
+
+```tsx
+import { useClient, useServer, useServerHandler } from 'request-iframe/react';
+import { useRef, useState } from 'react';
+
+// 父组件（Client）
+const ParentComponent = () => {
+  const iframeRef = useRef<HTMLIFrameElement>(null);
+  const client = useClient(iframeRef, { secretKey: 'my-app' });
+  const [data, setData] = useState(null);
+
+  const fetchData = async () => {
+    if (!client) return;
+    
+    try {
+      const response = await client.send('/api/data', { id: 1 });
+      setData(response.data);
+    } catch (error) {
+      console.error('请求失败:', error);
+    }
+  };
+
+  return (
+    <div>
+      <iframe ref={iframeRef} src="/iframe.html" />
+      <button onClick={fetchData}>获取数据</button>
+      {data && <pre>{JSON.stringify(data, null, 2)}</pre>}
+    </div>
+  );
+};
+
+// Iframe 组件（Server）
+const IframeComponent = () => {
+  const server = useServer({ secretKey: 'my-app' });
+  const [userId, setUserId] = useState(1);
+
+  // 注册 handler，自动清理
+  useServerHandler(server, '/api/data', async (req, res) => {
+    // Handler 始终使用最新的 userId 值
+    const userData = await fetchUserData(userId);
+    res.send(userData);
+  }, [userId]);
+
+  return (
+    <div>
+      <p>用户 ID: {userId}</p>
+      <button onClick={() => setUserId(userId + 1)}>增加</button>
+    </div>
+  );
+};
+```
+
+### 最佳实践
+
+1. **始终检查 null**：Client 和 server hooks 在初始时或目标不可用时可能返回 `null`：
+   ```tsx
+   const client = useClient(iframeRef);
+   if (!client) return null; // 处理 null 情况
+   ```
+
+2. **使用依赖数组**：向 hooks 传递依赖项，确保 handlers 使用最新值：
+   ```tsx
+   useServerHandler(server, '/api/data', (req, res) => {
+     res.send({ userId }); // 始终使用最新的 userId
+   }, [userId]); // 当 userId 变化时重新注册
+   ```
+
+3. **自动清理**：Hooks 在组件卸载时自动清理，但你也可以手动取消注册：
+   ```tsx
+   useEffect(() => {
+     if (!server) return;
+     const off = server.on('/api/data', handler);
+     return off; // 手动清理（可选，hooks 会自动处理）
+   }, [server]);
+   ```
+
+---
+
+## 错误处理
 
 ```typescript
 interface ServerRequest {

package/README.md

@@ -34,6 +34,13 @@ Communicate with iframes like sending HTTP requests! A cross-origin iframe commu
   - [Trace Mode](#trace-mode)
   - [Internationalization](#internationalization)
 - [API Reference](#api-reference)
+- [React Hooks](#react-hooks)
+  - [useClient](#useclienttargetfnorref-options-deps)
+  - [useServer](#useserveroptions-deps)
+  - [useServerHandler](#useserverhandlerserver-path-handler-deps)
+  - [useServerHandlerMap](#useserverhandlermapserver-map-deps)
+  - [Complete Example](#complete-example)
+  - [Best Practices](#best-practices)
 - [Error Handling](#error-handling)
 - [FAQ](#faq)
 - [Development](#development)
@@ -251,7 +258,7 @@ request-iframe uses a three-stage timeout strategy to intelligently adapt to dif
 
 ```typescript
 client.send('/api/getData', data, {
-  ackTimeout: 500,        // Stage 1: ACK timeout (default 500ms)
+  ackTimeout: 1000,       // Stage 1: ACK timeout (default 1000ms)
   timeout: 5000,          // Stage 2: Request timeout (default 5s)
   asyncTimeout: 120000    // Stage 3: Async request timeout (default 120s)
 });
@@ -291,7 +298,7 @@ Send REQUEST
 
 | Stage | Timeout | Scenario |
 |-------|---------|----------|
-| ackTimeout | Short (500ms) | Quickly detect if Server is online, avoid long waits for unreachable iframes |
+| ackTimeout | Short (1000ms) | Quickly detect if Server is online, avoid long waits for unreachable iframes. Increased from 500ms to accommodate slower environments or busy browsers |
 | timeout | Medium (5s) | Suitable for simple synchronous processing, like reading data, parameter validation |
 | asyncTimeout | Long (120s) | Suitable for complex async operations, like file processing, batch operations, third-party API calls |
 
@@ -712,7 +719,7 @@ Create a Client instance.
 | `target` | `HTMLIFrameElement \| Window` | Target iframe element or window object |
 | `options.secretKey` | `string` | Message isolation identifier (optional) |
 | `options.trace` | `boolean` | Whether to enable trace mode (optional) |
-| `options.ackTimeout` | `number` | Global default ACK acknowledgment timeout (ms), default 500 |
+| `options.ackTimeout` | `number` | Global default ACK acknowledgment timeout (ms), default 1000 |
 | `options.timeout` | `number` | Global default request timeout (ms), default 5000 |
 | `options.asyncTimeout` | `number` | Global default async timeout (ms), default 120000 |
 
@@ -728,7 +735,7 @@ Create a Server instance.
 |-----------|------|-------------|
 | `options.secretKey` | `string` | Message isolation identifier (optional) |
 | `options.trace` | `boolean` | Whether to enable trace mode (optional) |
-| `options.ackTimeout` | `number` | Wait for client acknowledgment timeout (ms), default 5000 |
+| `options.ackTimeout` | `number` | Wait for client acknowledgment timeout (ms), default 1000 |
 
 **Returns:** `RequestIframeServer`
 
@@ -744,7 +751,7 @@ Send a request.
 |-----------|------|-------------|
 | `path` | `string` | Request path |
 | `body` | `object` | Request data (optional) |
-| `options.ackTimeout` | `number` | ACK acknowledgment timeout (ms), default 500 |
+| `options.ackTimeout` | `number` | ACK acknowledgment timeout (ms), default 1000 |
 | `options.timeout` | `number` | Request timeout (ms), default 5000 |
 | `options.asyncTimeout` | `number` | Async timeout (ms), default 120000 |
 | `options.headers` | `object` | Request headers (optional) |
@@ -755,16 +762,11 @@ Send a request.
 
 ```typescript
 interface Response<T = any> {
-  data: T;                    // Response data
+  data: T;                    // Response data (File/Blob for auto-resolved file streams)
   status: number;             // Status code
   statusText: string;         // Status text
   requestId: string;          // Request ID
   headers?: Record<string, string | string[]>;  // Response headers (Set-Cookie is array)
-  fileData?: {                // File data (if any)
-    content: string;          // base64-encoded content
-    mimeType?: string;
-    fileName?: string;
-  };
   stream?: IIframeReadableStream<T>;  // Stream response (if any)
 }
 ```
@@ -840,6 +842,259 @@ Destroy Server instance, remove all listeners.
 
 ---
 
+## React Hooks
+
+request-iframe provides React hooks for easy integration in React applications. Import hooks from `request-iframe/react`:
+
+```typescript
+import { useClient, useServer, useServerHandler, useServerHandlerMap } from 'request-iframe/react';
+```
+
+### useClient(targetFnOrRef, options?, deps?)
+
+React hook for using request-iframe client.
+
+**Parameters:**
+
+| Parameter | Type | Description |
+|-----------|------|-------------|
+| `targetFnOrRef` | `(() => HTMLIFrameElement \| Window \| null) \| RefObject<HTMLIFrameElement \| Window>` | Function that returns iframe element or Window object, or a React ref object |
+| `options` | `RequestIframeClientOptions` | Client options (optional) |
+| `deps` | `readonly unknown[]` | Dependency array (optional, for re-creating client when dependencies change) |
+
+**Returns:** `RequestIframeClient | null`
+
+**Example:**
+
+```tsx
+import { useClient } from 'request-iframe/react';
+import { useRef } from 'react';
+
+const MyComponent = () => {
+  const iframeRef = useRef<HTMLIFrameElement>(null);
+  const client = useClient(iframeRef, { secretKey: 'my-app' });
+
+  const handleClick = async () => {
+    if (client) {
+      const response = await client.send('/api/data', { id: 1 });
+      console.log(response.data);
+    }
+  };
+
+  return (
+    <div>
+      <iframe ref={iframeRef} src="/iframe.html" />
+      <button onClick={handleClick}>Send Request</button>
+    </div>
+  );
+};
+```
+
+**Using function instead of ref:**
+
+```tsx
+const MyComponent = () => {
+  const iframeRef = useRef<HTMLIFrameElement>(null);
+  const client = useClient(() => iframeRef.current, { secretKey: 'my-app' });
+  // ...
+};
+```
+
+### useServer(options?, deps?)
+
+React hook for using request-iframe server.
+
+**Parameters:**
+
+| Parameter | Type | Description |
+|-----------|------|-------------|
+| `options` | `RequestIframeServerOptions` | Server options (optional) |
+| `deps` | `readonly unknown[]` | Dependency array (optional, for re-creating server when dependencies change) |
+
+**Returns:** `RequestIframeServer | null`
+
+**Example:**
+
+```tsx
+import { useServer } from 'request-iframe/react';
+
+const MyComponent = () => {
+  const server = useServer({ secretKey: 'my-app' });
+
+  useEffect(() => {
+    if (!server) return;
+
+    const off = server.on('/api/data', (req, res) => {
+      res.send({ data: 'Hello' });
+    });
+
+    return off; // Cleanup on unmount
+  }, [server]);
+
+  return <div>Server Component</div>;
+};
+```
+
+### useServerHandler(server, path, handler, deps?)
+
+React hook for registering a single server handler with automatic cleanup and closure handling.
+
+**Parameters:**
+
+| Parameter | Type | Description |
+|-----------|------|-------------|
+| `server` | `RequestIframeServer \| null` | Server instance (from `useServer`) |
+| `path` | `string` | Route path |
+| `handler` | `ServerHandler` | Handler function |
+| `deps` | `readonly unknown[]` | Dependency array (optional, for re-registering when dependencies change) |
+
+**Example:**
+
+```tsx
+import { useServer, useServerHandler } from 'request-iframe/react';
+import { useState } from 'react';
+
+const MyComponent = () => {
+  const server = useServer();
+  const [userId, setUserId] = useState(1);
+
+  // Handler automatically uses latest userId value
+  useServerHandler(server, '/api/user', (req, res) => {
+    res.send({ userId, data: 'Hello' });
+  }, [userId]); // Re-register when userId changes
+
+  return <div>Server Component</div>;
+};
+```
+
+**Key Features:**
+- Automatically handles closure issues - always uses latest values from dependencies
+- Automatically unregisters handler on unmount or when dependencies change
+- No need to manually manage handler registration/cleanup
+
+### useServerHandlerMap(server, map, deps?)
+
+React hook for registering multiple server handlers at once with automatic cleanup.
+
+**Parameters:**
+
+| Parameter | Type | Description |
+|-----------|------|-------------|
+| `server` | `RequestIframeServer \| null` | Server instance (from `useServer`) |
+| `map` | `Record<string, ServerHandler>` | Map of route paths and handler functions |
+| `deps` | `readonly unknown[]` | Dependency array (optional, for re-registering when dependencies change) |
+
+**Example:**
+
+```tsx
+import { useServer, useServerHandlerMap } from 'request-iframe/react';
+import { useState } from 'react';
+
+const MyComponent = () => {
+  const server = useServer();
+  const [userId, setUserId] = useState(1);
+
+  // Register multiple handlers at once
+  useServerHandlerMap(server, {
+    '/api/user': (req, res) => {
+      res.send({ userId, data: 'User data' });
+    },
+    '/api/posts': (req, res) => {
+      res.send({ userId, data: 'Posts data' });
+    }
+  }, [userId]); // Re-register all handlers when userId changes
+
+  return <div>Server Component</div>;
+};
+```
+
+**Key Features:**
+- Batch registration of multiple handlers
+- Automatically handles closure issues - always uses latest values from dependencies
+- Automatically unregisters all handlers on unmount or when dependencies change
+- Efficient - only re-registers when map keys change
+
+### Complete Example
+
+Here's a complete example showing how to use React hooks in a real application:
+
+```tsx
+import { useClient, useServer, useServerHandler } from 'request-iframe/react';
+import { useRef, useState } from 'react';
+
+// Parent Component (Client)
+const ParentComponent = () => {
+  const iframeRef = useRef<HTMLIFrameElement>(null);
+  const client = useClient(iframeRef, { secretKey: 'my-app' });
+  const [data, setData] = useState(null);
+
+  const fetchData = async () => {
+    if (!client) return;
+    
+    try {
+      const response = await client.send('/api/data', { id: 1 });
+      setData(response.data);
+    } catch (error) {
+      console.error('Request failed:', error);
+    }
+  };
+
+  return (
+    <div>
+      <iframe ref={iframeRef} src="/iframe.html" />
+      <button onClick={fetchData}>Fetch Data</button>
+      {data && <pre>{JSON.stringify(data, null, 2)}</pre>}
+    </div>
+  );
+};
+
+// Iframe Component (Server)
+const IframeComponent = () => {
+  const server = useServer({ secretKey: 'my-app' });
+  const [userId, setUserId] = useState(1);
+
+  // Register handler with automatic cleanup
+  useServerHandler(server, '/api/data', async (req, res) => {
+    // Handler always uses latest userId value
+    const userData = await fetchUserData(userId);
+    res.send(userData);
+  }, [userId]);
+
+  return (
+    <div>
+      <p>User ID: {userId}</p>
+      <button onClick={() => setUserId(userId + 1)}>Increment</button>
+    </div>
+  );
+};
+```
+
+### Best Practices
+
+1. **Always check for null**: Client and server hooks may return `null` initially or when target is unavailable:
+   ```tsx
+   const client = useClient(iframeRef);
+   if (!client) return null; // Handle null case
+   ```
+
+2. **Use dependency arrays**: Pass dependencies to hooks to ensure handlers use latest values:
+   ```tsx
+   useServerHandler(server, '/api/data', (req, res) => {
+     res.send({ userId }); // Always uses latest userId
+   }, [userId]); // Re-register when userId changes
+   ```
+
+3. **Cleanup is automatic**: Hooks automatically clean up on unmount, but you can also manually unregister:
+   ```tsx
+   useEffect(() => {
+     if (!server) return;
+     const off = server.on('/api/data', handler);
+     return off; // Manual cleanup (optional, hooks do this automatically)
+   }, [server]);
+   ```
+
+---
+
 ## Error Handling
 
 ### Error Codes