ms-vite-plugin 1.1.2 → 1.1.3

package/docs/apicn/http.md

@@ -0,0 +1,672 @@
+# HTTP 模块 ($HTTP)
+
+HTTP 模块提供了完整的网络请求功能，包括 HTTP 请求、文件下载、WebSocket 连接等。
+
+## 通用 HTTP 请求
+
+### 发送请求 - 发送通用 HTTP 请求，支持所有 HTTP 方法和完整的配置选项。
+
+```typescript
+function 发送请求(params: {
+  /**
+   * 请求地址
+   */
+  url: 字符串;
+  /**
+   * 请求超时时间
+   */
+  timeout?: 数字;
+  /**
+   * 请求方法 GET POST PUT DELETE PATCH HEAD OPTIONS
+   */
+  method?: 字符串;
+  /**
+   * 代理服务器
+   */
+  proxy?: {
+    /**
+     * 代理服务器地址
+     */
+    host: 字符串;
+    /**
+     * 代理服务器端口
+     */
+    port: 数字;
+  };
+  /**
+   * 是否跟随重定向
+   */
+  followRedirects?: 布尔值;
+  /**
+   * 请求体 仅在POST方法下有效 json 需要进行JSON.stringify
+   */
+  requestBody?: 字符串;
+  /**
+   * 请求头
+   */
+  userAgent?: 字符串;
+  /**
+   * 是否忽略内容类型
+   */
+  ignoreContentType?: 布尔值;
+  /**
+   * 是否忽略HTTP错误
+   */
+  ignoreHttpErrors?: 布尔值;
+  /**
+   * 最大响应体大小 默认 10MB
+   */
+  maxBodySize?: 数字;
+  /**
+   * 引用来源
+   */
+  referrer?: 字符串;
+  /**
+   * 请求头
+   */
+  header?: 字典<字符串>;
+  /**
+   * Cookie
+   */
+  cookie?: 字典<字符串>;
+  /**
+   * 请求参数
+   */
+  data?: 字典<任意类型>;
+  /**
+   * 请求文件
+   */
+  file?: 字典<字符串>;
+  /**
+   * 响应字符集
+   */
+  responseCharset?: 字符串;
+}): {
+  /**
+   * 响应头
+   */
+  header: 字典<字符串>;
+  /**
+   * 响应Cookie
+   */
+  cookie: 字典<字符串>;
+  /**
+   * 响应状态码
+   */
+  statusCode: 数字;
+  /**
+   * 响应状态消息
+   */
+  statusMessage: 字符串;
+  /**
+   * 响应字符集
+   */
+  charset: 字符串;
+  /**
+   * 响应内容类型
+   */
+  contentType: 字符串;
+  /**
+   * 响应体
+   */
+  body: 字符串;
+};
+```
+
+**参数：**
+
+| 参数名              | 类型           | 是否必填 | 默认值   | 描述                        |
+| ------------------- | -------------- | -------- | -------- | --------------------------- |
+| `url`               | 字符串         | 是       | -        | 请求地址                    |
+| `timeout`           | 数字           | 否       | 10000    | 请求超时时间（毫秒）        |
+| `method`            | 字符串         | 否       | GET      | 请求方法（GET、POST 等）    |
+| `proxy`             | 对象           | 否       | -        | 代理服务器配置              |
+| `followRedirects`   | 布尔值         | 否       | true     | 是否跟随重定向              |
+| `requestBody`       | 字符串         | 否       | -        | 请求体（POST 等方法使用）   |
+| `userAgent`         | 字符串         | 否       | -        | 用户代理字符串              |
+| `ignoreContentType` | 布尔值         | 否       | false    | 是否忽略内容类型            |
+| `ignoreHttpErrors`  | 布尔值         | 否       | false    | 是否忽略 HTTP 错误          |
+| `maxBodySize`       | 数字           | 否       | 10485760 | 最大响应体大小（默认 10MB） |
+| `referrer`          | 字符串         | 否       | -        | 引用来源                    |
+| `header`            | 字典<字符串>   | 否       | -        | 请求头                      |
+| `cookie`            | 字典<字符串>   | 否       | -        | Cookie                      |
+| `data`              | 字典<任意类型> | 否       | -        | 请求参数                    |
+| `file`              | 字典<字符串>   | 否       | -        | 请求文件                    |
+| `responseCharset`   | 字符串         | 否       | -        | 响应字符集                  |
+
+**返回值：**
+
+| 字段名          | 类型         | 描述          |
+| --------------- | ------------ | ------------- |
+| `header`        | 字典<字符串> | 响应头        |
+| `cookie`        | 字典<字符串> | 响应 Cookie   |
+| `statusCode`    | 数字         | HTTP 状态码   |
+| `statusMessage` | 字符串       | HTTP 状态消息 |
+| `charset`       | 字符串       | 响应字符集    |
+| `contentType`   | 字符串       | 响应内容类型  |
+| `body`          | 字符串       | 响应体内容    |
+
+**示例：**
+
+```typescript
+// GET 请求
+const 数据响应 = $HTTP.发送请求({
+  url: "https://api.example.com/users",
+  method: "GET",
+  timeout: 5000,
+  header: {
+    Authorization: "Bearer token123",
+    Accept: "application/json",
+  },
+});
+
+$打印信息日志(`状态码: ${数据响应.statusCode}`);
+$打印信息日志(`响应体: ${数据响应.body}`);
+
+// POST 请求发送 JSON 数据
+const 提交数据响应 = $HTTP.发送请求({
+  url: "https://api.example.com/users",
+  method: "POST",
+  header: {
+    "Content-Type": "application/json",
+    Authorization: "Bearer token123",
+  },
+  requestBody: JSON.stringify({
+    name: "张三",
+    email: "zhangsan@example.com",
+  }),
+});
+
+$打印信息日志(`状态码: ${提交数据响应.statusCode}`);
+$打印信息日志(`响应体: ${提交数据响应.body}`);
+
+// 使用代理
+const 代理数据响应 = $HTTP.发送请求({
+  url: "https://api.example.com/data",
+  method: "GET",
+  proxy: {
+    host: "proxy.example.com",
+    port: 8080,
+  },
+});
+
+$打印信息日志(`状态码: ${代理数据响应.statusCode}`);
+$打印信息日志(`响应体: ${代理数据响应.body}`);
+```
+
+## 简化 HTTP 方法
+
+### 发送 GET 请求 - 发送 GET 请求的简化方法。
+
+```typescript
+function 发送GET请求(
+  请求地址: 字符串,
+  请求参数?: 字典<字符串>,
+  超时时间?: 数字,
+  请求头?: 字典<字符串>,
+): 字符串 | null;
+```
+
+**参数：**
+
+| 参数名     | 类型         | 是否必填 | 默认值 | 描述             |
+| ---------- | ------------ | -------- | ------ | ---------------- |
+| `请求地址` | 字符串       | 是       | -      | 请求地址         |
+| `请求参数` | 字典<字符串> | 否       | -      | URL 查询参数     |
+| `超时时间` | 数字         | 否       | 10000  | 超时时间（毫秒） |
+| `请求头`   | 字典<字符串> | 否       | -      | 请求头           |
+
+**返回值：**
+
+| 类型     | 描述       |
+| -------- | ---------- |
+| `字符串` | 响应体内容 |
+
+**示例：**
+
+```typescript
+// 简单 GET 请求
+const html = $HTTP.发送GET请求("https://www.example.com");
+$打印信息日志(html);
+
+// 带参数的 GET 请求
+const 搜索响应 = $HTTP.发送GET请求(
+  "https://api.example.com/search",
+  { q: "快点JS", limit: "10" },
+  5000,
+  { "User-Agent": "快点JS/1.0" },
+);
+
+// 解析 JSON 响应
+try {
+  const data = JSON.parse(搜索响应);
+  $打印信息日志(`搜索结果: ${JSON.stringify(data)}`);
+} catch (error) {
+  $打印错误日志(`JSON 解析失败: ${error}`);
+}
+```
+
+### 发送 POST 请求 - 发送 POST 请求的简化方法。
+
+```typescript
+function 发送POST请求(
+  请求地址: 字符串,
+  请求参数?: 字典<字符串>,
+  请求文件?: 字典<字符串>,
+  超时时间?: 数字,
+  请求头?: 字典<字符串>,
+): 字符串 | null;
+```
+
+**参数：**
+
+| 参数名     | 类型         | 是否必填 | 默认值 | 描述             |
+| ---------- | ------------ | -------- | ------ | ---------------- |
+| `请求地址` | 字符串       | 是       | -      | 请求地址         |
+| `请求参数` | 字典<字符串> | 否       | -      | 表单参数         |
+| `请求文件` | 字典<字符串> | 否       | -      | 文件参数         |
+| `超时时间` | 数字         | 否       | 10000  | 超时时间（毫秒） |
+| `请求头`   | 字典<字符串> | 否       | -      | 请求头           |
+
+**返回值：**
+
+| 类型     | 描述       |
+| -------- | ---------- |
+| `字符串` | 响应体内容 |
+
+**示例：**
+
+```typescript
+// 发送表单数据
+const 提交响应 = $HTTP.发送POST请求("https://api.example.com/submit", {
+  username: "admin",
+  password: "123456",
+  action: "login",
+});
+
+// 上传文件
+const 上传响应 = $HTTP.发送POST请求(
+  "https://api.example.com/upload",
+  { description: "测试文件" },
+  { file: "/path/to/file.txt" },
+  10000,
+);
+
+$打印信息日志(`上传结果: ${JSON.stringify(上传响应)}`);
+```
+
+### 发送 JSON 请求 - 发送 JSON 数据的 POST 请求。
+
+```typescript
+function 发送JSON请求(
+  请求地址: 字符串,
+  请求JSON数据?: 字典<任意类型>,
+  超时时间?: 数字,
+  请求头?: 字典<字符串>,
+): 字符串 | null;
+```
+
+**参数：**
+
+| 参数名         | 类型           | 是否必填 | 默认值 | 描述             |
+| -------------- | -------------- | -------- | ------ | ---------------- |
+| `请求地址`     | 字符串         | 是       | -      | 请求地址         |
+| `请求JSON数据` | 字典<任意类型> | 否       | -      | JSON 数据        |
+| `超时时间`     | 数字           | 否       | 10000  | 超时时间（毫秒） |
+| `请求头`       | 字典<字符串>   | 否       | -      | 请求头           |
+
+**返回值：**
+
+| 类型     | 描述       |
+| -------- | ---------- |
+| `字符串` | 响应体内容 |
+
+**示例：**
+
+```typescript
+// 发送 JSON 数据
+const 数据响应 = $HTTP.发送JSON请求(
+  "https://api.example.com/api/users",
+  {
+    name: "快点JS",
+    version: "1.0.0",
+    platform: "iOS",
+  },
+  5000,
+  { Authorization: "Bearer token123" },
+);
+
+// 解析响应
+try {
+  const result = JSON.parse(数据响应);
+  if (result.success) {
+    $打印信息日志(`数据创建成功: ${JSON.stringify(result.data)}`);
+  } else {
+    $打印错误日志(`数据创建失败: ${result.message}`);
+  }
+} catch (error) {
+  $打印错误日志(`数据响应解析失败: ${error}`);
+}
+```
+
+## 文件下载
+
+### 下载文件 - 下载文件到本地，支持断点续传。
+
+```typescript
+function 下载文件(
+  请求地址: 字符串,
+  保存的文件路径: 字符串,
+  超时时间?: 数字,
+  请求头?: 字典<字符串>,
+): 布尔值;
+```
+
+**参数：**
+
+| 参数名           | 类型         | 是否必填 | 默认值 | 描述                 |
+| ---------------- | ------------ | -------- | ------ | -------------------- |
+| `请求地址`       | 字符串       | 是       | -      | 文件下载地址         |
+| `保存的文件路径` | 字符串       | 是       | -      | 本地保存路径         |
+| `超时时间`       | 数字         | 否       | 10000  | 下载超时时间（毫秒） |
+| `请求头`         | 字典<字符串> | 否       | -      | 请求头               |
+
+**返回值：**
+
+| 类型     | 描述         |
+| -------- | ------------ |
+| `布尔值` | 下载是否成功 |
+
+**示例：**
+
+```typescript
+const 文档目录 = $文件.获取内部目录("documents");
+
+// 下载文件
+const 下载成功 = $HTTP.下载文件(
+  "https://example.com/files/document.pdf",
+  `${文档目录}/document.pdf`,
+  30000, // 30秒超时
+  { "User-Agent": "快点JS Downloader" },
+);
+
+if (下载成功) {
+  $打印信息日志("文件下载成功");
+} else {
+  $打印错误日志("文件下载失败");
+}
+
+// 下载大文件
+function 下载大文件(请求地址, 保存的文件名称) {
+  $打印信息日志(`开始下载: ${保存的文件名称}`);
+  const 文档目录 = $文件.获取内部目录("documents");
+  const 下载成功 = $HTTP.下载文件(
+    请求地址,
+    `${文档目录}/${保存的文件名称}`,
+    60000, // 1分钟超时
+  );
+
+  if (下载成功) {
+    $打印信息日志(`下载完成: ${保存的文件名称}`);
+    return true;
+  } else {
+    $打印错误日志(`下载失败: ${保存的文件名称}`);
+    return false;
+  }
+}
+
+// 批量下载
+const 下载列表 = [
+  { url: "https://example.com/file1.zip", name: "file1.zip" },
+  { url: "https://example.com/file2.zip", name: "file2.zip" },
+];
+
+下载列表.forEach((file) => {
+  下载大文件(file.url, file.name);
+});
+```
+
+## WebSocket 连接
+
+### 创建 WebSocket 连接 - 创建 WebSocket 连接。
+
+```typescript
+function 创建WebSocket连接(
+  连接地址: 字符串,
+  连接头?: 字典<字符串>,
+): WebSocket连接;
+```
+
+**参数：**
+
+| 参数名     | 类型         | 是否必填 | 默认值 | 描述                 |
+| ---------- | ------------ | -------- | ------ | -------------------- |
+| `连接地址` | 字符串       | 是       | -      | WebSocket 服务器地址 |
+| `连接头`   | 字典<字符串> | 否       | -      | 连接头               |
+
+**返回值：**
+
+| 类型            | 描述               |
+| --------------- | ------------------ |
+| `WebSocket连接` | WebSocket 连接对象 |
+
+### WebSocket 接口方法
+
+#### 连接管理
+
+```typescript
+/**
+  * 连接WebSocket服务器
+   */
+连接(): 无返回值;
+/**
+  * 关闭WebSocket连接
+  */
+关闭(): 无返回值;
+/**
+  * 重置WebSocket连接
+  * @returns 重置是否成功
+  */
+重置(): 布尔值;
+/**
+  * 获取WebSocket是否已关闭
+  * @returns 是否已关闭
+  */
+已关闭(): 布尔值;
+/**
+  * 获取WebSocket是否已连接
+  * @returns 是否已连接
+  */
+已连接(): 布尔值;
+```
+
+#### 消息发送
+
+```typescript
+/**
+  * 发送文本消息
+  * @param 数据 文本消息内容
+  */
+发送文本(数据: 字符串): 无返回值;
+/**
+  * 发送二进制消息
+  * @param 数据 二进制消息内容
+  */
+发送二进制(数据: ArrayBuffer): 无返回值;
+```
+
+#### 事件回调
+
+```typescript
+// 设置连接打开回调
+监听打开回调(回调: () => 无返回值): 无返回值;
+/**
+  * 监听连接关闭回调
+  * @param 回调 连接关闭时调用的回调函数
+  */
+监听关闭回调(回调: () => 无返回值): 无返回值;
+/**
+  * 监听文本消息回调
+  * @param 回调 收到文本消息时调用的回调函数
+  */
+监听文本消息回调(回调: (数据: 字符串) => 无返回值): 无返回值;
+/**
+  * 监听二进制消息回调
+  * @param 回调 收到二进制消息时调用的回调函数
+  */
+监听二进制消息回调(回调: (数据: ArrayBuffer) => 无返回值): 无返回值;
+/**
+  * 监听错误回调
+  * @param 回调 发生错误时调用的回调函数
+  */
+监听异常回调(回调: (错误: 字符串) => 无返回值): 无返回值;
+```
+
+#### 配置选项
+
+```typescript
+/**
+  * 设置连接超时时间
+  * @param 超时时间 连接超时时间（毫秒）
+  */
+设置连接超时时间(超时时间: 数字): 无返回值;
+
+/**
+  * 设置写入超时时间
+  * @param 超时时间 写入超时时间（毫秒）
+  */
+设置写入超时时间(超时时间: 数字): 无返回值;
+/**
+  * 设置自动重连
+  * @param 自动重连 是否自动重连
+  */
+设置自动重连(自动重连: 布尔值): 无返回值;
+/**
+  * 启动心跳间隔
+  * @param 间隔 心跳间隔时间（毫秒）
+  * @param 回调 发送心跳消息的回调函数
+  */
+启动心跳间隔(间隔: 数字, 回调: () => 字符串): 无返回值;
+/**
+  * 停止心跳间隔
+  */
+停止心跳间隔(): 无返回值;
+```
+
+**WebSocket 完整示例：**
+
+```typescript
+/**
+ * 创建 WebSocket 连接示例
+ */
+function 创建WebSocket连接示例() {
+  const ws = $HTTP.创建WebSocket连接("wss://echo.websocket.org", {
+    "User-Agent": "快点JS/1.0",
+  });
+
+  // 设置连接超时
+  ws.设置连接超时时间(10); // 10秒
+  ws.设置写入超时时间(5); // 5秒
+  ws.设置自动重连(true); // 自动重连
+
+  // 设置事件回调
+  ws.监听打开回调(() => {
+    logi("WebSocket 连接已打开");
+
+    // 连接成功后发送消息
+    ws.发送文本(
+      JSON.stringify({
+        type: "greeting",
+        message: "Hello from 快点JS!",
+        timestamp: Date.now(),
+      }),
+    );
+  });
+
+  ws.监听文本消息回调((data) => {
+    $打印信息日志(`收到文本消息: ${data}`);
+
+    try {
+      const message = JSON.parse(data);
+      handleMessage(message);
+    } catch (error) {
+      $打印错误日志(`消息解析失败: ${error}`);
+    }
+  });
+
+  ws.监听二进制消息回调((data) => {
+    $打印信息日志(`收到二进制消息，大小: ${data.byteLength}`);
+    // 处理二进制数据
+  });
+
+  ws.监听关闭回调(() => {
+    $打印信息日志("WebSocket 连接已关闭");
+  });
+
+  ws.监听异常回调((error) => {
+    $打印错误日志(`WebSocket 错误: ${error}`);
+  });
+
+  // 设置心跳
+  ws.启动心跳间隔(30, () => {
+    return JSON.stringify({ type: "ping", timestamp: Date.now() });
+  });
+
+  // 连接到服务器
+  ws.连接();
+
+  return ws;
+}
+
+/**
+ * 处理接收到的消息
+ */
+function handleMessage(message: any) {
+  switch (message.type) {
+    case "pong":
+      $打印信息日志("收到心跳响应");
+      break;
+
+    case "notification":
+      $打印信息日志(`收到通知: ${message.content}`);
+      break;
+
+    case "command":
+      $打印信息日志(`收到命令: ${message.command}`);
+      executeCommand(message.command, message.params);
+      break;
+
+    default:
+      $打印信息日志(`未知消息类型: ${message.type}`);
+  }
+}
+
+/**
+ * 使用 WebSocket
+ */
+const websocket = 创建WebSocket连接示例();
+
+// 发送状态消息
+function sendStatusMessage() {
+  if (websocket.已连接()) {
+    websocket.发送文本(
+      JSON.stringify({
+        type: "status",
+        battery: $设备.获取电池状态(),
+        timestamp: Date.now(),
+      }),
+    );
+  }
+}
+
+// 调用发送状态消息
+sendStatusMessage();
+
+// 程序结束时关闭连接
+function cleanup() {
+  if (websocket && websocket.已连接()) {
+    websocket.停止心跳间隔();
+    websocket.关闭();
+  }
+}
+```