ms-vite-plugin 1.4.49 → 1.4.51

package/docs/apilua/hotUpdate.md

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

package/docs/apilua/http.md

@@ -0,0 +1,427 @@
+# HTTP 模块 (HTTP)
+
+HTTP 模块提供了完整的网络请求功能，包括 HTTP 请求、文件下载、WebSocket 连接等。
+
+## 通用 HTTP 请求
+
+### request - 发送通用 HTTP 请求，支持所有 HTTP 方法和完整的配置选项。
+
+```lua
+---@param params table
+---@return any
+function request(params) end
+```
+
+**参数：**
+
+| 参数名              | 类型    | 是否必填 | 默认值   | 描述                        |
+| ------------------- | ------- | -------- | -------- | --------------------------- |
+| `url`               | string  | 是       | -        | 请求地址                    |
+| `timeout`           | number  | 否       | 10000    | 请求超时时间（毫秒）        |
+| `method`            | string  | 否       | GET      | 请求方法（GET、POST 等）    |
+| `proxy`             | table  | 否       | -        | 代理服务器配置              |
+| `followRedirects`   | boolean | 否       | true     | 是否跟随重定向              |
+| `requestBody`       | string \| string | 否       | -        | 请求体，JSON 对象需先 ToJsonString |
+| `userAgent`         | string  | 否       | -        | 用户代理字符串              |
+| `ignoreContentType` | boolean | 否       | false    | 是否忽略内容类型            |
+| `ignoreHttpErrors`  | boolean | 否       | false    | 是否忽略 HTTP 错误          |
+| `maxBodySize`       | number  | 否       | 10485760 | 最大响应体大小（默认 10MB） |
+| `referrer`          | string  | 否       | -        | 引用来源                    |
+| `header`            | table  | 否       | -        | 请求头                      |
+| `cookie`            | table  | 否       | -        | Cookie                      |
+| `data`              | table  | 否       | -        | 请求参数                    |
+| `file`              | table  | 否       | -        | 请求文件                    |
+| `responseCharset`   | string  | 否       | -        | 响应字符集                  |
+
+**返回值：**
+
+| 字段名          | 类型   | 描述          |
+| --------------- | ------ | ------------- |
+| `header`        | table | 响应头        |
+| `cookie`        | table | 响应 Cookie   |
+| `statusCode`    | number | HTTP 状态码   |
+| `statusMessage` | string | HTTP 状态消息 |
+| `charset`       | string | 响应字符集    |
+| `contentType`   | string | 响应内容类型  |
+| `body`          | string | 响应体内容    |
+
+**示例：**
+
+```lua
+local http = require("http")
+-- GET 请求
+local response = http.request({
+  url = "https://api.example.com/users",
+  method = "GET",
+  timeout = 5000,
+  header = {
+    Authorization = "Bearer token123",
+    Accept = "application/json",
+  },
+})
+
+print("状态码: " .. tostring(response.statusCode))
+print("响应体: " .. tostring(response.body))
+-- POST 请求发送 JSON 数据
+local postResponse = http.request({
+  url = "https://api.example.com/users",
+  method = "POST",
+  header = {
+    ["Content-Type"] = "application/json",
+    Authorization = "Bearer token123",
+  },
+  requestBody = ToJsonString({
+    name = "张三",
+    email = "zhangsan@example.com",
+  }),
+})
+-- 使用代理
+local proxyResponse = http.request({
+  url = "https://api.example.com/data",
+  method = "GET",
+  proxy = {
+    host = "proxy.example.com",
+    port = 8080,
+  },
+})
+```
+
+## 简化 HTTP 方法
+
+### httpGet - 发送 GET 请求的简化方法。
+
+```lua
+---@param url string
+---@param params table?
+---@param timeout number?
+---@param headers table?
+---@return string | nil
+function httpGet(url, params, timeout, headers) end
+```
+
+**参数：**
+
+| 参数名    | 类型                   | 是否必填 | 默认值 | 描述             |
+| --------- | ---------------------- | -------- | ------ | ---------------- |
+| `url`     | string                 | 是       | -      | 请求地址         |
+| `params`  | table | 否       | -      | URL 查询参数     |
+| `timeout` | number                 | 否       | 10000  | 超时时间（毫秒） |
+| `headers` | table | 否       | -      | 请求头           |
+
+**返回值：**
+
+| 类型     | 描述       |
+| -------- | ---------- |
+| `string` | 响应体内容 |
+
+**示例：**
+
+```lua
+local http = require("http")
+-- 简单 GET 请求
+local html = http.httpGet("https://www.example.com")
+print(html)
+-- 带参数的 GET 请求
+local result = http.httpGet(
+  "https://api.example.com/search",
+  { q = "快点JS", limit = "10" },
+  5000,
+  { ["User-Agent"] = "快点JS/1.0" },
+)
+print("搜索结果: " .. tostring(result))
+```
+
+### httpPost - 发送 POST 请求的简化方法。
+
+```lua
+---@param url string
+---@param params table?
+---@param files table?
+---@param timeout number?
+---@param headers table?
+---@return string | nil
+function httpPost(url, params, files, timeout, headers) end
+```
+
+**参数：**
+
+| 参数名    | 类型                   | 是否必填 | 默认值 | 描述             |
+| --------- | ---------------------- | -------- | ------ | ---------------- |
+| `url`     | string                 | 是       | -      | 请求地址         |
+| `params`  | table | 否       | -      | 表单参数         |
+| `files`   | table | 否       | -      | 文件参数         |
+| `timeout` | number                 | 否       | 10000  | 超时时间（毫秒） |
+| `headers` | table | 否       | -      | 请求头           |
+
+**返回值：**
+
+| 类型     | 描述       |
+| -------- | ---------- |
+| `string` | 响应体内容 |
+
+**示例：**
+
+```lua
+local http = require("http")
+-- 发送表单数据
+local response = http.httpPost("https://api.example.com/submit", {
+  username = "admin",
+  password = "123456",
+  action = "login",
+})
+-- 上传文件
+local uploadResponse = http.httpPost(
+  "https://api.example.com/upload",
+  { description = "测试文件" },
+  { file: "/path/to/file.txt" },
+  10000,
+)
+
+print("上传结果: " .. tostring(ToJsonString(uploadResponse)))
+```
+
+### postJSON - 发送 JSON 数据的 POST 请求。
+
+```lua
+---@param url string
+---@param json table?
+---@param timeout number?
+---@param headers table?
+---@return string | nil
+function postJSON(url, json, timeout, headers) end
+```
+
+**参数：**
+
+| 参数名    | 类型                   | 是否必填 | 默认值 | 描述             |
+| --------- | ---------------------- | -------- | ------ | ---------------- |
+| `url`     | string                 | 是       | -      | 请求地址         |
+| `json`    | table | 否       | -      | JSON 数据        |
+| `timeout` | number                 | 否       | 10000  | 超时时间（毫秒） |
+| `headers` | table | 否       | -      | 请求头           |
+
+**返回值：**
+
+| 类型   | 描述       |
+| ------ | ---------- |
+| string | 响应体内容 |
+
+**示例：**
+
+```lua
+local http = require("http")
+-- 发送 JSON 数据
+local response = http.postJSON(
+  "https://api.example.com/api/users",
+  {
+    name = "快点JS",
+    version = "1.0.0",
+    platform = "iOS",
+  },
+  5000,
+  { Authorization = "Bearer token123" },
+)
+print("响应: " .. tostring(response))
+```
+
+## 文件下载
+
+### downloadFile - 下载文件到本地，支持断点续传。
+
+```lua
+---@param url string
+---@param file string
+---@param timeout number?
+---@param headers table?
+---@return boolean
+function downloadFile(url, file, timeout, headers) end
+```
+
+**参数：**
+
+| 参数名    | 类型                   | 是否必填 | 默认值 | 描述                 |
+| --------- | ---------------------- | -------- | ------ | -------------------- |
+| `url`     | string                 | 是       | -      | 文件下载地址         |
+| `file`    | string                 | 是       | -      | 本地保存路径         |
+| `timeout` | number                 | 否       | 10000  | 下载超时时间（毫秒） |
+| `headers` | table | 否       | -      | 请求头               |
+
+**返回值：**
+
+| 类型      | 描述         |
+| --------- | ------------ |
+| `boolean` | 下载是否成功 |
+
+**示例：**
+
+```lua
+local http = require("http")
+local file = require("file")
+local documentsDir = file.getInternalDir("documents")
+-- 下载文件
+local success = http.downloadFile(
+  "https://example.com/files/document.pdf",
+  documentsDir .. "/document.pdf",
+  30000,
+  { ["User-Agent"] = "快点JS Downloader" }
+)
+
+if success then
+  print("文件下载成功")
+else
+  print("文件下载失败")
+end
+
+-- 下载大文件
+local function downloadLargeFile(url, filename)
+  print("开始下载: " .. tostring(filename))
+  local documentsDir = file.getInternalDir("documents")
+  local ok = http.downloadFile(url, documentsDir .. "/" .. filename, 60000)
+  if ok then
+    print("下载完成: " .. tostring(filename))
+    return true
+  end
+  print("下载失败: " .. tostring(filename))
+  return false
+end
+
+local files = {
+  { url = "https://example.com/file1.zip", name = "file1.zip" },
+  { url = "https://example.com/file2.zip", name = "file2.zip" },
+}
+for _, item in ipairs(files) do
+  downloadLargeFile(item.url, item.name)
+end
+```
+
+## WebSocket 连接
+
+### newWebsocket - 创建 WebSocket 连接。
+
+```lua
+---@param url string
+---@param header table?
+---@return WebSocket
+function newWebsocket(url, header) end
+```
+
+**参数：**
+
+| 参数名   | 类型   | 是否必填 | 默认值 | 描述                 |
+| -------- | ------ | -------- | ------ | -------------------- |
+| `url`    | string | 是       | -      | WebSocket 服务器地址 |
+| `header` | table  | 否       | -      | 连接头               |
+
+**返回值：**
+
+| 类型        | 描述               |
+| ----------- | ------------------ |
+| `WebSocket` | WebSocket 连接对象 |
+
+对象方法用冒号调用，例如 `ws:connect()`。二进制收发使用 Base64 字符串。
+
+### WebSocket 接口方法
+
+#### 连接管理
+
+```lua
+---@return nil
+function connect() end
+---@return nil
+function close() end
+---@return boolean
+function reset() end
+---@return boolean
+function isClosed() end
+---@return boolean
+function isConnected() end
+```
+
+#### 消息发送
+
+```lua
+---@param data string
+function sendText(data) end
+---@param data string
+function sendBinary(data) end
+```
+
+#### 事件回调
+
+```lua
+---@param callback function
+function onOpen(callback) end
+---@param callback function
+function onClose(callback) end
+---@param callback function
+function onText(callback) end
+---@param callback function
+function onBinary(callback) end
+---@param callback function
+function onError(callback) end
+```
+
+#### 配置选项
+
+```lua
+---@param timeout number
+function setConnectionTimeout(timeout) end
+---@param timeout number
+function setWriteTimeout(timeout) end
+---@param autoReconnect boolean
+function setAutoReconnect(autoReconnect) end
+---@param interval number
+---@param callback function?
+function startHeartbeatInterval(interval, callback) end
+function stopHeartbeatInterval() end
+```
+
+**WebSocket 完整示例：**
+
+```lua
+local http = require("http")
+
+local function createWebSocketConnection()
+  local ws = http.newWebsocket("wss://echo.websocket.org", {
+    ["User-Agent"] = "快点JS/1.0",
+  })
+
+  ws:setConnectionTimeout(10)
+  ws:setWriteTimeout(5)
+  ws:setAutoReconnect(true)
+
+  ws:onOpen(function()
+    print("WebSocket 连接已打开")
+    ws:sendText(ToJsonString({
+      type = "greeting",
+      message = "Hello from 快点JS!",
+      timestamp = Time(),
+    }))
+  end)
+
+  ws:onText(function(data)
+    print("收到文本消息: " .. tostring(data))
+  end)
+
+  ws:onBinary(function(data)
+    print("收到二进制消息: " .. tostring(data))
+  end)
+
+  ws:onClose(function()
+    print("WebSocket 连接已关闭")
+  end)
+
+  ws:onError(function(error)
+    print("WebSocket 错误: " .. tostring(error))
+  end)
+
+  ws:startHeartbeatInterval(30, function()
+    return ToJsonString({ type = "ping", timestamp = Time() })
+  end)
+
+  ws:connect()
+  return ws
+end
+
+local websocket = createWebSocketConnection()
+```