ms-vite-plugin 1.4.49 → 1.4.51

package/docs/apilua/media.md

@@ -0,0 +1,283 @@
+# 媒体模块 (Media)
+
+媒体模块提供了丰富的媒体操作功能，包括图片和视频的相册管理，以及音频播放控制等功能。
+
+## 功能概览
+
+- **相册管理**: 保存图片和视频到相册，清理相册内容
+- **音频播放**: MP3 音频的播放、停止和循环控制
+- **同步/异步**: 支持异步播放和同步等待播放结束
+
+## API 参考
+
+### 相册操作
+
+#### saveImageToAlbum - 保存图像到系统相册。
+
+```lua
+---@param imageId string
+---@return boolean
+function saveImageToAlbum(imageId) end
+```
+
+**参数:**
+
+| 参数名    | 类型   | 是否必填 | 默认值 | 描述                           |
+| --------- | ------ | -------- | ------ | ------------------------------ |
+| `imageId` | string | 是       |        | 图像 ID（通过 image 模块获取） |
+
+**返回值:**
+
+| 类型      | 描述         |
+| --------- | ------------ |
+| `boolean` | 是否保存成功 |
+
+**示例:**
+
+```lua
+local media = require("media")
+-- 保存截图到相册
+media.saveImageToAlbum("screen")
+
+local documentsDir = file.getInternalDir("documents")
+-- 读取图像并保存到相册
+local imageId = image.readImage(tostring(documentsDir) .. "/screenshot.png")
+if imageId then
+  local saved = media.saveImageToAlbum(imageId)
+  if saved then
+    print("图片已保存到相册")
+  else
+    print("保存失败")
+  end
+end
+```
+
+#### saveVideoToAlbumPath - 保存视频文件到系统相册。
+
+```lua
+---@param path string
+---@return boolean
+function saveVideoToAlbumPath(path) end
+```
+
+**参数:**
+
+| 参数名 | 类型   | 是否必填 | 默认值 | 描述         |
+| ------ | ------ | -------- | ------ | ------------ |
+| `path` | string | 是       |        | 视频文件路径 |
+
+**返回值:**
+
+| 类型      | 描述         |
+| --------- | ------------ |
+| `boolean` | 是否保存成功 |
+
+**示例:**
+
+```lua
+local media = require("media")
+-- 保存视频到相册 （从 documents 目录读取）
+local documentsDir = file.getInternalDir("documents")
+local videoName = "video.mp4"
+local videoPath = tostring(documentsDir) .. "/" .. tostring(videoName)
+local saved = media.saveVideoToAlbumPath(videoPath)
+if saved then
+  print("视频已保存到相册")
+else
+  print("保存失败")
+end
+```
+
+#### deleteAllPhotos - 清空相册中的所有图片。
+
+```lua
+---@return boolean
+function deleteAllPhotos() end
+```
+
+**返回值:**
+
+| 类型      | 描述         |
+| --------- | ------------ |
+| `boolean` | 是否删除成功 |
+
+**示例:**
+
+```lua
+local media = require("media")
+-- 清空相册图片
+local deleted = media.deleteAllPhotos()
+if deleted then
+  print("相册图片已清空")
+else
+  print("清空失败")
+end
+```
+
+#### deleteAllVideos - 清空相册中的所有视频。
+
+```lua
+---@return boolean
+function deleteAllVideos() end
+```
+
+**返回值:**
+
+| 类型      | 描述         |
+| --------- | ------------ |
+| `boolean` | 是否删除成功 |
+
+**示例:**
+
+```lua
+local media = require("media")
+-- 清空相册视频
+local deleted = media.deleteAllVideos()
+if deleted then
+  print("相册视频已清空")
+else
+  print("清空失败")
+end
+```
+
+#### deleteAllScreenshots - 清空相册中的所有截图。
+
+```lua
+---@return boolean
+function deleteAllScreenshots() end
+```
+
+**示例:**
+
+```lua
+local media = require("media")
+local deleted = media.deleteAllScreenshots()
+if deleted then
+  print("相册截图已清空")
+end
+```
+
+### 音频播放
+
+#### playMp3 - 异步播放 MP3 音频文件。
+
+```lua
+---@param path string
+---@param loop boolean
+---@return boolean
+function playMp3(path, loop) end
+```
+
+**参数:**
+
+| 参数名 | 类型    | 是否必填 | 默认值 | 描述         |
+| ------ | ------- | -------- | ------ | ------------ |
+| `path` | string  | 是       |        | MP3 文件路径 |
+| `loop` | boolean | 是       |        | 是否循环播放 |
+
+**返回值:**
+
+| 类型      | 描述             |
+| --------- | ---------------- |
+| `boolean` | 是否开始播放成功 |
+
+**示例:**
+
+```lua
+local media = require("media")
+-- 播放背景音乐（循环）
+local played = media.playMp3("/path/to/background.mp3", true)
+if played then
+  print("背景音乐开始播放")
+end
+-- 播放音效（不循环）
+local soundPlayed = media.playMp3("/path/to/sound.mp3", false)
+if soundPlayed then
+  print("音效播放中")
+end
+```
+
+#### stopMp3 - 停止当前播放的 MP3 音频。
+
+```lua
+---@return boolean
+function stopMp3() end
+```
+
+**返回值:**
+
+| 类型      | 描述         |
+| --------- | ------------ |
+| `boolean` | 是否停止成功 |
+
+**示例:**
+
+```lua
+local media = require("media")
+-- 停止音乐播放
+local stopped = media.stopMp3()
+if stopped then
+  print("音乐已停止")
+else
+  print("停止失败或没有正在播放的音乐")
+end
+```
+
+#### playMp3WaitEnd - 同步播放 MP3 音频文件（播放一次并等待结束）。
+
+```lua
+---@param path string
+---@return boolean
+function playMp3WaitEnd(path) end
+```
+
+**参数:**
+
+| 参数名 | 类型   | 是否必填 | 默认值 | 描述         |
+| ------ | ------ | -------- | ------ | ------------ |
+| `path` | string | 是       |        | MP3 文件路径 |
+
+**返回值:**
+
+| 类型      | 描述                                                                 |
+| --------- | -------------------------------------------------------------------- |
+| `boolean` | 是否正常播放到结尾；系统音频中断、`stopMp3` 或新播放替换时返回 `false` |
+
+**示例:**
+
+```lua
+local media = require("media")
+-- 同步播放音频，等待播放完成
+print("开始播放音频...")
+local played = media.playMp3WaitEnd("/path/to/notification.mp3")
+if played then
+  print("音频播放完成")
+else
+  print("播放失败或被系统音频中断")
+end
+```
+
+
+#### isMp3Playing - 当前是否正在播放 MP3。
+
+```lua
+---@return boolean
+function isMp3Playing() end
+```
+
+**返回值:**
+
+| 类型      | 描述                         |
+| --------- | ---------------------------- |
+| `boolean` | 正在播放返回 `true`，否则 `false` |
+
+**示例:**
+
+```lua
+local media = require("media")
+if media.isMp3Playing() then
+  print("正在播放")
+else
+  print("未播放")
+end
+```

