ms-vite-plugin 1.1.1 → 1.1.3

package/docs/apicn/global.md

@@ -0,0 +1,613 @@
+# 全局定义 (Global)
+
+全局定义模块提供了应用运行时的全局常量和函数，包括应用信息、调试状态、线程控制等核心功能。
+
+**全局模块无调用前缀，直接使用即可。**
+
+## 功能概览
+
+- **应用信息**: 获取应用版本、名称、包信息等
+- **运行状态**: 检查调试模式、退出状态等
+- **线程控制**: 线程睡眠、应用退出等
+- **脚本生命周期**: 设置停止回调、异常回调、重启脚本等
+- **时间工具**: 获取时间戳
+- **应用控制**: 切换应用到前台
+
+## 全局常量
+
+### 运行模式
+
+### 运行模式
+
+#### **$运行模式**
+
+用户设置选择的运行模式，"agent" 或 "hid"。
+
+```typescript
+declare const $运行模式: "agent" | "hid";
+```
+
+**示例:**
+
+```javascript
+$打印信息日志(`运行模式: ${$运行模式}`);
+```
+
+### 是否使用内置Agent
+
+#### **$是否内置Agent**
+
+是否使用内置 Agent。
+
+```typescript
+declare const $是否内置Agent: 布尔值;
+```
+
+**示例:**
+
+```javascript
+$打印信息日志(`是否使用内置Agent: ${$是否内置Agent}`);
+```
+
+### 调试和状态
+
+#### **$是否调试**
+
+当前是否为调试模式。
+
+```typescript
+declare const $是否调试: 布尔值;
+```
+
+**示例:**
+
+```javascript
+$打印信息日志($是否调试);
+```
+
+### 应用信息
+
+#### **$平台**
+
+平台信息，标识当前应用运行的平台，例如 "ios"、"android" 等。
+
+```typescript
+declare const $平台: "ios" | "android";
+```
+
+**示例:**
+
+```javascript
+$打印信息日志(`平台: ${$平台}`);
+```
+
+#### **$APP 应用版本**
+
+应用版本号，注意这是快点 JS 应用的版本号，不是脚本的版本号。
+
+```typescript
+declare const $APP应用版本: 字符串;
+```
+
+**示例:**
+
+```javascript
+logi(`应用版本: ${$APP应用版本}`);
+```
+
+#### **$APP 应用构建号**
+
+应用构建号，注意这是快点 JS 应用的构建号，不是脚本的构建号。
+
+```typescript
+declare const $APP应用构建号: 数字;
+```
+
+**示例:**
+
+```javascript
+logi(`构建号: ${$APP应用构建号}`);
+
+// 要求最低版本号和构建号示例
+const 最低版本号 = "1.1.0";
+const 最低构建号 = 2;
+
+function 确保APP版本(最低版本号, 最低构建号) {
+  function 比较版本号(a, b) {
+    const pa = a.split(".").map(Number);
+    const pb = b.split(".").map(Number);
+    const len = Math.max(pa.length, pb.length);
+    for (let i = 0; i < len; i++) {
+      const ai = pa[i] || 0;
+      const bi = pb[i] || 0;
+      if (ai !== bi) return ai - bi;
+    }
+    return 0;
+  }
+
+  const 版本满足 = 比较版本号($APP应用版本, 最低版本号) >= 0;
+  const 构建满足 = $APP应用构建号 >= 最低构建号;
+  if (!版本满足 || !构建满足) {
+    $视图.显示警告对话框("版本号提示", "应用版本过低，请升级到最新版本");
+    $退出脚本();
+  }
+}
+
+确保APP版本(最低版本号, 最低构建号);
+```
+
+#### **$APP 应用名称**
+
+应用名称，注意这是快点 JS 应用的名称，不是脚本的名称。
+
+```typescript
+declare const $APP应用名称: 字符串;
+```
+
+**示例:**
+
+```javascript
+logi(`应用名称: ${$APP应用名称}`);
+```
+
+#### **$APP 应用包名**
+
+应用的 Bundle ID，注意这是快点 JS 应用的 Bundle ID，不是脚本的 Bundle ID。
+
+```typescript
+declare const $APP应用包名: 字符串;
+```
+
+**示例:**
+
+```javascript
+logi(`Bundle ID: ${$APP应用包名}`);
+```
+
+### 线程信息
+
+#### **$线程名称**
+
+当前线程名称。
+
+```typescript
+declare const $线程名称: 字符串;
+```
+
+**示例:**
+
+```javascript
+logi(`当前线程: ${$线程名称}`);
+```
+
+### 包（脚本）信息
+
+#### **$脚本配置**
+
+应用包（脚本）的配置信息，package.json 的内容
+
+```typescript
+declare const $脚本配置: {
+  name: 字符串;
+  appVersion: 字符串;
+  appId: 字符串;
+  [key: 字符串]: 任意值;
+};
+```
+
+**属性:**
+
+- `name` - 脚本项目名称
+- `appVersion` - 脚本版本号
+- `appId` - 脚本 Id
+- `[key: 字符串]: 任意值` - 其他自定义属性
+
+**示例:**
+
+```javascript
+$打印信息日志(`脚本项目名称: ${$脚本配置.name}`);
+$打印信息日志(`脚本版本号: ${$脚本配置.appVersion}`);
+
+// 访问自定义属性
+if ($脚本配置.author) {
+  $打印信息日志(`作者: ${$脚本配置.author}`);
+}
+```
+
+## 全局函数
+
+### $延时
+
+使当前线程睡眠指定的毫秒数。
+
+```typescript
+declare const $延时: (毫秒: 数字) => 无返回值;
+```
+
+**参数:**
+
+| 参数名 | 类型 | 是否必填 | 默认值 | 描述             |
+| ------ | ---- | -------- | ------ | ---------------- |
+| `毫秒` | 数字 | 是       | -      | 睡眠时间（毫秒） |
+
+**示例:**
+
+```javascript
+$打印信息日志("开始等待...");
+$延时(2000); // 等待2秒
+$打印信息日志("等待结束");
+```
+
+### $退出脚本
+
+退出应用。
+
+```typescript
+declare const $退出脚本: (退出所有线程?: 布尔值) => 无返回值;
+```
+
+**参数:**
+
+| 参数名         | 类型   | 是否必填 | 默认值 | 描述                                                             |
+| -------------- | ------ | -------- | ------ | ---------------------------------------------------------------- |
+| `退出所有线程` | 布尔值 | 否       | false  | 是否退出所有线程，默认 `false` 退出当前线程，`true` 退出所有线程 |
+
+**注意事项:**
+
+- 调用 `$退出脚本(true)` 会退出所有线程，包括主线程和子线程。
+- 调用 `$退出脚本(false)` 或不传参数，仅退出当前线程。如果是主线程调用会退出所有线程，子线程调用仅退出子线程。
+
+**示例:**
+
+```javascript
+$打印信息日志("应用即将退出");
+// 执行清理工作
+$退出脚本();
+```
+
+### $获取当前时间戳
+
+获取当前时间戳。
+
+```typescript
+declare function $获取当前时间戳(): 数字;
+```
+
+**返回值:**
+
+| 类型   | 描述               |
+| ------ | ------------------ |
+| `数字` | 当前时间戳（毫秒） |
+
+**示例:**
+
+```javascript
+const 开始时间 = $获取当前时间戳();
+// 执行一些操作
+$延时(1000);
+const 结束时间 = $获取当前时间戳();
+$打印信息日志(`操作耗时: ${结束时间 - 开始时间}ms`);
+```
+
+### $APP 切入前台
+
+将快点 JS 应用切换到前台。
+
+快点 Agent 模式下调用-> `$工具.APP切入前台()`
+
+HID 模式下调用-> `$HID.APP切入前台()`
+
+```typescript
+declare function $APP切入前台(): 无返回值;
+```
+
+**示例:**
+
+```javascript
+// 当需要用户注意时，将应用切换到前台
+$APP切入前台();
+$打印信息日志("应用已切换到前台");
+```
+
+### $设置停止回调
+
+设置停止回调函数（仅主线程调用）。
+
+```typescript
+declare const $设置停止回调: (回调: () => 无返回值) => 无返回值;
+```
+
+**参数:**
+
+| 参数名 | 类型           | 是否必填 | 默认值 | 描述         |
+| ------ | -------------- | -------- | ------ | ------------ |
+| `回调` | () => 无返回值 | 是       | -      | 停止回调函数 |
+
+**说明:**
+
+脚本执行完成或异常停止时调用，`$退出脚本()` 退出不会触发此回调。
+
+**示例:**
+
+```javascript
+$设置停止回调(() => {
+  $打印信息日志("脚本执行完成");
+  // 执行清理工作
+});
+```
+
+### $设置异常停止回调
+
+设置异常停止回调函数（仅主线程调用）。
+
+```typescript
+declare const $设置异常停止回调: (回调: () => 无返回值) => 无返回值;
+```
+
+**参数:**
+
+| 参数名 | 类型           | 是否必填 | 默认值 | 描述             |
+| ------ | -------------- | -------- | ------ | ---------------- |
+| `回调` | () => 无返回值 | 是       | -      | 异常停止回调函数 |
+
+**说明:**
+
+脚本执行异常停止时调用，可用于错误处理和恢复。
+
+**示例:**
+
+```javascript
+$设置异常停止回调(() => {
+  $打印错误日志("脚本执行异常");
+  // 可以选择重启脚本
+  $重启脚本(2000);
+});
+```
+
+### $重启脚本
+
+重启脚本。
+
+```typescript
+declare const $重启脚本: (延迟时间: 数字) => 无返回值;
+```
+
+**参数:**
+
+| 参数名     | 类型 | 是否必填 | 默认值 | 描述                                     |
+| ---------- | ---- | -------- | ------ | ---------------------------------------- |
+| `延迟时间` | 数字 | 是       | -      | 延迟时间（毫秒），建议不要低于 2000 毫秒 |
+
+**示例:**
+
+```javascript
+// 重启脚本，延迟2秒
+$重启脚本(2000);
+
+// 在异常回调中使用
+$设置异常停止回调(() => {
+  $打印错误日志("检测到异常，2秒后重启脚本");
+  $重启脚本(2000);
+});
+```
+
+### $加载Dex
+
+加载指定的 dex、apk 文件。
+
+```typescript
+declare const $加载Dex: (dexPath: 字符串) => 无返回值;
+```
+
+**参数:**
+
+| 参数名    | 类型   | 是否必填 | 默认值 | 描述              |
+| --------- | ------ | -------- | ------ | ----------------- |
+| `dexPath` | 字符串 | 是       | -      | dex、apk 文件路径 |
+
+**示例:**
+
+```javascript
+// 加载指定的 Dex 文件
+const 是否加载成功 = $加载Dex("/sdcard/script.dex");
+if (是否加载成功) {
+  $打印信息日志("Dex 文件加载成功");
+} else {
+  $打印错误日志("Dex 文件加载失败");
+}
+```
+
+### $获取上下文
+
+获取安卓上下文 (仅安卓可用)。
+
+```typescript
+declare function $获取上下文(): 任意类型;
+```
+
+**返回值:**
+
+| 类型         | 描述           |
+| ------------ | -------------- |
+| `上下文对象` | 当前上下文对象 |
+
+**示例:**
+
+```javascript
+const 上下文 = $获取上下文();
+$打印调试日志(`当前上下文: ${JSON.stringify(上下文)}`);
+```
+
+### $导入类
+
+导入指定的类。
+
+```typescript
+declare function $导入类(类名: 字符串): 任意类型;
+```
+
+**参数:**
+
+| 参数名 | 类型   | 是否必填 | 默认值 | 描述         |
+| ------ | ------ | -------- | ------ | ------------ |
+| `类名` | 字符串 | 是       | -      | 要导入的类名 |
+
+**返回值:**
+
+| 类型     | 描述         |
+| -------- | ------------ |
+| `类对象` | 导入的类对象 |
+
+**示例:**
+
+```javascript
+// 大部分情况下，不需要导入 Java 类，直接使用即可
+const B = new com.a.B();
+logi(`B 类的实例: ${B}`);
+
+// 只有在无法直接使用类时，才需要导入 Java 类
+const C = $导入类("xxx.a.C");
+const c = new C();
+logi(`创建了 C 类的实例: ${c}`);
+```
+
+## 全局日志函数
+
+全局日志函数是 `logger` 模块对应方法的便捷别名，可以直接调用而无需 `logger.` 前缀。
+
+### $打印调试日志
+
+输出调试级别的日志，等同于 `$日志.调试输出()`。
+
+```typescript
+function $打印调试日志(...日志内容: 数组<任意类型>): 无返回值;
+```
+
+**参数:**
+
+| 参数名        | 类型           | 是否必填 | 默认值 | 描述             |
+| ------------- | -------------- | -------- | ------ | ---------------- |
+| `...日志内容` | 数组<任意类型> | 是       | -      | 要输出的日志内容 |
+
+**用途:**
+
+- 详细的程序执行信息
+- 变量值和状态信息
+- 函数调用跟踪
+- 开发阶段的调试信息
+
+**示例:**
+
+```javascript
+$打印调试日志("程序开始执行");
+
+// 函数调用跟踪
+function processData(data) {
+  $打印调试日志(`processData 开始，参数: ${JSON.stringify(data)}`);
+  // 处理逻辑...
+  $打印调试日志("processData 完成");
+}
+```
+
+### $打印信息日志
+
+输出信息级别的日志，等同于 `$日志.信息输出()`。
+
+```typescript
+function $打印信息日志(...日志内容: 数组<任意类型>): 无返回值;
+```
+
+**参数:**
+
+| 参数名        | 类型           | 是否必填 | 默认值 | 描述             |
+| ------------- | -------------- | -------- | ------ | ---------------- |
+| `...日志内容` | 数组<任意类型> | 是       | -      | 要输出的日志内容 |
+
+**用途:**
+
+- 程序正常运行信息
+- 重要操作的确认
+- 状态变更通知
+- 一般性信息记录
+
+**示例:**
+
+```javascript
+$打印信息日志("应用程序启动成功");
+$打印信息日志(`处理了 ${count} 条记录`);
+```
+
+### $打印警告日志
+
+输出警告级别的日志，等同于 `$日志.警告输出()`。
+
+```typescript
+function $打印警告日志(...日志内容: 数组<任意类型>): 无返回值;
+```
+
+**参数:**
+
+| 参数名        | 类型           | 是否必填 | 默认值 | 描述             |
+| ------------- | -------------- | -------- | ------ | ---------------- |
+| `...日志内容` | 数组<任意类型> | 是       | -      | 要输出的日志内容 |
+
+**用途:**
+
+- 潜在的问题警告
+- 不推荐的操作提醒
+- 性能警告
+- 兼容性问题提示
+
+**示例:**
+
+```javascript
+$打印警告日志("电池电量低于 20%");
+$打印警告日志("网络连接不稳定");
+$打印警告日志("使用了已废弃的 API");
+$打印警告日志("内存使用率较高");
+```
+
+### $打印错误日志
+
+输出错误级别的日志，等同于 `$日志.错误输出()`。
+
+```typescript
+function $打印错误日志(...日志内容: 数组<任意类型>): 无返回值;
+```
+
+**参数:**
+
+| 参数名        | 类型           | 是否必填 | 默认值 | 描述             |
+| ------------- | -------------- | -------- | ------ | ---------------- |
+| `...日志内容` | 数组<任意类型> | 是       | -      | 要输出的日志内容 |
+
+**用途:**
+
+- 程序错误和异常
+- 操作失败记录
+- 系统错误报告
+- 致命问题记录
+
+**示例:**
+
+```javascript
+$打印错误日志("网络请求失败");
+$打印错误日志("文件读取错误");
+$打印错误日志("数据库连接失败");
+$打印错误日志(`未知错误: ${error.message}`);
+
+// 异常处理
+try {
+  // 可能出错的操作
+  const result = riskyOperation();
+} catch (error) {
+  $打印错误日志(`操作失败: ${error.message}`);
+}
+```
+
+**注意事项:**
+
+- 这些全局日志函数的行为完全等同于对应的 `$日志` 模块方法
+- 日志级别设置通过 `$日志.设置日志级别()` 统一控制
+- 文件输出设置通过 `$日志.设置日志保存到文件()` 统一控制
+- 推荐在简单脚本中使用全局函数，在复杂项目中使用 `$日志` 模块方法以保持代码清晰性