ms-vite-plugin 1.1.2 → 1.1.3

package/docs/apipython/file.md

@@ -0,0 +1,476 @@
+# 文件模块 (File)
+
+文件模块提供完整的文件与目录操作功能，包括目录管理、文件基础操作、文件读写、按行操作、文件信息等。
+
+## 功能概览
+
+- 目录管理：获取应用目录、创建目录、列出目录内容
+- 文件操作：创建、删除、复制、检查存在性
+- 文件读写：支持整文件与按行读写
+- 文件信息：获取文件 MD5 值
+
+## 注意事项
+
+- **文件路径**: 所有文件路径均为绝对路径，不支持相对路径。
+- **目录查看**: `documents`目录可以通过`文件`->`我的iPhone`->`快点JS`查看，其他目录不可直接查看
+
+## API 参考
+
+### 目录操作
+
+#### getInternalDir - 获取应用内部目录路径
+
+```python
+from typing import Literal
+
+def getInternalDir(type: Literal["documents","library","temp","libraryCaches"]) -> str
+```
+
+**参数:**
+
+| 参数名 | 类型   | 是否必填 | 描述                                                                                  |
+| ------ | ------ | -------- | ------------------------------------------------------------------------------------- |
+| `type` | string | 是       | 目录类型：`"documents"` 文档、`"library"` 库、`"temp"` 临时、`"libraryCaches"` 库缓存 |
+
+**返回值:**
+
+| 类型  | 描述             |
+| ----- | ---------------- |
+| `str` | 应用内部目录路径 |
+
+**示例:**
+
+```python
+from kuaijs import file
+documents_dir = file.getInternalDir("documents")
+temp_dir = file.getInternalDir("temp")
+print(documents_dir)
+print(temp_dir)
+```
+
+#### getDataDir - 获取应用数据目录路径
+
+```python
+def getDataDir() -> str
+```
+
+**返回值:**
+
+| 类型  | 描述             |
+| ----- | ---------------- |
+| `str` | 应用数据目录路径 |
+
+**示例:**
+
+```python
+from kuaijs import file
+data_dir = file.getDataDir()
+print(data_dir)
+```
+
+#### getDataFile - 获取应用数据文件的完整路径
+
+```python
+def getDataFile(file: str) -> str
+```
+
+**参数:**
+
+| 参数名 | 类型 | 是否必填 | 描述         |
+| ------ | ---- | -------- | ------------ |
+| `file` | str  | 是       | 文件名或路径 |
+
+**返回值:**
+
+| 类型  | 描述         |
+| ----- | ------------ |
+| `str` | 文件完整路径 |
+
+**示例:**
+
+```python
+from kuaijs import file
+config_path = file.getDataFile("config.json")
+print(config_path)
+```
+
+#### mkdirs - 创建目录（支持递归创建）
+
+```python
+def mkdirs(path: str) -> bool
+```
+
+**参数:**
+
+| 参数名 | 类型 | 是否必填 | 描述     |
+| ------ | ---- | -------- | -------- |
+| `path` | str  | 是       | 目录路径 |
+
+**返回值:**
+
+| 类型   | 描述         |
+| ------ | ------------ |
+| `bool` | 是否创建成功 |
+
+**示例:**
+
+```python
+from kuaijs import file
+ok = file.mkdirs("/path/to/nested/directory")
+print(ok)
+```
+
+#### listDir - 列出目录下的所有文件和子目录
+
+```python
+from typing import List
+
+def listDir(path: str, recursion: bool) -> List[str]
+```
+
+**参数:**
+
+| 参数名      | 类型 | 是否必填 | 描述                   |
+| ----------- | ---- | -------- | ---------------------- |
+| `path`      | str  | 是       | 目录路径               |
+| `recursion` | bool | 是       | 是否递归列出子目录内容 |
+
+**返回值:**
+
+| 类型        | 描述               |
+| ----------- | ------------------ |
+| `List[str]` | 文件和目录路径数组 |
+
+**示例:**
+
+```python
+from kuaijs import file
+files = file.listDir("/path/to/directory", False)
+all_files = file.listDir("/path/to/directory", True)
+print(files)
+print(all_files)
+```
+
+### 文件基础操作
+
+#### create - 创建新文件
+
+```python
+def create(path: str) -> bool
+```
+
+**参数:**
+
+| 参数名 | 类型 | 是否必填 | 描述     |
+| ------ | ---- | -------- | -------- |
+| `path` | str  | 是       | 文件路径 |
+
+**返回值:**
+
+| 类型   | 描述         |
+| ------ | ------------ |
+| `bool` | 是否创建成功 |
+
+**示例:**
+
+```python
+from kuaijs import file
+created = file.create("/path/to/newfile.txt")
+print(created)
+```
+
+#### exists - 检查文件或目录是否存在
+
+```python
+def exists(path: str) -> bool
+```
+
+**参数:**
+
+| 参数名 | 类型 | 是否必填 | 描述           |
+| ------ | ---- | -------- | -------------- |
+| `path` | str  | 是       | 文件或目录路径 |
+
+**返回值:**
+
+| 类型   | 描述     |
+| ------ | -------- |
+| `bool` | 是否存在 |
+
+**示例:**
+
+```python
+from kuaijs import file
+print(file.exists("/path/to/file.txt"))
+```
+
+#### copy - 复制文件
+
+```python
+def copy(src: str, dest: str) -> bool
+```
+
+**参数:**
+
+| 参数名 | 类型 | 是否必填 | 描述         |
+| ------ | ---- | -------- | ------------ |
+| `src`  | str  | 是       | 源文件路径   |
+| `dest` | str  | 是       | 目标文件路径 |
+
+**返回值:**
+
+| 类型   | 描述         |
+| ------ | ------------ |
+| `bool` | 是否复制成功 |
+
+**示例:**
+
+```python
+from kuaijs import file
+copied = file.copy("/path/to/source.txt", "/path/to/destination.txt")
+print(copied)
+```
+
+#### deleteAllFile - 删除文件或目录
+
+```python
+def deleteAllFile(path: str) -> bool
+```
+
+**参数:**
+
+| 参数名 | 类型 | 是否必填 | 描述           |
+| ------ | ---- | -------- | -------------- |
+| `path` | str  | 是       | 文件或目录路径 |
+
+**返回值:**
+
+| 类型   | 描述         |
+| ------ | ------------ |
+| `bool` | 是否删除成功 |
+
+**示例:**
+
+```python
+from kuaijs import file
+deleted = file.deleteAllFile("/path/to/file.txt")
+print(deleted)
+```
+
+### 文件读写操作
+
+#### readFile - 读取整个文件内容
+
+```python
+def readFile(path: str) -> Optional[str]
+```
+
+**参数：**
+
+| 参数名 | 类型 | 是否必填 | 描述     |
+| ------ | ---- | -------- | -------- |
+| `path` | str  | 是       | 文件路径 |
+
+**返回值：**
+
+| 类型            | 描述                            |
+| --------------- | ------------------------------- |
+| `str   \| None` | 文件内容；失败或不存在返回 None |
+
+**示例:**
+
+```python
+from kuaijs import file
+p = file.getDataFile("read.txt")
+file.writeFile(p, "line1\nline2")
+print(file.readFile(p))
+```
+
+#### readResFile - 读取 res 目录中的文本文件内容
+
+注意：该函数仅适用于读取脚本 res 目录中的文本文件；res 目录文件只读，不能修改。
+
+```python
+def readResFile(fileName: str) -> Optional[str]
+```
+
+**参数:**
+
+| 参数名     | 类型 | 是否必填 | 描述         |
+| ---------- | ---- | -------- | ------------ |
+| `fileName` | str  | 是       | res 目录路径 |
+
+**返回值:**
+
+| 类型          | 描述                    |
+| ------------- | ----------------------- |
+| `str \| None` | 文件内容；失败返回 None |
+
+**示例:**
+
+```python
+from kuaijs import file
+config = file.readResFile("config.json")
+if config:
+    print(config)
+```
+
+#### writeFile - 写入文件内容（覆盖）
+
+```python
+def writeFile(path: str, data: str) -> bool
+```
+
+**参数:**
+
+| 参数名 | 类型 | 是否必填 | 描述         |
+| ------ | ---- | -------- | ------------ |
+| `path` | str  | 是       | 文件路径     |
+| `data` | str  | 是       | 要写入的内容 |
+
+**返回值:**
+
+| 类型   | 描述         |
+| ------ | ------------ |
+| `bool` | 是否写入成功 |
+
+#### appendLine - 向文件追加内容
+
+```python
+def appendLine(path: str, content: str) -> bool:
+```
+
+**参数:**
+
+| 参数名    | 类型 | 是否必填 | 描述         |
+| --------- | ---- | -------- | ------------ |
+| `path`    | str  | 是       | 文件路径     |
+| `content` | str  | 是       | 要追加的内容 |
+
+**返回值:**
+
+| 类型   | 描述         |
+| ------ | ------------ |
+| `bool` | 是否追加成功 |
+
+**示例:**
+
+```python
+from kuaijs import file
+appended = file.appendLine("/path/to/log.txt", "新的日志条目")
+print(appended)
+```
+
+### 按行操作
+
+#### readLine - 读取文件指定行的内容
+
+```python
+def readLine(path: str, lineNo: int) -> Optional[str]
+```
+
+**参数:**
+
+| 参数名   | 类型 | 是否必填 | 描述              |
+| -------- | ---- | -------- | ----------------- |
+| `path`   | str  | 是       | 文件路径          |
+| `lineNo` | int  | 是       | 行号（从 1 开始） |
+
+**返回值:**
+
+| 类型          | 描述                          |
+| ------------- | ----------------------------- |
+| `str \| None` | 行内容；失败或不存在返回 None |
+
+**示例:**
+
+```python
+from kuaijs import file
+first_line = file.readLine("/path/to/file.txt", 1)
+print(first_line)
+```
+
+#### readAllLines - 读取文件所有行内容
+
+```python
+from typing import List, Optional
+
+def readAllLines(path: str) -> Optional[List[str]]
+```
+
+**参数：**
+
+| 参数名 | 类型 | 是否必填 | 描述     |
+| ------ | ---- | -------- | -------- |
+| `path` | str  | 是       | 文件路径 |
+
+**返回值：**
+
+| 类型                | 描述                          |
+| ------------------- | ----------------------------- |
+| `List[str] \| None` | 所有行内容数组；失败返回 None |
+
+**示例:**
+
+```python
+from kuaijs import file
+lines = file.readAllLines("/path/to/file.txt")
+print(lines)
+```
+
+#### deleteLine - 删除文件中符合条件的行
+
+```python
+def deleteLine(path: str, line: int, contains: Optional[str]) -> bool
+```
+
+**参数：**
+
+| 参数名     | 类型        | 是否必填 | 描述                                |
+| ---------- | ----------- | -------- | ----------------------------------- |
+| `path`     | str         | 是       | 文件路径                            |
+| `line`     | int         | 是       | 行号（-1 表示不按行号删除）         |
+| `contains` | str \| None | 否       | 包含的内容（None 表示不按内容删除） |
+
+**返回值：**
+
+| 类型   | 描述         |
+| ------ | ------------ |
+| `bool` | 是否删除成功 |
+
+**示例:**
+
+```python
+from kuaijs import file
+file.deleteLine("/path/to/file.txt", 3, None)
+file.deleteLine("/path/to/file.txt", -1, "error")
+file.deleteLine("/path/to/file.txt", 5, "debug")
+```
+
+### 文件信息
+
+#### fileMD5 - 获取文件的 MD5 哈希值
+
+```python
+def fileMD5(path: str) -> Optional[str]
+```
+
+**参数：**
+
+| 参数名 | 类型 | 是否必填 | 描述     |
+| ------ | ---- | -------- | -------- |
+| `path` | str  | 是       | 文件路径 |
+
+**返回值：**
+
+| 类型          | 描述                       |
+| ------------- | -------------------------- |
+| `str \| None` | 文件 MD5 值；失败返回 None |
+
+**示例:**
+
+```python
+from kuaijs import file
+md5 = file.fileMD5("/path/to/file.txt")
+print(md5)
+```

