ms-vite-plugin 1.1.2 → 1.1.4

package/docs/api/media.md

@@ -0,0 +1,248 @@
+# 媒体模块 (Media)
+
+媒体模块提供了丰富的媒体操作功能，包括图片和视频的相册管理，以及音频播放控制等功能。
+
+## 功能概览
+
+- **相册管理**: 保存图片和视频到相册，清理相册内容
+- **音频播放**: MP3 音频的播放、停止和循环控制
+- **同步/异步**: 支持异步播放和同步等待播放结束
+
+## API 参考
+
+### 相册操作
+
+#### saveImageToAlbum - 保存图像到系统相册。
+
+```typescript
+function saveImageToAlbum(imageId: string): boolean;
+```
+
+**参数:**
+
+| 参数名    | 类型   | 是否必填 | 默认值 | 描述                           |
+| --------- | ------ | -------- | ------ | ------------------------------ |
+| `imageId` | string | 是       |        | 图像 ID（通过 image 模块获取） |
+
+**返回值:**
+
+| 类型      | 描述         |
+| --------- | ------------ |
+| `boolean` | 是否保存成功 |
+
+**示例:**
+
+```javascript
+// 保存截图到相册
+media.saveImageToAlbum("screen");
+
+const documentsDir = file.getInternalDir("documents");
+// 读取图像并保存到相册
+const imageId = image.readImage(`${documentsDir}/screenshot.png`);
+if (imageId) {
+  const saved = media.saveImageToAlbum(imageId);
+  if (saved) {
+    logi("图片已保存到相册");
+  } else {
+    logi("保存失败");
+  }
+}
+```
+
+#### saveVideoToAlbumPath - 保存视频文件到系统相册。
+
+```typescript
+function saveVideoToAlbumPath(path: string): boolean;
+```
+
+**参数:**
+
+| 参数名 | 类型   | 是否必填 | 默认值 | 描述         |
+| ------ | ------ | -------- | ------ | ------------ |
+| `path` | string | 是       |        | 视频文件路径 |
+
+**返回值:**
+
+| 类型      | 描述         |
+| --------- | ------------ |
+| `boolean` | 是否保存成功 |
+
+**示例:**
+
+```javascript
+// 保存视频到相册 （从 documents 目录读取）
+const documentsDir = file.getInternalDir("documents");
+const videoName = "video.mp4";
+const videoPath = `${documentsDir}/${videoName}`;
+const saved = media.saveVideoToAlbumPath(videoPath);
+if (saved) {
+  logi("视频已保存到相册");
+} else {
+  logi("保存失败");
+}
+```
+
+#### deleteAllPhotos - 清空相册中的所有图片。
+
+```typescript
+function deleteAllPhotos(): boolean;
+```
+
+**返回值:**
+
+| 类型      | 描述         |
+| --------- | ------------ |
+| `boolean` | 是否删除成功 |
+
+**示例:**
+
+```javascript
+// 清空相册图片
+const deleted = media.deleteAllPhotos();
+if (deleted) {
+  logi("相册图片已清空");
+} else {
+  logi("清空失败");
+}
+```
+
+#### deleteAllVideos - 清空相册中的所有视频。
+
+```typescript
+function deleteAllVideos(): boolean;
+```
+
+**返回值:**
+
+| 类型      | 描述         |
+| --------- | ------------ |
+| `boolean` | 是否删除成功 |
+
+**示例:**
+
+```javascript
+// 清空相册视频
+const deleted = media.deleteAllVideos();
+if (deleted) {
+  logi("相册视频已清空");
+} else {
+  logi("清空失败");
+}
+```
+
+#### deleteAllScreenshots - 清空相册中的所有截图。
+
+```typescript
+function deleteAllScreenshots(): boolean;
+```
+
+**返回值:**
+
+| 类型      | 描述         |
+| --------- | ------------ |
+| `boolean` | 是否删除成功 |
+
+**示例:**
+
+```javascript
+// 清空相册截图
+const deleted = media.deleteAllScreenshots();
+if (deleted) {
+  logi("相册截图已清空");
+} else {
+  logi("清空失败");
+}
+```
+
+### 音频播放
+
+#### playMp3 - 异步播放 MP3 音频文件。
+
+```typescript
+function playMp3(path: string, loop: boolean): boolean;
+```
+
+**参数:**
+
+| 参数名 | 类型    | 是否必填 | 默认值 | 描述         |
+| ------ | ------- | -------- | ------ | ------------ |
+| `path` | string  | 是       |        | MP3 文件路径 |
+| `loop` | boolean | 是       |        | 是否循环播放 |
+
+**返回值:**
+
+| 类型      | 描述             |
+| --------- | ---------------- |
+| `boolean` | 是否开始播放成功 |
+
+**示例:**
+
+```javascript
+// 播放背景音乐（循环）
+const played = media.playMp3("/path/to/background.mp3", true);
+if (played) {
+  logi("背景音乐开始播放");
+}
+
+// 播放音效（不循环）
+const soundPlayed = media.playMp3("/path/to/sound.mp3", false);
+if (soundPlayed) {
+  logi("音效播放中");
+}
+```
+
+#### stopMp3 - 停止当前播放的 MP3 音频。
+
+```typescript
+function stopMp3(): boolean;
+```
+
+**返回值:**
+
+| 类型      | 描述         |
+| --------- | ------------ |
+| `boolean` | 是否停止成功 |
+
+**示例:**
+
+```javascript
+// 停止音乐播放
+const stopped = media.stopMp3();
+if (stopped) {
+  logi("音乐已停止");
+} else {
+  logi("停止失败或没有正在播放的音乐");
+}
+```
+
+#### playMp3WaitEnd - 同步播放 MP3 音频文件（等待播放结束）。
+
+```typescript
+function playMp3WaitEnd(path: string, loop: boolean): boolean;
+```
+
+**参数:**
+
+| 参数名 | 类型    | 是否必填 | 默认值 | 描述                                                                 |
+| ------ | ------- | -------- | ------ | -------------------------------------------------------------------- |
+| `path` | string  | 是       |        | MP3 文件路径                                                         |
+| `loop` | boolean | 是       |        | 是否循环播放 注意：循环播放会阻塞线程，慎用，不要在主线程设置为 true |
+
+**返回值:**
+
+| 类型      | 描述         |
+| --------- | ------------ |
+| `boolean` | 是否播放成功 |
+
+**示例:**
+
+```javascript
+// 同步播放音频，等待播放完成
+logi("开始播放音频...");
+const played = media.playMp3WaitEnd("/path/to/notification.mp3", false);
+if (played) {
+  logi("音频播放完成");
+} else {
+  logi("播放失败");
+}
+```

package/docs/api/mysql.md

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