ms-vite-plugin 1.1.2 → 1.1.3

package/docs/apicn/hotUpdate.md

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