package/docs/apipython/g.md

@@ -0,0 +1,154 @@
+# 全局模块 (Global)
+
+- 提供应用信息常量与前台切换能力
+
+## 功能概览
+
+- 应用信息常量：版本号/构建号/名称/包名
+- 前台切换：将宿主应用切到前台
+
+## 常量
+
+- `runMode: str` 运行模式，"agent" 或 "hid"
+- `isSupportBuiltAgent: bool` 是否使用内置Agent
+- `platform: str` 平台信息（"ios" 或 "android"）
+- `appVersion: str` 应用版本号
+- `appBuildNumber: int` 应用构建号
+- `appName: str` 应用名称
+- `appBundleId: str` 应用包名
+- `isDebug: bool` 是否调试模式（True/False）
+- `packageJson: dict` 应用的 `package.json` 内容（对象）
+
+## 示例
+
+```python
+from kuaijs import g
+print(g.appName, g.appVersion)
+
+# 读取 package.json 内容
+pkg = g.packageJson
+print(pkg.get("appVersion"))
+
+# 调试模式判断
+print("Debug Mode" if g.isDebug else "Release Mode")
+```
+
+## API 参考
+
+### 方法
+
+#### `takeMeToFront` - 将宿主应用切入前台
+
+```python
+def takeMeToFront() -> bool
+```
+
+**返回值:**
+
+- `bool` 是否成功切入前台
+
+**示例:**
+
+```python
+from kuaijs import g
+g.takeMeToFront()
+```
+
+#### `restartScript` - 重启脚本
+
+```python
+def restartScript(delay_ms: int = 2000) -> None
+```
+
+**参数:**
+| 参数 | 类型 | 必需 | 默认值 | 描述 |
+| ---- | ---- | ---- | ------ | ---- |
+| `delay_ms` | int | 否 | 2000 | 重启延迟毫秒数（至少 2000ms） |
+
+**示例:**
+
+```python
+from kuaijs import g
+g.restartScript()
+```
+
+#### `loadDex` - 加载指定的 dex、apk 文件
+
+**注意:**
+
+- 仅在 Android 平台可用
+
+```python
+def loadDex(dexPath: str) -> bool
+```
+
+**参数:**
+| 参数 | 类型 | 必需 | 默认值 | 描述 |
+| ---- | ---- | ---- | ------ | ---- |
+| `dexPath` | str | 是 | - | Dex 或 APK 文件的路径 |
+
+**返回值:**
+
+**返回值:**
+
+| 类型   | 描述                  |
+| ------ | --------------------- |
+| `bool` | 是否成功加载 Dex 文件 |
+
+**示例:**
+
+```python
+from kuaijs import g
+g.loadDex("/sdcard/classes.dex")
+```
+
+#### `getContext` - 获取安卓上下文
+
+**注意:**
+
+- 仅在 Android 平台可用
+
+```python
+def getContext() -> dict
+```
+
+**返回值:**
+
+- `dict` 当前安卓上下文对象
+
+**示例:**
+
+```python
+from kuaijs import g
+ctx = g.getContext()
+print(ctx)
+```
+
+#### `importClass` - 导入类对象
+
+**注意:**
+
+- 仅在 Android 平台可用
+
+```python
+def importClass(className: str) -> any
+```
+
+**参数:**
+
+| 参数        | 类型 | 必需 | 默认值 | 描述                   |
+| ----------- | ---- | ---- | ------ | ---------------------- |
+| `className` | str  | 是   | -      | 类名（包含完整包路径） |
+
+**返回值:**
+
+| 类型  | 描述   |
+| ----- | ------ |
+| `any` | 类对象 |
+
+**示例:**
+
+```python
+from kuaijs import g
+Activity = g.importClass("android.app.Activity")
+```