ms-vite-plugin 1.1.2 → 1.1.4

package/docs/api/hotUpdate.md

@@ -0,0 +1,166 @@
+# 热更新模块 (HotUpdate)
+
+热更新模块提供了完整的应用热更新功能，支持检查更新、下载更新包、MD5 校验、对话框展示等核心功能。
+
+## 自动检查更新
+
+以下 api 功能给脚本启动时调用，检查是否有更新，有更新则下载更新包，下载完成后重启应用。
+
+即使脚本没有调用，程序仍会在启动时自动检查更新。
+
+## 类型定义
+
+### HotUpdateResult
+
+热更新检查结果接口。
+
+```typescript
+interface HotUpdateResult {
+  needUpdate: boolean; // 是否需要更新
+  error?: string; // 错误信息（当检查失败时）
+  data?: HotUpdateResponse; // 服务器返回的更新数据（当 needUpdate 为 true 时）
+}
+```
+
+**参数说明**
+
+| 参数名       | 类型              | 是否必填 | 默认值 | 描述                                             |
+| ------------ | ----------------- | -------- | ------ | ------------------------------------------------ |
+| `needUpdate` | boolean           | 是       | -      | 是否需要更新                                     |
+| `error`      | string            | 否       | -      | 错误信息（当检查失败时）                         |
+| `data`       | HotUpdateResponse | 否       | -      | 服务器返回的更新数据（当 needUpdate 为 true 时） |
+
+### HotUpdateResponse
+
+服务器响应数据结构。
+
+```typescript
+interface HotUpdateResponse {
+  download_url: string; // 新包的下载地址
+  version: number; // 新包的版本号
+  download_timeout: number; // 下载超时时间（秒）
+  dialog: boolean; // 是否用对话框展示
+  msg: string; // 对话框消息
+  force: boolean; // 是否强制更新
+  md5?: string; // 更新包MD5值（可选）
+}
+```
+
+**参数说明**
+
+| 参数名             | 类型    | 是否必填 | 默认值 | 描述                  |
+| ------------------ | ------- | -------- | ------ | --------------------- |
+| `download_url`     | string  | 是       | -      | 新包的下载地址        |
+| `version`          | number  | 是       | -      | 新包的版本号          |
+| `download_timeout` | number  | 是       | -      | 下载超时时间（秒）    |
+| `dialog`           | boolean | 是       | -      | 是否用对话框展示      |
+| `msg`              | string  | 是       | -      | 对话框消息            |
+| `force`            | boolean | 是       | -      | 是否强制更新          |
+| `md5`              | string  | 否       | -      | 更新包 MD5 值（可选） |
+
+## API 参考
+
+- 只有你需要代码检查更新，才需要调用 `checkUpdate` 方法
+
+### 更新管理
+
+#### checkUpdate - 检查更新
+
+```typescript
+function checkUpdate(): HotUpdateResult;
+```
+
+**返回值:**
+
+| 类型            | 描述         |
+| --------------- | ------------ |
+| HotUpdateResult | 检查结果对象 |
+
+**示例:**
+
+```javascript
+// 检查更新
+const result = hotUpdate.checkUpdate();
+
+if (result.needUpdate) {
+  logi("发现新版本:", result.data.version);
+  logi("更新消息:", result.data.msg);
+  const installResult = hotUpdate.downloadAndInstall();
+  if (installResult.updated) {
+    logi("更新安装成功");
+  } else {
+    loge("更新安装失败:", installResult.error);
+  }
+} else if (result.error) {
+  loge("检查更新失败:", result.error);
+} else {
+  logi("已是最新版本");
+}
+```
+
+#### downloadAndInstall - 下载并安装更新
+
+下载并安装更新，安装完成后自动重启脚本。
+
+```typescript
+function downloadAndInstall(): {
+  updated: boolean;
+  error?: string;
+};
+```
+
+**参数:**
+
+- 无需参数，自动使用上次 `checkUpdate` 的结果
+
+**返回值:**
+
+| 参数名    | 类型    | 描述                 |
+| --------- | ------- | -------------------- |
+| `updated` | boolean | 是否安装成功         |
+| `error`   | string  | 安装失败时的错误信息 |
+
+**示例:**
+
+```javascript
+// 先检查更新，再手动下载安装
+const result = hotUpdate.checkUpdate();
+
+if (result.needUpdate) {
+  const installResult = hotUpdate.downloadAndInstall();
+  if (installResult.updated) {
+    logi("更新安装成功，自动重启应用");
+  } else {
+    loge("更新失败: " + installResult.error);
+  }
+} else {
+  logi("已是最新版本");
+}
+```
+
+### 版本信息
+
+#### getCurrentVersion - 获取当前版本号
+
+```typescript
+function getCurrentVersion(): number;
+```
+
+**返回值:**
+
+| 参数名    | 类型   | 描述                               |
+| --------- | ------ | ---------------------------------- |
+| `version` | number | 当前应用版本号（仅支持整数版本号） |
+
+**版本获取逻辑:**
+
+- 从 `package.json` 文件读取 `appVersion` 字段
+- 支持数字类型的 `appVersion`
+- 如果获取不到则返回 0
+
+**示例:**
+
+```javascript
+const version = hotUpdate.getCurrentVersion();
+logi("当前版本:", version);
+```

