ms-vite-plugin 1.1.2 → 1.1.3

package/docs/api/global.md

@@ -0,0 +1,617 @@
+# 全局定义 (Global)
+
+全局定义模块提供了应用运行时的全局常量和函数，包括应用信息、调试状态、线程控制等核心功能。
+
+**全局模块无调用前缀，直接使用即可。**
+
+## 功能概览
+
+- **应用信息**: 获取应用版本、名称、包信息等
+- **运行状态**: 检查调试模式、退出状态等
+- **线程控制**: 线程睡眠、应用退出等
+- **脚本生命周期**: 设置停止回调、异常回调、重启脚本等
+- **时间工具**: 获取时间戳
+- **应用控制**: 切换应用到前台
+
+## 全局常量
+
+### 运行模式
+
+#### **runMode**
+
+用户设置选择的运行模式，"agent" 或 "hid"。
+
+```typescript
+declare const __runMode__: "agent" | "hid";
+```
+
+**示例:**
+
+```javascript
+logi(`运行模式: ${__runMode__}`);
+```
+
+### 是否使用内置Agent
+
+#### **isSupportBuiltAgent**
+
+是否使用内置 Agent。
+
+```typescript
+declare const __isSupportBuiltAgent__: boolean;
+```
+
+**示例:**
+
+```javascript
+logi(`是否使用内置Agent: ${__isSupportBuiltAgent__}`);
+```
+
+### 调试和状态
+
+#### **debug**
+
+当前是否为调试模式。
+
+```typescript
+declare const __debug__: boolean;
+```
+
+**示例:**
+
+```javascript
+logi(`调试模式: ${__debug__}`);
+```
+
+### 应用信息
+
+#### **platform**
+
+平台信息，标识当前应用运行的平台，例如 "ios"、"android" 等。
+
+```typescript
+declare const __platform__: "ios" | "android";
+```
+
+**示例:**
+
+```javascript
+logi(`平台: ${__platform__}`);
+```
+
+#### **appVersion**
+
+应用版本号，注意这是快点 JS 应用的版本号，不是脚本的版本号。
+
+```typescript
+declare const __appVersion__: string;
+```
+
+**示例:**
+
+```javascript
+logi(`应用版本: ${__appVersion__}`);
+```
+
+#### **appBuildNumber**
+
+应用构建号，注意这是快点 JS 应用的构建号，不是脚本的构建号。
+
+```typescript
+declare const __appBuildNumber__: number;
+```
+
+**示例:**
+
+```javascript
+logi(`构建号: ${__appBuildNumber__}`);
+
+// 要求最低版本号和构建号示例
+const requiredVersion = "1.1.0";
+const requiredBuildNumber = 2;
+
+function ensureAppVersion(requiredVersion, requiredBuildNumber) {
+  function compareVersion(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 versionOk = compareVersion(__appVersion__, requiredVersion) >= 0;
+  const buildOk = __appBuildNumber__ >= requiredBuildNumber;
+
+  if (!versionOk || !buildOk) {
+    ui.alert("版本号提示", "应用版本过低，请升级到最新版本");
+    exit();
+  }
+}
+
+ensureAppVersion(requiredVersion, requiredBuildNumber);
+```
+
+#### **appName**
+
+应用名称，注意这是快点 JS 应用的名称，不是脚本的名称。
+
+```typescript
+declare const __appName__: string;
+```
+
+**示例:**
+
+```javascript
+logi(`应用名称: ${__appName__}`);
+```
+
+#### **bundleId**
+
+应用的 Bundle ID，注意这是快点 JS 应用的 Bundle ID，不是脚本的 Bundle ID。
+
+```typescript
+declare const __bundleId__: string;
+```
+
+**示例:**
+
+```javascript
+logi(`Bundle ID: ${__bundleId__}`);
+```
+
+### 线程信息
+
+#### **threadName**
+
+当前线程名称。
+
+```typescript
+declare const __threadName__: string;
+```
+
+**示例:**
+
+```javascript
+logi(`当前线程: ${__threadName__}`);
+```
+
+### 包（脚本）信息
+
+#### **package**
+
+应用包（脚本）的配置信息，package.json 的内容
+
+```typescript
+declare const __package__: {
+  name: string;
+  appVersion: string;
+  appId: string;
+  [key: string]: any;
+};
+```
+
+**属性:**
+
+- `name` - 脚本项目名称
+- `appVersion` - 脚本版本号
+- `appId` - 脚本 Id
+- `[key: string]: any` - 其他自定义属性
+
+**示例:**
+
+```javascript
+logi(`脚本项目名称: ${__package__.name}`);
+logi(`脚本版本号: ${__package__.appVersion}`);
+
+// 访问自定义属性
+if (__package__.author) {
+  logi(`作者: ${__package__.author}`);
+}
+```
+
+## 全局函数
+
+### sleep
+
+使当前线程睡眠指定的毫秒数。
+
+```typescript
+function sleep(ms: number): void;
+```
+
+**参数:**
+
+| 参数名 | 类型   | 是否必填 | 默认值 | 描述             |
+| ------ | ------ | -------- | ------ | ---------------- |
+| `ms`   | number | 是       | -      | 睡眠时间（毫秒） |
+
+**示例:**
+
+```javascript
+logi("开始等待...");
+sleep(2000); // 等待2秒
+logi("等待结束");
+```
+
+### exit
+
+退出应用。
+
+```typescript
+function exit(exitAll?: boolean): void;
+```
+
+**参数:**
+
+| 参数名    | 类型    | 是否必填 | 默认值 | 描述                                                             |
+| --------- | ------- | -------- | ------ | ---------------------------------------------------------------- |
+| `exitAll` | boolean | 否       | false  | 是否退出所有线程，默认 `false` 退出当前线程，`true` 退出所有线程 |
+
+**注意事项:**
+
+- 调用 `exit(true)` 会退出所有线程，包括主线程和子线程。
+- 调用 `exit(false)` 或不传参数，仅退出当前线程。如果是主线程调用会退出所有线程，子线程调用仅退出子线程。
+
+**示例:**
+
+```javascript
+logi("应用即将退出");
+// 执行清理工作
+exit();
+```
+
+### time
+
+获取当前时间戳。
+
+```typescript
+function time(): number;
+```
+
+**返回值:**
+
+| 类型     | 描述               |
+| -------- | ------------------ |
+| `number` | 当前时间戳（毫秒） |
+
+**示例:**
+
+```javascript
+const startTime = time();
+// 执行一些操作
+sleep(1000);
+const endTime = time();
+logi(`操作耗时: ${endTime - startTime}ms`);
+```
+
+### takeMeToFront
+
+将快点 JS 应用切换到前台。
+
+快点 Agent 模式下调用-> `utils.takeMeToFront()`
+
+HID 模式下调用-> `hid.takeMeToFront()`
+
+```typescript
+function takeMeToFront(): boolean;
+```
+
+**示例:**
+
+```javascript
+// 当需要用户注意时，将应用切换到前台
+takeMeToFront();
+logi("应用已切换到前台");
+```
+
+### setStopCallback
+
+设置停止回调函数（仅主线程调用）。
+
+```typescript
+function setStopCallback(callback: () => void): void;
+```
+
+**参数:**
+
+| 参数名     | 类型       | 是否必填 | 默认值 | 描述         |
+| ---------- | ---------- | -------- | ------ | ------------ |
+| `callback` | () => void | 是       | -      | 停止回调函数 |
+
+**说明:**
+
+脚本执行完成或异常停止时调用，`exit()` 退出不会触发此回调。
+
+**示例:**
+
+```javascript
+setStopCallback(() => {
+  logi("脚本执行完成");
+  // 执行清理工作
+});
+```
+
+### setExceptionCallback
+
+设置异常停止回调函数（仅主线程调用）。
+
+```typescript
+function setExceptionCallback(callback: () => void): void;
+```
+
+**参数:**
+
+| 参数名     | 类型       | 是否必填 | 默认值 | 描述             |
+| ---------- | ---------- | -------- | ------ | ---------------- |
+| `callback` | () => void | 是       | -      | 异常停止回调函数 |
+
+**说明:**
+
+脚本执行异常停止时调用，可用于错误处理和恢复。
+
+**示例:**
+
+```javascript
+setExceptionCallback(() => {
+  loge("脚本执行异常");
+  // 可以选择重启脚本
+  restartScript(2000);
+});
+```
+
+### restartScript
+
+重启脚本。
+
+```typescript
+function restartScript(delay: number): void;
+```
+
+**参数:**
+
+| 参数名  | 类型   | 是否必填 | 默认值 | 描述                                     |
+| ------- | ------ | -------- | ------ | ---------------------------------------- |
+| `delay` | number | 是       | -      | 延迟时间（毫秒），建议不要低于 2000 毫秒 |
+
+**示例:**
+
+```javascript
+// 重启脚本，延迟2秒
+restartScript(2000);
+
+// 在异常回调中使用
+setExceptionCallback(() => {
+  loge("检测到异常，2秒后重启脚本");
+  restartScript(2000);
+});
+```
+
+### loadDex
+
+加载 dex、apk 文件 (仅安卓可用)。
+
+```typescript
+function loadDex(path: string): boolean;
+```
+
+**参数:**
+
+| 参数名 | 类型   | 是否必填 | 默认值 | 描述              |
+| ------ | ------ | -------- | ------ | ----------------- |
+| `path` | string | 是       | -      | dex、apk 文件路径 |
+
+**返回值:**
+
+| 类型      | 描述         |
+| --------- | ------------ |
+| `boolean` | 是否加载成功 |
+
+**示例:**
+
+```javascript
+const isLoaded = loadDex("/sdcard/classes.dex");
+if (isLoaded) {
+  logi("dex 文件加载成功");
+} else {
+  loge("dex 文件加载失败");
+}
+```
+
+### getContext
+
+获取安卓上下文 (仅安卓可用)。
+
+```typescript
+function getContext(): any;
+```
+
+**返回值:**
+
+| 类型  | 描述           |
+| ----- | -------------- |
+| `any` | 当前安卓上下文 |
+
+**示例:**
+
+```javascript
+const context = getContext();
+logi(`当前安卓上下文: ${context}`);
+```
+
+### importClass
+
+导入 Java 类 (仅安卓可用)。
+
+```typescript
+function importClass(className: string): any;
+```
+
+**参数:**
+
+| 参数名      | 类型   | 是否必填 | 默认值 | 描述      |
+| ----------- | ------ | -------- | ------ | --------- |
+| `className` | string | 是       | -      | Java 类名 |
+
+**返回值:**
+
+| 类型  | 描述           |
+| ----- | -------------- |
+| `any` | 导入的 Java 类 |
+
+**示例:**
+
+```javascript
+// 大部分情况下，不需要导入 Java 类，直接使用即可
+const B = new com.a.B();
+logi(`B 类的实例: ${B}`);
+
+// 只有在无法直接使用类时，才需要导入 Java 类
+const C = importClass("xxx.a.C");
+const c = new C();
+logi(`创建了 C 类的实例: ${c}`);
+```
+
+## 全局日志函数
+
+全局日志函数是 `logger` 模块对应方法的便捷别名，可以直接调用而无需 `logger.` 前缀。
+
+### logd
+
+输出调试级别的日志，等同于 `logger.debug()`。
+
+```typescript
+function logd(...args: any[]): void;
+```
+
+**参数:**
+
+| 参数名    | 类型  | 是否必填 | 默认值 | 描述             |
+| --------- | ----- | -------- | ------ | ---------------- |
+| `...args` | any[] | 是       | -      | 要输出的日志内容 |
+
+**用途:**
+
+- 详细的程序执行信息
+- 变量值和状态信息
+- 函数调用跟踪
+- 开发阶段的调试信息
+
+**示例:**
+
+```javascript
+logd("程序开始执行");
+
+// 函数调用跟踪
+function processData(data) {
+  logd(`processData 开始，参数: ${JSON.stringify(data)}`);
+  // 处理逻辑...
+  logd("processData 完成");
+}
+```
+
+### logi
+
+输出信息级别的日志，等同于 `logger.info()`。
+
+```typescript
+function logi(...args: any[]): void;
+```
+
+**参数:**
+
+| 参数名    | 类型  | 是否必填 | 默认值 | 描述             |
+| --------- | ----- | -------- | ------ | ---------------- |
+| `...args` | any[] | 是       | -      | 要输出的日志内容 |
+
+**用途:**
+
+- 程序正常运行信息
+- 重要操作的确认
+- 状态变更通知
+- 一般性信息记录
+
+**示例:**
+
+```javascript
+logi("应用程序启动成功");
+logi(`处理了 ${count} 条记录`);
+```
+
+### logw
+
+输出警告级别的日志，等同于 `logger.warn()`。
+
+```typescript
+function logw(...args: any[]): void;
+```
+
+**参数:**
+
+| 参数名    | 类型  | 是否必填 | 默认值 | 描述             |
+| --------- | ----- | -------- | ------ | ---------------- |
+| `...args` | any[] | 是       | -      | 要输出的日志内容 |
+
+**用途:**
+
+- 潜在的问题警告
+- 不推荐的操作提醒
+- 性能警告
+- 兼容性问题提示
+
+**示例:**
+
+```javascript
+logw("电池电量低于 20%");
+logw("网络连接不稳定");
+logw("使用了已废弃的 API");
+logw("内存使用率较高");
+```
+
+### loge
+
+输出错误级别的日志，等同于 `logger.error()`。
+
+```typescript
+function loge(...args: any[]): void;
+```
+
+**参数:**
+
+| 参数名    | 类型  | 是否必填 | 默认值 | 描述             |
+| --------- | ----- | -------- | ------ | ---------------- |
+| `...args` | any[] | 是       | -      | 要输出的日志内容 |
+
+**用途:**
+
+- 程序错误和异常
+- 操作失败记录
+- 系统错误报告
+- 致命问题记录
+
+**示例:**
+
+```javascript
+loge("网络请求失败");
+loge("文件读取错误");
+loge("数据库连接失败");
+loge(`未知错误: ${error.message}`);
+
+// 异常处理
+try {
+  // 可能出错的操作
+  const result = riskyOperation();
+} catch (error) {
+  loge(`操作失败: ${error.message}`);
+}
+```
+
+**注意事项:**
+
+- 这些全局日志函数的行为完全等同于对应的 `logger` 模块方法
+- 日志级别设置通过 `logger.setLoggerLevel()` 统一控制
+- 文件输出设置通过 `logger.setLogToFile()` 统一控制
+- 推荐在简单脚本中使用全局函数，在复杂项目中使用 `logger` 模块方法以保持代码清晰性