ms-vite-plugin 1.1.2 → 1.1.3

package/docs/apicn/media.md

@@ -0,0 +1,252 @@
+# 媒体模块 ($媒体)
+
+媒体模块提供了丰富的媒体操作功能，包括图片和视频的相册管理，以及音频播放控制等功能。
+
+## 功能概览
+
+- **相册管理**: 保存图片和视频到相册，清理相册内容
+- **音频播放**: MP3 音频的播放、停止和循环控制
+- **同步/异步**: 支持异步播放和同步等待播放结束
+
+## API 参考
+
+### 相册操作
+
+#### 保存图片到相册
+
+```typescript
+function 保存图片到相册(图像ID: 字符串): 布尔值;
+```
+
+**参数:**
+
+| 参数名   | 类型   | 是否必填 | 默认值 | 描述                           |
+| -------- | ------ | -------- | ------ | ------------------------------ |
+| `图像ID` | 字符串 | 是       |        | 图像 ID（通过 image 模块获取） |
+
+**返回值:**
+
+| 类型     | 描述         |
+| -------- | ------------ |
+| `布尔值` | 是否保存成功 |
+
+**示例:**
+
+```javascript
+// 保存截图到相册
+$媒体.保存图片到相册("screen");
+const 文档目录 = $文件.获取内部目录("documents");
+
+// 读取图像并保存到相册
+const 图像ID = $图像.读取图片(`${文档目录}/screenshot.png`);
+if (图像ID) {
+  const 是否保存成功 = $媒体.保存图片到相册(图像ID);
+  if (是否保存成功) {
+    $打印信息日志("图片已保存到相册");
+  } else {
+    $打印错误日志("保存失败");
+  }
+}
+```
+
+#### 保存视频到相册
+
+```typescript
+function 保存视频到相册(视频路径: 字符串): 布尔值;
+```
+
+**参数:**
+
+| 参数名     | 类型   | 是否必填 | 默认值 | 描述         |
+| ---------- | ------ | -------- | ------ | ------------ |
+| `视频路径` | 字符串 | 是       |        | 视频文件路径 |
+
+**返回值:**
+
+| 类型     | 描述         |
+| -------- | ------------ |
+| `布尔值` | 是否保存成功 |
+
+**示例:**
+
+```javascript
+// 保存视频到相册 （从 documents 目录读取）
+const 文档目录 = $文件.获取内部目录("documents");
+const 文件名称 = "video.mp4";
+const 视频路径 = `${文档目录}/${文件名称}`;
+const 是否保存成功 = $媒体.保存视频到相册(视频路径);
+if (是否保存成功) {
+  $打印信息日志("视频已保存到相册");
+} else {
+  $打印错误日志("保存失败");
+}
+```
+
+#### 清空相册中的图片
+
+```typescript
+function 清空相册中的图片(): 布尔值;
+```
+
+**返回值:**
+
+| 类型     | 描述         |
+| -------- | ------------ |
+| `布尔值` | 是否删除成功 |
+
+**示例:**
+
+```javascript
+// 清空相册图片
+const 是否删除成功 = $媒体.清空相册中的图片();
+if (是否删除成功) {
+  $打印信息日志("相册图片已清空");
+} else {
+  $打印错误日志("清空失败");
+}
+```
+
+#### 清空相册中的视频
+
+```typescript
+function 清空相册中的视频(): 布尔值;
+```
+
+**返回值:**
+
+| 类型     | 描述         |
+| -------- | ------------ |
+| `布尔值` | 是否删除成功 |
+
+**示例:**
+
+```javascript
+// 清空相册视频
+const 是否删除成功 = $媒体.清空相册中的视频();
+if (是否删除成功) {
+  $打印信息日志("相册视频已清空");
+} else {
+  $打印错误日志("清空失败");
+}
+```
+
+#### 清空相册中的截图
+
+```typescript
+function 清空相册中的截图(): 布尔值;
+```
+
+**返回值:**
+
+| 类型     | 描述         |
+| -------- | ------------ |
+| `布尔值` | 是否删除成功 |
+
+**示例:**
+
+```javascript
+// 清空相册截图
+const 是否删除成功 = $媒体.清空相册中的截图();
+if (是否删除成功) {
+  $打印信息日志("相册截图已清空");
+} else {
+  $打印错误日志("清空失败");
+}
+```
+
+### 音频播放
+
+#### 播放 MP3 音乐 - 异步播放 MP3 音频文件。
+
+```typescript
+function 播放MP3音乐(文件路径: 字符串, 是否循环播放: 布尔值): 布尔值;
+```
+
+**参数:**
+
+| 参数名         | 类型   | 是否必填 | 默认值 | 描述         |
+| -------------- | ------ | -------- | ------ | ------------ |
+| `文件路径`     | 字符串 | 是       |        | MP3 文件路径 |
+| `是否循环播放` | 布尔值 | 是       |        | 是否循环播放 |
+
+**返回值:**
+
+| 类型     | 描述             |
+| -------- | ---------------- |
+| `布尔值` | 是否开始播放成功 |
+
+**示例:**
+
+```javascript
+// 播放背景音乐（循环）
+const 是否开始播放成功 = $媒体.播放MP3音乐("/path/to/background.mp3", true);
+if (是否开始播放成功) {
+  $打印信息日志("背景音乐开始播放");
+} else {
+  $打印错误日志("背景音乐播放失败");
+}
+
+// 播放音效（不循环）
+const 是否开始播放成功 = $媒体.播放MP3音乐("/path/to/sound.mp3", false);
+if (是否开始播放成功) {
+  $打印信息日志("音效播放中");
+} else {
+  $打印错误日志("音效播放失败");
+}
+```
+
+#### 停止播放 MP3 音乐 - 停止当前播放的 MP3 音频。
+
+```typescript
+function 停止播放MP3音乐(): 布尔值;
+```
+
+**返回值:**
+
+| 类型     | 描述         |
+| -------- | ------------ |
+| `布尔值` | 是否停止成功 |
+
+**示例:**
+
+```javascript
+// 停止音乐播放
+const 是否停止成功 = $媒体.停止播放MP3音乐();
+if (是否停止成功) {
+  $打印信息日志("音乐已停止");
+} else {
+  $打印错误日志("停止失败或没有正在播放的音乐");
+}
+```
+
+#### 同步播放 MP3 音乐 - 同步播放 MP3 音频文件（等待播放结束）。
+
+```typescript
+function 同步播放MP3音乐(文件路径: 字符串, 是否循环播放: 布尔值): 布尔值;
+```
+
+**参数:**
+
+| 参数名         | 类型   | 是否必填 | 默认值 | 描述                                                                 |
+| -------------- | ------ | -------- | ------ | -------------------------------------------------------------------- |
+| `文件路径`     | 字符串 | 是       |        | MP3 文件路径                                                         |
+| `是否循环播放` | 布尔值 | 是       |        | 是否循环播放 注意：循环播放会阻塞线程，慎用，不要在主线程设置为 true |
+
+**返回值:**
+
+| 类型     | 描述         |
+| -------- | ------------ |
+| `布尔值` | 是否播放成功 |
+
+**示例:**
+
+```javascript
+// 同步播放音频，等待播放完成
+$打印信息日志("开始播放音频...");
+const 是否播放成功 = $媒体.同步播放MP3音乐("/path/to/notification.mp3", false);
+if (是否播放成功) {
+  $打印信息日志("音频播放完成");
+} else {
+  $打印错误日志("播放失败");
+}
+```

package/docs/apicn/mysql.md

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