ms-vite-plugin 1.1.2 → 1.1.4

package/docs/apipython/media.md

@@ -0,0 +1,221 @@
+# 媒体模块 (Media)
+
+媒体模块提供图片/视频的相册管理与 MP3 音频播放控制，支持异步与同步播放模式。
+
+## 功能概览
+
+- 相册管理：保存图片/视频到相册，清空相册图片/视频
+- 音频播放：播放/停止 MP3，支持循环播放与等待播放结束
+
+## API 参考
+
+### 相册操作
+
+#### saveImageToAlbum - 保存图像到系统相册。
+
+```python
+def saveImageToAlbum(imageId: str) -> bool
+```
+
+**参数:**
+
+| 参数名    | 类型 | 是否必填 | 默认值 | 描述                             |
+| --------- | ---- | -------- | ------ | -------------------------------- |
+| `imageId` | str  | 是       |        | 图像 ID（通过 `image` 模块获取） |
+
+**返回值:**
+
+| 类型   | 描述         |
+| ------ | ------------ |
+| `bool` | 是否保存成功 |
+
+**示例:**
+
+```python
+from kuaijs import media, image
+
+# 保存截图到相册
+img = image.captureFullScreen()
+if img:
+saved = media.saveImageToAlbum(img)
+    print("图片已保存到相册" if saved else "保存失败")
+```
+
+#### saveVideoToAlbumPath - 保存视频文件到系统相册。
+
+```python
+def saveVideoToAlbumPath(path: str) -> bool
+```
+
+**参数:**
+
+| 参数名 | 类型 | 是否必填 | 默认值 | 描述         |
+| ------ | ---- | -------- | ------ | ------------ |
+| `path` | str  | 是       |        | 视频文件路径 |
+
+**返回值:**
+
+| 类型   | 描述         |
+| ------ | ------------ |
+| `bool` | 是否保存成功 |
+
+**示例:**
+
+```python
+from kuaijs import media, file
+
+# 保存视频到相册 （从 documents 目录读取）
+documentsDir = file.getInternalDir("documents")
+videoName = "video.mp4"
+videoPath = f"{documentsDir}/{videoName}"
+saved = media.saveVideoToAlbumPath(videoPath)
+print("视频已保存到相册" if saved else "保存失败")
+```
+
+#### deleteAllPhotos - 清空相册中的所有图片。
+
+```python
+def deleteAllPhotos() -> bool
+```
+
+**返回值:**
+
+| 类型   | 描述         |
+| ------ | ------------ |
+| `bool` | 是否删除成功 |
+
+**示例:**
+
+```python
+from kuaijs import media
+
+deleted = media.deleteAllPhotos()
+print("相册图片已清空" if deleted else "清空失败")
+```
+
+#### deleteAllVideos - 清空相册中的所有视频。
+
+```python
+def deleteAllVideos() -> bool
+```
+
+**返回值:**
+
+| 类型   | 描述         |
+| ------ | ------------ |
+| `bool` | 是否删除成功 |
+
+**示例:**
+
+```python
+from kuaijs import media
+
+deleted = media.deleteAllVideos()
+print("相册视频已清空" if deleted else "清空失败")
+```
+
+#### deleteAllScreenshots - 清空相册中的所有截图。
+
+```python
+def deleteAllScreenshots() -> bool
+```
+
+**返回值:**
+
+| 类型   | 描述         |
+| ------ | ------------ |
+| `bool` | 是否删除成功 |
+
+**示例:**
+
+```python
+from kuaijs import media
+
+deleted = media.deleteAllScreenshots()
+print("相册截图已清空" if deleted else "清空失败")
+```
+
+### 音频播放
+
+#### playMp3 - 异步播放 MP3 音频文件。
+
+```python
+def playMp3(path: str, loop: bool) -> bool
+```
+
+**参数:**
+
+| 参数名 | 类型 | 是否必填 | 默认值 | 描述         |
+| ------ | ---- | -------- | ------ | ------------ |
+| `path` | str  | 是       |        | MP3 文件路径 |
+| `loop` | bool | 是       |        | 是否循环播放 |
+
+**返回值:**
+
+| 类型   | 描述             |
+| ------ | ---------------- |
+| `bool` | 是否开始播放成功 |
+
+**示例:**
+
+```python
+from kuaijs import media
+
+played = media.playMp3("/var/mobile/Media/background.mp3", True)
+if played:
+    print("背景音乐开始播放")
+
+sound_played = media.playMp3("/var/mobile/Media/sound.mp3", False)
+if sound_played:
+    print("音效播放中")
+```
+
+#### stopMp3 - 停止当前播放的 MP3 音频。
+
+```python
+def stopMp3() -> bool
+```
+
+**返回值:**
+
+| 类型   | 描述         |
+| ------ | ------------ |
+| `bool` | 是否停止成功 |
+
+**示例:**
+
+```python
+from kuaijs import media
+
+stopped = media.stopMp3()
+print("音乐已停止" if stopped else "停止失败或没有正在播放的音乐")
+```
+
+#### playMp3WaitEnd - 同步播放 MP3 音频文件（等待播放结束）。
+
+```python
+def playMp3WaitEnd(path: str, loop: bool) -> bool
+```
+
+**参数:**
+
+| 参数名 | 类型 | 是否必填 | 默认值 | 描述                                                                 |
+| ------ | ---- | -------- | ------ | -------------------------------------------------------------------- |
+| `path` | str  | 是       |        | MP3 文件路径                                                         |
+| `loop` | bool | 是       |        | 是否循环播放 注意：循环播放会阻塞线程，慎用，不要在主线程设置为 True |
+
+**返回值:**
+
+| 类型   | 描述         |
+| ------ | ------------ |
+| `bool` | 是否播放成功 |
+
+**示例:**
+
+```python
+from kuaijs import media
+
+print("开始播放音频...")
+played = media.playMp3WaitEnd("/var/mobile/Media/notification.mp3", False)
+print("音频播放完成" if played else "播放失败")
+```

package/docs/apipython/mysql.md

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