ms-vite-plugin 1.5.12 → 1.5.13

package/docs/apicn/file.md

@@ -225,7 +225,7 @@ if (是否删除成功) {
 #### 读取文件 - 读取整个文件内容。
 
 ```typescript
-function 读取文件(文件路径: 字符串): 字符串 | null;
+function 读取文件(文件路径: 字符串): 字符串 | undefined;
 ```
 
 **参数:**
@@ -238,13 +238,13 @@ function 读取文件(文件路径: 字符串): 字符串 | null;
 
 | 类型             | 描述                            |
 | ---------------- | ------------------------------- |
-| `字符串 \| null` | 文件内容；失败或不存在返回 null |
+| `字符串 \| undefined` | 文件内容；失败或不存在返回 undefined |
 
 **示例:**
 
 ```javascript
 const 文件内容 = $文件.读取文件("/path/to/file.txt");
-if (文件内容 !== null) {
+if (文件内容 !== undefined) {
   $打印信息日志(`文件内容: ${文件内容}`);
 } else {
   $打印警告日志("文件不存在或读取失败");
@@ -259,7 +259,7 @@ if (文件内容 !== null) {
 - res 目录文件只读，不能修改。
 
 ```typescript
-function 读取资源文件(文件名: 字符串): 字符串 | null;
+function 读取资源文件(文件名: 字符串): 字符串 | undefined;
 ```
 
 **参数:**
@@ -272,7 +272,7 @@ function 读取资源文件(文件名: 字符串): 字符串 | null;
 
 | 类型           | 描述                                    |
 | -------------- | --------------------------------------- |
-| `字符串\|null` | 文件内容 文件不存在或读取失败 返回 null |
+| `字符串 \| undefined` | 文件内容 文件不存在或读取失败 返回 undefined |
 
 **示例:**
 
@@ -292,7 +292,7 @@ if (配置文件内容) {
 适用于需要真实文件路径的场景（如模型文件、音视频）。用完后应调用 `清理资源文件`。
 
 ```typescript
-function 获取资源文件(文件名: 字符串): 字符串 | null;
+function 获取资源文件(文件名: 字符串): 字符串 | undefined;
 ```
 
 **参数:**
@@ -305,7 +305,7 @@ function 获取资源文件(文件名: 字符串): 字符串 | null;
 
 | 类型           | 描述                                       |
 | -------------- | ------------------------------------------ |
-| `字符串\|null` | 本地文件绝对路径；失败或不存在时返回 null |
+| `字符串 \| undefined` | 本地文件绝对路径；失败或不存在时返回 undefined |
 
 **示例:**
 
@@ -396,7 +396,7 @@ if (是否追加成功) {
 #### 读取指定行 - 读取文件指定行的内容。
 
 ```typescript
-function 读取指定行(文件路径: 字符串, 行号: 数字): 字符串 | null;
+function 读取指定行(文件路径: 字符串, 行号: 数字): 字符串 | undefined;
 ```
 
 **参数:**
@@ -410,7 +410,7 @@ function 读取指定行(文件路径: 字符串, 行号: 数字): 字符串 | n
 
 | 类型             | 描述                          |
 | ---------------- | ----------------------------- |
-| `字符串 \| null` | 行内容；失败或不存在返回 null |
+| `字符串 \| undefined` | 行内容；失败或不存在返回 undefined |
 
 **示例:**
 
@@ -422,7 +422,7 @@ $打印信息日志(`第一行内容: ${第一行内容}`);
 #### 读取所有行 - 读取文件所有行内容。
 
 ```typescript
-function 读取所有行(文件路径: 字符串): 数组<字符串> | null;
+function 读取所有行(文件路径: 字符串): 数组<字符串> | undefined;
 ```
 
 **参数:**
@@ -435,13 +435,13 @@ function 读取所有行(文件路径: 字符串): 数组<字符串> | null;
 
 | 类型                   | 描述                          |
 | ---------------------- | ----------------------------- |
-| `数组<字符串> \| null` | 所有行内容数组；失败返回 null |
+| `数组<字符串> \| undefined` | 所有行内容数组；失败返回 undefined |
 
 **示例:**
 
 ```javascript
 const 所有行内容 = $文件.读取所有行("/path/to/file.txt");
-if (所有行内容 !== null) {
+if (所有行内容 !== undefined) {
   所有行内容.forEach((line, index) => {
     $打印信息日志(`第${index + 1}行: ${line}`);
   });
@@ -462,7 +462,7 @@ function 删除指定行(文件路径: 字符串, 行号: 数字, 包含内容?:
 | ---------- | ------ | -------- | ------ | ----------------------------------- |
 | `文件路径` | 字符串 | 是       | -      | 文件路径                            |
 | `行号`     | 数字   | 是       | -      | 行号（-1 表示不按行号删除）         |
-| `包含内容` | 字符串 | 否       | null   | 包含的内容（null 表示不按内容删除） |
+| `包含内容` | 字符串 | 否       |        | 包含的内容；省略则不按内容删除 |
 
 **返回值:**
 
@@ -474,7 +474,7 @@ function 删除指定行(文件路径: 字符串, 行号: 数字, 包含内容?:
 
 ```javascript
 // 删除第3行
-$文件.删除指定行("/path/to/file.txt", 3, null);
+$文件.删除指定行("/path/to/file.txt", 3);
 
 // 删除包含"error"的行
 $文件.删除指定行("/path/to/file.txt", -1, "error");
@@ -488,7 +488,7 @@ $文件.删除指定行("/path/to/file.txt", 5, "debug");
 #### 计算文件 MD5。
 
 ```typescript
-function 计算文件MD5(文件路径: 字符串): 字符串 | null;
+function 计算文件MD5(文件路径: 字符串): 字符串 | undefined;
 ```
 
 **参数:**
@@ -501,7 +501,7 @@ function 计算文件MD5(文件路径: 字符串): 字符串 | null;
 
 | 类型             | 描述                      |
 | ---------------- | ------------------------- |
-| `字符串 \| null` | 文件 MD5 值 失败返回 null |
+| `字符串 \| undefined` | 文件 MD5 值 失败返回 undefined |
 
 **示例:**
 

package/docs/apicn/hid.md

@@ -1125,13 +1125,13 @@ $HID.APP切入前台();
 function 当前打开应用信息(): {
   name: 字符串;
   bundleId: 字符串;
-} | null;
+} | undefined;
 ```
 
 **返回值:**
 | 类型 | 描述 |
 | ---- | ---- |
-| 对象 \| null | 当前打开应用信息或 null（如果不可用） |
+| 对象 \| undefined | 当前打开应用信息或 undefined（如果不可用） |
 
 **返回对象属性:**
 | 属性 | 类型 | 描述 |
@@ -1179,13 +1179,13 @@ $HID.设置剪切板内容("你好，世界！");
 获取当前剪切板内容。
 
 ```typescript
-function 获取剪切板内容(): 字符串 | null;
+function 获取剪切板内容(): 字符串;
 ```
 
 **返回值:**
 | 类型 | 描述 |
 | ---- | ---- |
-| 字符串 \| null | 剪切板内容 |
+| 字符串 | 剪切板内容，空则为 `""` |
 
 **示例:**
 

package/docs/apicn/hotUpdate.md

@@ -42,7 +42,7 @@ interface 热更新服务器响应数据结构 {
   dialog: 布尔值; // 是否用对话框展示
   msg: 字符串; // 对话框消息
   force: 布尔值; // 是否强制更新
-  md5?: 字符串; // 更新包MD5值（可选）
+  md5: 字符串 | null; // 更新包 MD5；没有时为 null
 }
 ```
 
@@ -56,7 +56,7 @@ interface 热更新服务器响应数据结构 {
 | `dialog`           | 布尔值 | 是       | -      | 是否用对话框展示      |
 | `msg`              | 字符串 | 是       | -      | 对话框消息            |
 | `force`            | 布尔值 | 是       | -      | 是否强制更新          |
-| `md5`              | 字符串 | 否       | -      | 更新包 MD5 值（可选） |
+| `md5`              | 字符串 \| null | 否       | -      | 更新包 MD5；没有时为 `null` |
 
 ## API 参考
 

package/docs/apicn/http.md

@@ -110,7 +110,7 @@ function 发送请求(params: {
    * 响应体
    */
   body: 字符串;
-};
+} | undefined;
 ```
 
 **参数：**
@@ -204,7 +204,7 @@ function 发送GET请求(
   请求参数?: 字典<字符串>,
   超时时间?: 数字,
   请求头?: 字典<字符串>,
-): 字符串 | null;
+): 字符串 | undefined;
 ```
 
 **参数：**
@@ -255,7 +255,7 @@ function 发送POST请求(
   请求文件?: 字典<字符串>,
   超时时间?: 数字,
   请求头?: 字典<字符串>,
-): 字符串 | null;
+): 字符串 | undefined;
 ```
 
 **参数：**
@@ -303,7 +303,7 @@ function 发送JSON请求(
   请求JSON数据?: 字典<任意类型>,
   超时时间?: 数字,
   请求头?: 字典<字符串>,
-): 字符串 | null;
+): 字符串 | undefined;
 ```
 
 **参数：**

package/docs/apicn/image.md

@@ -24,7 +24,7 @@ function 截取屏幕(
   区域左上角Y坐标?: 数字,
   区域右下角X坐标?: 数字,
   区域右下角Y坐标?: 数字,
-): 字符串 | null;
+): 字符串 | undefined;
 ```
 
 **参数：**
@@ -40,7 +40,7 @@ function 截取屏幕(
 
 | 类型     | 描述                             |
 | -------- | -------------------------------- |
-| `字符串` | 截图的图片 ID，失败时返回 `null` |
+| `字符串` | 截图的图片 ID，失败时返回 `undefined` |
 
 **示例：**
 
@@ -73,7 +73,7 @@ if (图片ID) {
 ### 读取图片 - 从文件路径或图片ID读取图片。
 
 ```typescript
-function 读取图片(图片路径: 字符串): 字符串 | null;
+function 读取图片(图片路径: 字符串): 字符串 | undefined;
 ```
 
 **参数：**
@@ -86,7 +86,7 @@ function 读取图片(图片路径: 字符串): 字符串 | null;
 
 | 类型     | 描述                       |
 | -------- | -------------------------- |
-| `字符串` | 图片 ID，失败时返回 `null` |
+| `字符串` | 图片 ID，失败时返回 `undefined` |
 
 **示例：**
 
@@ -186,7 +186,7 @@ if (图片ID) {
 ### 获取图片大小 - 获取图片尺寸。
 
 ```typescript
-function 获取图片大小(图片ID: 字符串): { width: 数字; height: 数字 } | null;
+function 获取图片大小(图片ID: 字符串): { width: 数字; height: 数字 } | undefined;
 ```
 
 **参数：**
@@ -199,7 +199,7 @@ function 获取图片大小(图片ID: 字符串): { width: 数字; height: 数
 
 | 类型                                    | 描述                                                           |
 | --------------------------------------- | -------------------------------------------------------------- |
-| `{ width: 数字; height: 数字 } \| null` | 图片尺寸对象，包含 `width` 和 `height` 属性，失败时返回 `null` |
+| `{ width: 数字; height: 数字 } \| undefined` | 图片尺寸对象，包含 `width` 和 `height` 属性，失败时返回 `undefined` |
 
 **示例：**
 
@@ -938,7 +938,7 @@ if (图片ID) {
 ### 旋转图片
 
 ```typescript
-function 旋转图片(图片ID: 字符串, 角度: 数字): 字符串 | null;
+function 旋转图片(图片ID: 字符串, 角度: 数字): 字符串 | undefined;
 ```
 
 **参数：**
@@ -952,7 +952,7 @@ function 旋转图片(图片ID: 字符串, 角度: 数字): 字符串 | null;
 
 | 类型             | 描述                                |
 | ---------------- | ----------------------------------- |
-| `字符串 \| null` | 旋转后的新图片 ID 失败时返回 `null` |
+| `字符串 \| undefined` | 旋转后的新图片 ID 失败时返回 `undefined` |
 
 **示例：**
 
@@ -973,7 +973,7 @@ if (图片ID) {
 ### 灰度化图片
 
 ```typescript
-function 灰度化图片(图片ID: 字符串): 字符串;
+function 灰度化图片(图片ID: 字符串): 字符串 | undefined;
 ```
 
 **参数：**
@@ -1007,7 +1007,7 @@ if (图片ID) {
 ### 二值化图片
 
 ```typescript
-function 二值化图片(图片ID: 字符串, 阈值: 数字): 字符串;
+function 二值化图片(图片ID: 字符串, 阈值: 数字): 字符串 | undefined;
 ```
 
 **参数：**
@@ -1080,7 +1080,7 @@ if (图片ID) {
 ### 扫码条码（支持一维码和二维码）
 
 ```typescript
-function 扫描条码(图片ID: 字符串): 字符串 | null;
+function 扫描条码(图片ID: 字符串): 字符串 | undefined;
 ```
 
 **参数：**
@@ -1093,7 +1093,7 @@ function 扫描条码(图片ID: 字符串): 字符串 | null;
 
 | 类型             | 描述                        |
 | ---------------- | --------------------------- |
-| `字符串 \| null` | 扫码结果，失败时返回 `null` |
+| `字符串 \| undefined` | 扫码结果，失败时返回 `undefined` |
 
 **示例：**
 
@@ -1115,7 +1115,7 @@ if (图片ID) {
 ### base64 转图片
 
 ```typescript
-function base64转图片(base64: 字符串): 字符串;
+function base64转图片(base64: 字符串): 字符串 | undefined;
 ```
 
 **参数：**

package/docs/apicn/mysql.md

@@ -50,9 +50,9 @@ interface MySQL连接配置 {
 interface MySQL查询结果 {
   rows: 数组<字典<任意类型>>; // 查询结果数据行
   affectedRows: 数字; // 受影响的行数
-  insertId?: 数字; // 插入ID（仅适用于INSERT操作）
+  insertId: 数字 | null; // 插入ID（仅适用于INSERT操作）；没有插入时为 null
   success: 布尔值; // 查询是否成功
-  error?: 字符串; // 错误信息
+  error: 字符串 | null; // 错误信息；成功时为 null
 }
 ```
 
@@ -62,9 +62,9 @@ interface MySQL查询结果 {
 | -------------- | -------------------- | -------- | ------ | ------------------------------- |
 | `rows`         | 数组<字典<任意类型>> | 否       |        | 查询结果数据行                  |
 | `affectedRows` | 数字                 | 否       |        | 受影响的行数                    |
-| `insertId`     | 数字                 | 否       |        | 插入 ID（仅适用于 INSERT 操作） |
+| `insertId`     | 数字 \| null         | 否       |        | 插入 ID；没有插入时为 `null`            |
 | `success`      | 布尔值               | 否       |        | 查询是否成功                    |
-| `error`        | 字符串               | 否       |        | 错误信息                        |
+| `error`        | 字符串 \| null       | 否       |        | 错误信息；成功时为 `null`               |
 
 ## API 参考
 

package/docs/apicn/netCard.md

@@ -1,17 +1,16 @@
 # 卡密模块 ($卡密)
 
-卡密模块提供了卡密验证、备注设置以及键值对存储功能，用于管理网络卡密相关的操作。
+卡密模块提供了卡密验证和备注设置功能，用于管理网络卡密相关的操作。
 
 ## 功能概览
 
 - **卡密验证**: 验证卡密的有效性
 - **备注管理**: 设置和管理卡密备注信息
-- **云变量存储**: 提供键值对形式的数据存储和读取功能
 
 ## 注意事项
 
 1. **卡密安全**: 卡密信息应当妥善保管，避免在日志中明文输出
-2. **普通卡密模式**: 需要先调用 `$卡密.验证(卡密)` 验证卡密，验证通过后才能调用获取卡密信息、备注和云变量等接口
+2. **普通卡密模式**: 需要先调用 `$卡密.验证(卡密)` 验证卡密，验证通过后才能调用获取卡密信息和备注等接口
 3. **授权卡密模式**: App 打开加密 UI 或运行脚本前会完成授权和卡密验证，脚本中不需要重复让用户输入卡密，也不需要重复调用 `$卡密.验证`
 4. **兼容旧脚本**: 授权卡密模式下调用 `$卡密.验证` 会直接返回 `true`，用于兼容原来已经写了验证逻辑的脚本
 
@@ -73,7 +72,7 @@ function 验证(卡密: 字符串): 布尔值;
 
 **说明：**
 
-普通卡密模式下，该方法会请求普通卡密验证接口，验证成功后才能继续使用卡密信息、备注和云变量相关能力。
+普通卡密模式下，该方法会请求普通卡密验证接口，验证成功后才能继续使用卡密信息和备注相关能力。
 
 授权卡密模式下，App 层已经完成授权和卡密验证，脚本侧不需要重复调用该方法；如果旧脚本仍然调用，方法会直接返回 `true`。
 
@@ -110,7 +109,7 @@ if (!$卡密.是否授权卡密模式()) {
 #### 获取卡密信息
 
 ```typescript
-function 获取卡密信息(): 卡密信息 | null;
+function 获取卡密信息(): 卡密信息 | undefined;
 ```
 
 **返回值：**
@@ -168,71 +167,3 @@ if (success) {
   $打印错误日志("备注设置失败");
 }
 ```
-
-### 云变量
-
-#### 设置值 - 设置键值对
-
-```typescript
-function 设置值(键: 字符串, 值: 字符串): 字符串;
-```
-
-**参数说明：**
-
-| 参数名 | 类型   | 是否必填 | 默认值 | 描述       |
-| ------ | ------ | -------- | ------ | ---------- |
-| `键`   | 字符串 | 是       |        | 存储的键名 |
-| `值`   | 字符串 | 是       |        | 存储的值   |
-
-**返回值：**
-
-| 类型     | 描述                                          |
-| -------- | --------------------------------------------- |
-| `字符串` | 成功时返回设置的 value 值，失败时返回空字符串 |
-
-**示例：**
-
-```typescript
-// 设置键值对
-const key = "userConfig";
-const value = "enableNotification";
-const result = $卡密.设置值(key, value);
-
-if (result === value) {
-  $打印信息日志(`成功设置 ${key}: ${value}`);
-} else {
-  $打印错误日志("设置失败");
-}
-```
-
-#### 获取值 - 获取键值对
-
-```typescript
-function 获取值(键: 字符串): 字符串;
-```
-
-**参数说明：**
-
-| 参数名 | 类型   | 是否必填 | 默认值 | 描述         |
-| ------ | ------ | -------- | ------ | ------------ |
-| `键`   | 字符串 | 是       |        | 要获取的键名 |
-
-**返回值：**
-
-| 类型     | 描述                                             |
-| -------- | ------------------------------------------------ |
-| `字符串` | 成功时返回对应的值，失败或键不存在时返回空字符串 |
-
-**示例：**
-
-```typescript
-// 获取键值对
-const key = "userConfig";
-const value = $卡密.获取值(key);
-
-if (value) {
-  $打印信息日志(`获取到配置: ${key} = ${value}`);
-} else {
-  $打印警告日志(`配置 ${key} 不存在或获取失败"`);
-}
-```

package/docs/apicn/node.md

@@ -100,9 +100,9 @@ const listPage = $创建节点选择器({ mode: 2 });
 | `释放内存()` | 释放内存 |
 | `加载节点数据(timeout?)` | 重新加载界面节点，默认超时 5000ms |
 | `清除选择器()` | 清除已设置的筛选条件 |
-| `xml(timeout?)` | 获取界面 XML，失败返回 `null` |
+| `xml(timeout?)` | 获取界面 XML，失败返回 `undefined` |
 | `获取节点信息(timeout?)` | 获取所有匹配节点 |
-| `获取一个节点信息(timeout?)` | 获取第一个匹配节点，没有则 `null` |
+| `获取一个节点信息(timeout?)` | 获取第一个匹配节点，没有则 `undefined` |
 
 超时单位均为毫秒，默认 `5000`。
 

package/docs/apicn/sqlite.md

@@ -0,0 +1,197 @@
+# SQLite 数据库模块 ($SQLite数据库)
+
+SQLite 模块提供本地数据库文件的打开、查询、执行和事务。可以同时打开多个库，每个库用 `打开` 返回的句柄操作。
+
+## 功能概览
+
+- **多库句柄**: `打开` 返回句柄，后续方法把句柄作为第一个参数
+- **数据查询**: 执行 SELECT 查询
+- **数据更新**: 执行 CREATE、INSERT、UPDATE、DELETE
+- **事务支持**: `开始事务` / `提交事务` / `回滚事务`
+- **参数绑定**: 使用 `?` 占位，防止 SQL 注入
+
+## 注意事项
+
+1. **文件路径**: 路径必须是绝对路径，与 `$文件` 模块相同。相对路径会打开失败。
+2. **内存库**: 路径传 `":memory:"` 打开内存数据库。
+3. **句柄**: 先 `打开` 再查询；脚本结束会关闭本次运行打开的全部句柄，仍建议用完 `关闭`。
+4. **BLOB**: 第一版不把 BLOB 转成字符串，读到的该格为 `null`。
+5. **锁定等待**: 数据库被占用时最多等待 5 秒。
+
+## 类型定义
+
+### SQLite查询结果
+
+查询 / 执行结果。
+
+```typescript
+interface SQLite查询结果 {
+  rows: 数组<字典<任意类型>>;
+  affectedRows: 数字;
+  insertId: 数字 | null;
+  success: 布尔值;
+  error: 字符串 | null;
+}
+```
+
+**数据类型说明:**
+
+| 参数名         | 类型                 | 是否必填 | 默认值 | 描述                         |
+| -------------- | -------------------- | -------- | ------ | ---------------------------- |
+| `rows`         | 数组<字典<任意类型>> | 否       |        | 查询结果数据行               |
+| `affectedRows` | 数字                 | 否       |        | 受影响的行数                 |
+| `insertId`     | 数字 \| null         | 否       |        | 本次连接最近一次插入的 rowid；没有插入时为 `null` |
+| `success`      | 布尔值               | 否       |        | 是否成功                     |
+| `error`        | 字符串 \| null       | 否       |        | 错误信息；成功时为 `null`    |
+
+## API 参考
+
+### 连接管理
+
+#### 打开 - 打开数据库
+
+```typescript
+function 打开(路径: 字符串): 字符串 | undefined;
+```
+
+**参数:**
+
+| 参数名 | 类型   | 是否必填 | 默认值 | 描述                      |
+| ------ | ------ | -------- | ------ | ------------------------- |
+| `路径` | 字符串 | 是       |        | 绝对路径，或 `":memory:"` |
+
+**返回值:**
+
+| 类型             | 描述                         |
+| ---------------- | ---------------------------- |
+| `字符串 \| undefined` | 成功返回句柄，失败返回 `undefined` |
+
+**示例:**
+
+```javascript
+const 路径 = $文件.获取内部目录("documents") + "/app.db";
+const 库 = $SQLite数据库.打开(路径);
+if (!库) {
+  $打印错误日志("打开失败");
+}
+```
+
+#### 关闭 - 关闭数据库
+
+```typescript
+function 关闭(句柄: 字符串): 无返回值;
+```
+
+**参数:**
+
+| 参数名 | 类型   | 是否必填 | 默认值 | 描述              |
+| ------ | ------ | -------- | ------ | ----------------- |
+| `句柄` | 字符串 | 是       |        | `打开` 返回的句柄 |
+
+**示例:**
+
+```javascript
+$SQLite数据库.关闭(库);
+```
+
+#### 是否已打开 - 检查句柄是否仍打开
+
+```typescript
+function 是否已打开(句柄: 字符串): 布尔值;
+```
+
+**返回值:**
+
+| 类型   | 描述              |
+| ------ | ----------------- |
+| `布尔值` | 仍打开返回 `true` |
+
+**示例:**
+
+```javascript
+if ($SQLite数据库.是否已打开(库)) {
+  $打印信息日志("数据库已打开");
+}
+```
+
+### 数据操作
+
+#### 查询 - 执行查询
+
+```typescript
+function 查询(句柄: 字符串, sql语句: 字符串, 参数?: 数组<任意类型>): SQLite查询结果;
+```
+
+**示例:**
+
+```javascript
+const 查询结果 = $SQLite数据库.查询(库, "SELECT * FROM t WHERE id = ?", [1]);
+if (查询结果.success) {
+  $打印信息日志(`查询到 ${查询结果.rows.length} 条记录`);
+} else {
+  $打印错误日志(`查询失败: ${查询结果.error}`);
+}
+```
+
+#### 执行 - 执行更新
+
+```typescript
+function 执行(句柄: 字符串, sql语句: 字符串, 参数?: 数组<任意类型>): SQLite查询结果;
+```
+
+**示例:**
+
+```javascript
+$SQLite数据库.执行(
+  库,
+  "CREATE TABLE IF NOT EXISTS t (id INTEGER PRIMARY KEY, name TEXT)",
+);
+const 插入结果 = $SQLite数据库.执行(库, "INSERT INTO t(name) VALUES (?)", [
+  "a",
+]);
+if (插入结果.success) {
+  $打印信息日志(`插入 ID: ${插入结果.insertId}`);
+}
+```
+
+### 事务管理
+
+#### 开始事务 / 提交事务 / 回滚事务
+
+```typescript
+function 开始事务(句柄: 字符串): 布尔值;
+function 提交事务(句柄: 字符串): 布尔值;
+function 回滚事务(句柄: 字符串): 布尔值;
+```
+
+**示例:**
+
+```javascript
+if ($SQLite数据库.开始事务(库)) {
+  $SQLite数据库.执行(库, "INSERT INTO t(name) VALUES (?)", ["a"]);
+  $SQLite数据库.执行(库, "INSERT INTO t(name) VALUES (?)", ["b"]);
+  if (!$SQLite数据库.提交事务(库)) {
+    $SQLite数据库.回滚事务(库);
+  }
+}
+```
+
+## 完整使用示例
+
+```javascript
+const 库 = $SQLite数据库.打开($文件.获取内部目录("documents") + "/app.db");
+if (!库) {
+  $打印错误日志("打开失败");
+} else {
+  $SQLite数据库.执行(
+    库,
+    "CREATE TABLE IF NOT EXISTS t (id INTEGER PRIMARY KEY, name TEXT)",
+  );
+  $SQLite数据库.执行(库, "INSERT INTO t(name) VALUES (?)", ["a"]);
+  const 结果 = $SQLite数据库.查询(库, "SELECT * FROM t WHERE id = ?", [1]);
+  if (结果.success) {
+    $打印信息日志(JSON.stringify(结果.rows));
+  }
+  $SQLite数据库.关闭(库);
+}
+```