package/docs/apilua/mysql.md

@@ -0,0 +1,445 @@
+# MySQL 数据库模块 (MySQL)
+
+MySQL 模块提供了完整的 MySQL 数据库连接和操作功能，支持连接管理、查询执行、事务处理等核心数据库操作。
+
+## 功能概览
+
+- **连接管理**: 创建、连接、断开数据库连接
+- **数据查询**: 执行 SELECT 查询操作
+- **数据更新**: 执行 CREATE INSERT、UPDATE、DELETE 操作
+- **事务支持**: 完整的事务管理功能
+- **参数绑定**: 支持参数化查询，防止 SQL 注入
+
+## 类型定义
+
+### MySQLConfig
+
+数据库连接配置接口。
+
+```lua
+---@class MySQLConfig
+---@field host string
+---@field port number
+---@field username string
+---@field password string
+---@field database string
+---@field charset string
+---@field connectTimeout number
+---@field queryTimeout number
+```
+
+**数据类型说明:**
+
+| 参数名           | 类型   | 是否必填 | 默认值  | 描述                          |
+| ---------------- | ------ | -------- | ------- | ----------------------------- |
+| `host`           | string | 是       |         | 数据库主机地址，必填          |
+| `port`           | number | 否       | 3306    | 数据库端口，默认 3306         |
+| `username`       | string | 是       |         | 用户名，必填                  |
+| `password`       | string | 是       |         | 密码，必填                    |
+| `database`       | string | 是       |         | 数据库名，必填                |
+| `charset`        | string | 否       | utf8mb4 | 字符集，默认 utf8mb4          |
+| `connectTimeout` | number | 否       | 5000    | 连接超时时间，默认 5000 毫秒  |
+| `queryTimeout`   | number | 否       | 30000   | 查询超时时间，默认 30000 毫秒 |
+
+### MySQLResult
+
+查询结果接口。
+
+```lua
+---@class MySQLResult
+---@field rows table[]
+---@field affectedRows number
+---@field insertId number
+---@field success boolean
+---@field error string
+```
+
+**数据类型说明:**
+
+| 参数名         | 类型                  | 是否必填 | 默认值 | 描述                            |
+| -------------- | --------------------- | -------- | ------ | ------------------------------- |
+| `rows`         | table[] | 否       |        | 查询结果数据行                  |
+| `affectedRows` | number                | 否       |        | 受影响的行数                    |
+| `insertId`     | number                | 否       |        | 插入 ID（仅适用于 INSERT 操作） |
+| `success`      | boolean               | 否       |        | 查询是否成功                    |
+| `error`        | string                | 否       |        | 错误信息                        |
+
+## API 参考
+
+### 连接管理
+
+#### connect - 连接到数据库
+
+```lua
+---@param config MySQLConfig
+---@return boolean
+function connect(config) end
+```
+
+**参数:**
+
+| 参数名   | 类型        | 是否必填 | 默认值 | 描述               |
+| -------- | ----------- | -------- | ------ | ------------------ |
+| `config` | MySQLConfig | 是       |        | 数据库连接配置对象 |
+
+**返回值:**
+
+| 类型      | 描述         |
+| --------- | ------------ |
+| `boolean` | 是否连接成功 |
+
+**示例:**
+
+```lua
+local mysql = require("mysql")
+local success = mysql.connect({
+  host = "localhost",
+  port = 3306,
+  username = "root",
+  password = "password",
+  database = "test_db",
+  charset = "utf8mb4",
+  connectTimeout = 5000,
+  queryTimeout = 30000,
+})
+
+if success then
+  print("数据库连接成功")
+else
+  print("数据库连接失败")
+end
+```
+
+#### disconnect - 断开数据库连接
+
+```lua
+function disconnect() end
+```
+
+**示例:**
+
+```lua
+local mysql = require("mysql")
+mysql.disconnect()
+print("数据库连接已断开")
+```
+
+#### isConnected - 检查连接状态
+
+```lua
+---@return boolean
+function isConnected() end
+```
+
+**返回值:**
+
+| 类型      | 描述       |
+| --------- | ---------- |
+| `boolean` | 是否已连接 |
+
+**示例:**
+
+```lua
+local mysql = require("mysql")
+if mysql.isConnected() then
+  print("数据库已连接")
+else
+  print("数据库未连接")
+end
+```
+
+### 数据操作
+
+#### query - 执行查询操作
+
+执行 SELECT 查询操作，用于数据检索。
+
+```lua
+---@param sql string
+---@param params any[]?
+---@return MySQLResult
+function query(sql, params) end
+```
+
+**参数:**
+
+| 参数名   | 类型   | 是否必填 | 默认值 | 描述               |
+| -------- | ------ | -------- | ------ | ------------------ |
+| `sql`    | string | 是       |        | SQL 查询语句       |
+| `params` | any[]  | 否       |        | 查询参数数组，可选 |
+
+**返回值:**
+
+| 类型          | 描述         |
+| ------------- | ------------ |
+| `MySQLResult` | 查询结果对象 |
+
+**示例:**
+
+```lua
+local mysql = require("mysql")
+-- 简单查询
+local result1 = mysql.query("SELECT * FROM users")
+if result1.success then
+  print("查询到 " .. tostring(#result1.rows) .. " 条用户记录")
+  result1.for _, user in ipairs(rows) do
+    print("用户: " .. tostring(user.name) .. ", 邮箱: " .. tostring(user.email))
+  end)
+end
+-- 带参数查询
+local result2 = mysql.query("SELECT * FROM users WHERE age > ? AND city = ?", [
+  18,
+  "北京",
+])
+if result2.success then
+  print("找到 " .. tostring(#result2.rows) .. " 个符合条件的用户")
+else
+  print("查询失败: " .. tostring(result2.error))
+end
+```
+
+#### execute - 执行更新操作
+
+执行 CREATE、INSERT、UPDATE、DELETE 等数据修改操作。
+
+```lua
+---@param sql string
+---@param params any[]?
+---@return MySQLResult
+function execute(sql, params) end
+```
+
+**参数:**
+
+| 参数名   | 类型   | 是否必填 | 默认值 | 描述           |
+| -------- | ------ | -------- | ------ | -------------- |
+| `sql`    | string | 是       |        | SQL 语句       |
+| `params` | any[]  | 否       |        | 参数数组，可选 |
+
+**返回值:**
+
+| 类型          | 描述         |
+| ------------- | ------------ |
+| `MySQLResult` | 执行结果对象 |
+
+**示例:**
+
+```lua
+local mysql = require("mysql")
+-- 创建表
+local createTableResult = mysql.execute("
+  CREATE TABLE IF NOT EXISTS users (
+    id INT AUTO_INCREMENT PRIMARY KEY,
+    name VARCHAR(255),
+    email VARCHAR(255),
+    age INT
+  )
+")
+if createTableResult.success then
+  print("用户表创建成功")
+else
+  print("用户表创建失败: " .. tostring(createTableResult.error))
+end
+-- 插入数据
+local insertResult = mysql.execute(
+  "INSERT INTO users (name, email, age) VALUES (?, ?, ?)",
+  ["张三", "zhangsan@example.com", 25],
+)
+if insertResult.success then
+  print("用户插入成功，ID = " .. tostring(insertResult.insertId))
+  print("影响行数: " .. tostring(insertResult.affectedRows))
+end
+-- 更新数据
+local updateResult = mysql.execute("UPDATE users SET age = ? WHERE name = ?", [
+  26,
+  "张三",
+])
+if updateResult.success then
+  print("更新了 " .. tostring(updateResult.affectedRows) .. " 条记录")
+end
+-- 删除数据
+local deleteResult = mysql.execute("DELETE FROM users WHERE age < ?", [18])
+if deleteResult.success then
+  print("删除了 " .. tostring(deleteResult.affectedRows) .. " 条记录")
+else
+  print("删除失败: " .. tostring(deleteResult.error))
+end
+```
+
+### 事务管理
+
+#### beginTransaction - 开始事务
+
+```lua
+---@return boolean
+function beginTransaction() end
+```
+
+**返回值:**
+
+| 类型      | 描述             |
+| --------- | ---------------- |
+| `boolean` | 是否成功开始事务 |
+
+**示例:**
+
+```lua
+local mysql = require("mysql")
+if mysql.beginTransaction() then
+  print("事务开始")
+else
+  print("事务开始失败")
+end
+```
+
+#### commit - 提交事务
+
+```lua
+---@return boolean
+function commit() end
+```
+
+**返回值:**
+
+| 类型      | 描述             |
+| --------- | ---------------- |
+| `boolean` | 是否成功提交事务 |
+
+**示例:**
+
+```lua
+local mysql = require("mysql")
+if mysql.commit() then
+  print("事务提交成功")
+else
+  print("事务提交失败")
+end
+```
+
+#### rollback - 回滚事务
+
+```lua
+---@return boolean
+function rollback() end
+```
+
+**返回值:**
+
+| 类型      | 描述             |
+| --------- | ---------------- |
+| `boolean` | 是否成功回滚事务 |
+
+**示例:**
+
+```lua
+local mysql = require("mysql")
+if mysql.rollback() then
+  print("事务回滚成功")
+else
+  print("事务回滚失败")
+end
+```
+
+## 完整使用示例
+
+### 基本数据库操作
+
+```lua
+local mysql = require("mysql")
+-- 1. 创建连接配置
+local dbConfig = {
+  host = "localhost",
+  port = 3306,
+  username = "root",
+  password = "password",
+  database = "my_app",
+  charset = "utf8mb4",
+}
+-- 2. 连接数据库
+if mysql.connect(dbConfig) then
+  print("数据库连接成功")
+-- 3. 查询数据
+  local users = mysql.query("SELECT * FROM users WHERE status = ?", { "active" })
+  if users.success then
+    print("找到 " .. tostring(#users.rows) .. " 个活跃用户")
+  end
+-- 4. 插入新用户
+  local newUser = mysql.execute(
+    "INSERT INTO users (name, email, status) VALUES (?, ?, ?)",
+    { "新用户", "newuser@example.com", "active" },
+  )
+  if newUser.success then
+    print("新用户创建成功，ID = " .. tostring(newUser.insertId))
+  end
+-- 5. 断开连接
+  mysql.disconnect()
+else
+  print("数据库连接失败")
+end
+```
+
+### 事务处理示例
+
+```lua
+local mysql = require("mysql")
+-- 转账操作示例
+local function transferMoney(fromUserId, toUserId, amount)
+  if not mysql.beginTransaction() then
+    print("事务开始失败")
+    return false
+  end
+
+  local debitResult = mysql.execute(
+    "UPDATE accounts SET balance = balance - ? WHERE user_id = ? AND balance >= ?",
+    { amount, fromUserId, amount }
+  )
+  if not debitResult.success or debitResult.affectedRows == 0 then
+    mysql.rollback()
+    print("余额不足或扣款失败")
+    return false
+  end
+
+  local creditResult = mysql.execute(
+    "UPDATE accounts SET balance = balance + ? WHERE user_id = ?",
+    { amount, toUserId }
+  )
+  if not creditResult.success or creditResult.affectedRows == 0 then
+    mysql.rollback()
+    print("转入账户不存在或转账失败")
+    return false
+  end
+
+  local logResult = mysql.execute(
+    "INSERT INTO transfer_logs (from_user, to_user, amount, created_at) VALUES (?, ?, ?, NOW())",
+    { fromUserId, toUserId, amount }
+  )
+  if not logResult.success then
+    mysql.rollback()
+    print("转账日志记录失败")
+    return false
+  end
+
+  if mysql.commit() then
+    print("转账成功: " .. tostring(fromUserId) .. " -> " .. tostring(toUserId) .. ", 金额: " .. tostring(amount))
+    return true
+  end
+  mysql.rollback()
+  print("事务提交失败")
+  return false
+end
+-- 使用示例
+if mysql.isConnected() then
+  local success = transferMoney(1, 2, 100.0)
+  if success then
+    print("转账操作完成")
+  end
+end
+```
+
+## 注意事项
+
+1. **连接管理**: 使用全局单例连接，确保在应用生命周期内正确管理连接状态
+2. **参数绑定**: 始终使用参数化查询来防止 SQL 注入攻击
+3. **事务处理**: 在事务中发生错误时，确保调用 `rollback()` 来回滚事务
+4. **错误处理**: 检查每个操作的 `success` 字段，并适当处理错误信息
+5. **资源清理**: 在应用结束时调用 `disconnect()` 来释放数据库连接资源