package/docs/api/http.md

@@ -0,0 +1,548 @@
+# HTTP 模块 (HTTP)
+
+HTTP 模块提供了完整的网络请求功能，包括 HTTP 请求、文件下载、WebSocket 连接等。
+
+## 通用 HTTP 请求
+
+### request - 发送通用 HTTP 请求，支持所有 HTTP 方法和完整的配置选项。
+
+```typescript
+function request(params: {
+  url: string;
+  timeout?: number;
+  method?: string;
+  proxy?: { host: string; port: number };
+  followRedirects?: boolean;
+  requestBody?: string;
+  userAgent?: string;
+  ignoreContentType?: boolean;
+  ignoreHttpErrors?: boolean;
+  maxBodySize?: number;
+  referrer?: string;
+  header?: Record<string, string>;
+  cookie?: Record<string, string>;
+  data?: Record<string, any>;
+  file?: Record<string, string>;
+  responseCharset?: string;
+}): {
+  header: Record<string, string>;
+  cookie: Record<string, string>;
+  statusCode: number;
+  statusMessage: string;
+  charset: string;
+  contentType: string;
+  body: string;
+};
+```
+
+**参数：**
+
+| 参数名              | 类型    | 是否必填 | 默认值   | 描述                        |
+| ------------------- | ------- | -------- | -------- | --------------------------- |
+| `url`               | string  | 是       | -        | 请求地址                    |
+| `timeout`           | number  | 否       | 10000    | 请求超时时间（毫秒）        |
+| `method`            | string  | 否       | GET      | 请求方法（GET、POST 等）    |
+| `proxy`             | object  | 否       | -        | 代理服务器配置              |
+| `followRedirects`   | boolean | 否       | true     | 是否跟随重定向              |
+| `requestBody`       | string  | 否       | -        | 请求体（POST 等方法使用）   |
+| `userAgent`         | string  | 否       | -        | 用户代理字符串              |
+| `ignoreContentType` | boolean | 否       | false    | 是否忽略内容类型            |
+| `ignoreHttpErrors`  | boolean | 否       | false    | 是否忽略 HTTP 错误          |
+| `maxBodySize`       | number  | 否       | 10485760 | 最大响应体大小（默认 10MB） |
+| `referrer`          | string  | 否       | -        | 引用来源                    |
+| `header`            | object  | 否       | -        | 请求头                      |
+| `cookie`            | object  | 否       | -        | Cookie                      |
+| `data`              | object  | 否       | -        | 请求参数                    |
+| `file`              | object  | 否       | -        | 请求文件                    |
+| `responseCharset`   | string  | 否       | -        | 响应字符集                  |
+
+**返回值：**
+
+| 字段名          | 类型   | 描述          |
+| --------------- | ------ | ------------- |
+| `header`        | object | 响应头        |
+| `cookie`        | object | 响应 Cookie   |
+| `statusCode`    | number | HTTP 状态码   |
+| `statusMessage` | string | HTTP 状态消息 |
+| `charset`       | string | 响应字符集    |
+| `contentType`   | string | 响应内容类型  |
+| `body`          | string | 响应体内容    |
+
+**示例：**
+
+```typescript
+// GET 请求
+const response = http.request({
+  url: "https://api.example.com/users",
+  method: "GET",
+  timeout: 5000,
+  header: {
+    Authorization: "Bearer token123",
+    Accept: "application/json",
+  },
+});
+
+logi(`状态码: ${response.statusCode}`);
+logi(`响应体: ${response.body}`);
+
+// POST 请求发送 JSON 数据
+const postResponse = http.request({
+  url: "https://api.example.com/users",
+  method: "POST",
+  header: {
+    "Content-Type": "application/json",
+    Authorization: "Bearer token123",
+  },
+  requestBody: JSON.stringify({
+    name: "张三",
+    email: "zhangsan@example.com",
+  }),
+});
+
+// 使用代理
+const proxyResponse = http.request({
+  url: "https://api.example.com/data",
+  method: "GET",
+  proxy: {
+    host: "proxy.example.com",
+    port: 8080,
+  },
+});
+```
+
+## 简化 HTTP 方法
+
+### httpGet - 发送 GET 请求的简化方法。
+
+```typescript
+function httpGet(
+  url: string,
+  params?: Record<string, string>,
+  timeout?: number,
+  headers?: Record<string, string>,
+): string | null;
+```
+
+**参数：**
+
+| 参数名    | 类型                   | 是否必填 | 默认值 | 描述             |
+| --------- | ---------------------- | -------- | ------ | ---------------- |
+| `url`     | string                 | 是       | -      | 请求地址         |
+| `params`  | Record<string, string> | 否       | -      | URL 查询参数     |
+| `timeout` | number                 | 否       | 10000  | 超时时间（毫秒） |
+| `headers` | Record<string, string> | 否       | -      | 请求头           |
+
+**返回值：**
+
+| 类型     | 描述       |
+| -------- | ---------- |
+| `string` | 响应体内容 |
+
+**示例：**
+
+```typescript
+// 简单 GET 请求
+const html = http.httpGet("https://www.example.com");
+logi(html);
+
+// 带参数的 GET 请求
+const result = http.httpGet(
+  "https://api.example.com/search",
+  { q: "快点JS", limit: "10" },
+  5000,
+  { "User-Agent": "快点JS/1.0" },
+);
+
+// 解析 JSON 响应
+try {
+  const data = JSON.parse(result);
+  logi(`搜索结果: ${JSON.stringify(data)}`);
+} catch (error) {
+  loge(`JSON 解析失败: ${error}`);
+}
+```
+
+### httpPost - 发送 POST 请求的简化方法。
+
+```typescript
+function httpPost(
+  url: string,
+  params?: Record<string, string>,
+  files?: Record<string, string>,
+  timeout?: number,
+  headers?: Record<string, string>,
+): string | null;
+```
+
+**参数：**
+
+| 参数名    | 类型                   | 是否必填 | 默认值 | 描述             |
+| --------- | ---------------------- | -------- | ------ | ---------------- |
+| `url`     | string                 | 是       | -      | 请求地址         |
+| `params`  | Record<string, string> | 否       | -      | 表单参数         |
+| `files`   | Record<string, string> | 否       | -      | 文件参数         |
+| `timeout` | number                 | 否       | 10000  | 超时时间（毫秒） |
+| `headers` | Record<string, string> | 否       | -      | 请求头           |
+
+**返回值：**
+
+| 类型     | 描述       |
+| -------- | ---------- |
+| `string` | 响应体内容 |
+
+**示例：**
+
+```typescript
+// 发送表单数据
+const response = http.httpPost("https://api.example.com/submit", {
+  username: "admin",
+  password: "123456",
+  action: "login",
+});
+
+// 上传文件
+const uploadResponse = http.httpPost(
+  "https://api.example.com/upload",
+  { description: "测试文件" },
+  { file: "/path/to/file.txt" },
+  10000,
+);
+
+logi(`上传结果: ${JSON.stringify(uploadResponse)}`);
+```
+
+### postJSON - 发送 JSON 数据的 POST 请求。
+
+```typescript
+function postJSON(
+  url: string,
+  json?: Record<string, any>,
+  timeout?: number,
+  headers?: Record<string, string>,
+): string | null;
+```
+
+**参数：**
+
+| 参数名    | 类型                   | 是否必填 | 默认值 | 描述             |
+| --------- | ---------------------- | -------- | ------ | ---------------- |
+| `url`     | string                 | 是       | -      | 请求地址         |
+| `json`    | Record<string, string> | 否       | -      | JSON 数据        |
+| `timeout` | number                 | 否       | 10000  | 超时时间（毫秒） |
+| `headers` | Record<string, string> | 否       | -      | 请求头           |
+
+**返回值：**
+
+| 类型   | 描述       |
+| ------ | ---------- |
+| string | 响应体内容 |
+
+**示例：**
+
+```typescript
+// 发送 JSON 数据
+const response = http.postJSON(
+  "https://api.example.com/api/users",
+  {
+    name: "快点JS",
+    version: "1.0.0",
+    platform: "iOS",
+  },
+  5000,
+  { Authorization: "Bearer token123" },
+);
+
+// 解析响应
+try {
+  const result = JSON.parse(response);
+  if (result.success) {
+    logi(`创建成功: ${JSON.stringify(result.data)}`);
+  } else {
+    loge(`创建失败: ${result.message}`);
+  }
+} catch (error) {
+  loge(`响应解析失败: ${error}`);
+}
+```
+
+## 文件下载
+
+### downloadFile - 下载文件到本地，支持断点续传。
+
+```typescript
+function downloadFile(
+  url: string,
+  file: string,
+  timeout?: number,
+  headers?: Record<string, string>,
+): boolean;
+```
+
+**参数：**
+
+| 参数名    | 类型                   | 是否必填 | 默认值 | 描述                 |
+| --------- | ---------------------- | -------- | ------ | -------------------- |
+| `url`     | string                 | 是       | -      | 文件下载地址         |
+| `file`    | string                 | 是       | -      | 本地保存路径         |
+| `timeout` | number                 | 否       | 10000  | 下载超时时间（毫秒） |
+| `headers` | Record<string, string> | 否       | -      | 请求头               |
+
+**返回值：**
+
+| 类型      | 描述         |
+| --------- | ------------ |
+| `boolean` | 下载是否成功 |
+
+**示例：**
+
+```typescript
+const documentsDir = file.getInternalDir("documents");
+// 下载文件
+const success = http.downloadFile(
+  "https://example.com/files/document.pdf",
+  `${documentsDir}/document.pdf`,
+  30000, // 30秒超时
+  { "User-Agent": "快点JS Downloader" },
+);
+
+if (success) {
+  logi("文件下载成功");
+} else {
+  logi("文件下载失败");
+}
+
+// 下载大文件
+function downloadLargeFile(url, filename) {
+  logi(`开始下载: ${filename}`);
+
+  const documentsDir = file.getInternalDir("documents");
+
+  const success = http.downloadFile(
+    url,
+    `${documentsDir}/${filename}`,
+    60000, // 1分钟超时
+  );
+
+  if (success) {
+    logi(`下载完成: ${filename}`);
+    return true;
+  } else {
+    loge(`下载失败: ${filename}`);
+    return false;
+  }
+}
+
+// 批量下载
+const files = [
+  { url: "https://example.com/file1.zip", name: "file1.zip" },
+  { url: "https://example.com/file2.zip", name: "file2.zip" },
+];
+
+files.forEach((file) => {
+  downloadLargeFile(file.url, file.name);
+});
+```
+
+## WebSocket 连接
+
+### newWebsocket - 创建 WebSocket 连接。
+
+```typescript
+function newWebsocket(url: string, header?: Record<string, string>): WebSocket;
+```
+
+**参数：**
+
+| 参数名   | 类型                   | 是否必填 | 默认值 | 描述                 |
+| -------- | ---------------------- | -------- | ------ | -------------------- |
+| `url`    | string                 | 是       | -      | WebSocket 服务器地址 |
+| `header` | Record<string, string> | 否       | -      | 连接头               |
+
+**返回值：**
+
+| 类型        | 描述               |
+| ----------- | ------------------ |
+| `WebSocket` | WebSocket 连接对象 |
+
+### WebSocket 接口方法
+
+#### 连接管理
+
+```typescript
+// 连接到服务器
+connect(): void
+
+// 关闭连接
+close(): void
+
+// 重置连接
+reset(): boolean
+
+// 检查连接状态
+isClosed(): boolean
+isConnected(): boolean
+```
+
+#### 消息发送
+
+```typescript
+// 发送文本消息
+sendText(data: string): void
+
+// 发送二进制消息
+sendBinary(data: ArrayBuffer): void
+```
+
+#### 事件回调
+
+```typescript
+// 设置连接打开回调
+onOpen(callback: () => void): void
+
+// 设置连接关闭回调
+onClose(callback: () => void): void
+
+// 设置文本消息回调
+onText(callback: (data: string) => void): void
+
+// 设置二进制消息回调
+onBinary(callback: (data: ArrayBuffer) => void): void
+
+// 设置错误回调
+onError(callback: (error: string) => void): void
+```
+
+#### 配置选项
+
+```typescript
+// 设置连接超时
+setConnectionTimeout(timeout: number): void
+
+// 设置写入超时
+setWriteTimeout(timeout: number): void
+
+// 设置自动重连
+setAutoReconnect(autoReconnect: boolean): void
+
+// 心跳管理
+startHeartbeatInterval(interval: number, callback: () => string): void
+stopHeartbeatInterval(): void
+```
+
+**WebSocket 完整示例：**
+
+```typescript
+/**
+ * 创建 WebSocket 连接示例
+ */
+function createWebSocketConnection() {
+  const ws = http.newWebsocket("wss://echo.websocket.org", {
+    "User-Agent": "快点JS/1.0",
+  });
+
+  // 设置连接超时
+  ws.setConnectionTimeout(10); // 10秒
+  ws.setWriteTimeout(5); // 5秒
+  ws.setAutoReconnect(true); // 自动重连
+
+  // 设置事件回调
+  ws.onOpen(() => {
+    logi("WebSocket 连接已打开");
+
+    // 连接成功后发送消息
+    ws.sendText(
+      JSON.stringify({
+        type: "greeting",
+        message: "Hello from 快点JS!",
+        timestamp: Date.now(),
+      }),
+    );
+  });
+
+  ws.onText((data) => {
+    logi(`收到文本消息: ${data}`);
+
+    try {
+      const message = JSON.parse(data);
+      handleMessage(message);
+    } catch (error) {
+      loge(`消息解析失败: ${error}`);
+    }
+  });
+
+  ws.onBinary((data) => {
+    logi(`收到二进制消息，大小: ${data.byteLength}`);
+    // 处理二进制数据
+  });
+
+  ws.onClose(() => {
+    logi("WebSocket 连接已关闭");
+  });
+
+  ws.onError((error) => {
+    loge(`WebSocket 错误: ${error}`);
+  });
+
+  // 设置心跳
+  ws.startHeartbeatInterval(30, () => {
+    return JSON.stringify({ type: "ping", timestamp: Date.now() });
+  });
+
+  // 连接到服务器
+  ws.connect();
+
+  return ws;
+}
+
+/**
+ * 处理接收到的消息
+ */
+function handleMessage(message: any) {
+  switch (message.type) {
+    case "pong":
+      logi("收到心跳响应");
+      break;
+
+    case "notification":
+      logi(`收到通知: ${message.content}`);
+      break;
+
+    case "command":
+      logi(`收到命令: ${message.command}`);
+      executeCommand(message.command, message.params);
+      break;
+
+    default:
+      logi(`未知消息类型: ${message.type}`);
+  }
+}
+
+/**
+ * 使用 WebSocket
+ */
+const websocket = createWebSocketConnection();
+
+// 发送状态消息
+function sendStatusMessage() {
+  if (websocket.isConnected()) {
+    websocket.sendText(
+      JSON.stringify({
+        type: "status",
+        battery: device.getBatteryInfo(),
+        timestamp: Date.now(),
+      }),
+    );
+  }
+}
+
+// 调用发送状态消息
+sendStatusMessage();
+
+// 程序结束时关闭连接
+function cleanup() {
+  if (websocket && websocket.isConnected()) {
+    websocket.stopHeartbeatInterval();
+    websocket.close();
+  }
+}
+```