ms-vite-plugin 1.1.1 → 1.1.3

package/docs/api/file.md

@@ -0,0 +1,516 @@
+# 文件模块 (File)
+
+文件模块提供了完整的文件和目录操作功能，包括文件的创建、读写、删除、复制等操作，以及目录的管理和遍历功能。
+
+## 功能概览
+
+- **目录管理**: 获取应用目录、创建目录、列出目录内容
+- **文件操作**: 创建、删除、复制、检查文件存在性
+- **文件读写**: 支持整个文件和按行的读写操作
+- **文件信息**: 获取文件 MD5 值等信息
+
+## 注意事项
+
+- **文件路径**: 所有文件路径均为绝对路径，不支持相对路径。
+- **目录查看**: `documents`目录可以通过`文件`->`我的iPhone`->`快点JS`查看，其他目录不可直接查看
+
+## API 参考
+
+### 目录操作
+
+#### getInternalDir - 获取应用内部目录路径。
+
+```typescript
+function getInternalDir(
+  type: "documents" | "library" | "temp" | "libraryCaches"
+): string;
+```
+
+**参数:**
+
+| 参数名 | 类型   | 是否必填 | 默认值 | 描述                                                                                                                          |
+| ------ | ------ | -------- | ------ | ----------------------------------------------------------------------------------------------------------------------------- |
+| `type` | string | 是       | -      | 目录类型 <br>-`"documents"` - 文档目录 <br>-`"library"` - 库目录 <br>-`"temp"` - 临时目录 <br>-`"libraryCaches"` - 库缓存目录 |
+
+**返回值:**
+
+| 类型     | 描述             |
+| -------- | ---------------- |
+| `string` | 应用内部目录路径 |
+
+**示例:**
+
+```javascript
+const documentsDir = file.getInternalDir("documents");
+const tempDir = file.getInternalDir("temp");
+logi(`文档目录: ${documentsDir}`);
+logi(`临时目录: ${tempDir}`);
+```
+
+#### getDataDir - 获取应用数据目录路径。
+
+```typescript
+function getDataDir(): string;
+```
+
+**返回值:**
+
+| 类型     | 描述             |
+| -------- | ---------------- |
+| `string` | 应用数据目录路径 |
+
+**示例:**
+
+```javascript
+const dataDir = file.getDataDir();
+logi(`数据目录: ${dataDir}`);
+```
+
+#### getDataFile - 获取应用数据文件的完整路径。
+
+```typescript
+function getDataFile(file: string): string;
+```
+
+**参数:**
+
+| 参数名 | 类型   | 是否必填 | 默认值 | 描述         |
+| ------ | ------ | -------- | ------ | ------------ |
+| `file` | string | 是       | -      | 文件名或路径 |
+
+**返回值:**
+
+| 类型     | 描述         |
+| -------- | ------------ |
+| `string` | 文件完整路径 |
+
+**示例:**
+
+```javascript
+const configPath = file.getDataFile("config.json");
+logi(`配置文件路径: ${configPath}`);
+```
+
+#### mkdirs - 创建目录（支持递归创建）。
+
+```typescript
+function mkdirs(path: string): boolean;
+```
+
+**参数:**
+
+| 参数名 | 类型   | 是否必填 | 默认值 | 描述     |
+| ------ | ------ | -------- | ------ | -------- |
+| `path` | string | 是       | -      | 目录路径 |
+
+**返回值:**
+
+| 类型      | 描述         |
+| --------- | ------------ |
+| `boolean` | 是否创建成功 |
+
+**示例:**
+
+```javascript
+const success = file.mkdirs("/path/to/nested/directory");
+if (success) {
+  logi("目录创建成功");
+}
+```
+
+#### listDir - 列出目录下的所有文件和子目录。
+
+```typescript
+function listDir(path: string, recursion: boolean): string[];
+```
+
+**参数:**
+
+| 参数名      | 类型    | 是否必填 | 默认值 | 描述                   |
+| ----------- | ------- | -------- | ------ | ---------------------- |
+| `path`      | string  | 是       | -      | 目录路径               |
+| `recursion` | boolean | 是       | -      | 是否递归列出子目录内容 |
+
+**返回值:**
+
+| 类型       | 描述               |
+| ---------- | ------------------ |
+| `string[]` | 文件和目录路径数组 |
+
+**示例:**
+
+```javascript
+// 列出目录内容（不递归）
+const files = file.listDir("/path/to/directory", false);
+logi(`目录内容: ${JSON.stringify(files)}`);
+
+// 递归列出所有内容
+const allFiles = file.listDir("/path/to/directory", true);
+logi(`所有文件: ${JSON.stringify(allFiles)}`);
+```
+
+### 文件基础操作
+
+#### create - 创建新文件。
+
+```typescript
+function create(path: string): boolean;
+```
+
+**参数:**
+
+| 参数名 | 类型   | 是否必填 | 默认值 | 描述     |
+| ------ | ------ | -------- | ------ | -------- |
+| `path` | string | 是       | -      | 文件路径 |
+
+**返回值:**
+
+| 类型      | 描述         |
+| --------- | ------------ |
+| `boolean` | 是否创建成功 |
+
+**示例:**
+
+```javascript
+const created = file.create("/path/to/newfile.txt");
+if (created) {
+  logi("文件创建成功");
+}
+```
+
+#### exists - 检查文件或目录是否存在。
+
+```typescript
+function exists(path: string): boolean;
+```
+
+**参数:**
+
+| 参数名 | 类型   | 是否必填 | 默认值 | 描述           |
+| ------ | ------ | -------- | ------ | -------------- |
+| `path` | string | 是       | -      | 文件或目录路径 |
+
+**返回值:**
+
+| 类型      | 描述     |
+| --------- | -------- |
+| `boolean` | 是否存在 |
+
+**示例:**
+
+```javascript
+if (file.exists("/path/to/file.txt")) {
+  logi("文件存在");
+} else {
+  logi("文件不存在");
+}
+```
+
+#### copy - 复制文件。
+
+```typescript
+function copy(src: string, dest: string): boolean;
+```
+
+**参数:**
+
+| 参数名 | 类型   | 是否必填 | 默认值 | 描述         |
+| ------ | ------ | -------- | ------ | ------------ |
+| `src`  | string | 是       | -      | 源文件路径   |
+| `dest` | string | 是       | -      | 目标文件路径 |
+
+**返回值:**
+
+| 类型      | 描述         |
+| --------- | ------------ |
+| `boolean` | 是否复制成功 |
+
+**示例:**
+
+```javascript
+const copied = file.copy("/path/to/source.txt", "/path/to/destination.txt");
+if (copied) {
+  logi("文件复制成功");
+}
+```
+
+#### deleteAllFile - 删除文件或目录。
+
+```typescript
+function deleteAllFile(path: string): boolean;
+```
+
+**参数:**
+
+| 参数名 | 类型   | 是否必填 | 默认值 | 描述           |
+| ------ | ------ | -------- | ------ | -------------- |
+| `path` | string | 是       | -      | 文件或目录路径 |
+
+**返回值:**
+
+| 类型      | 描述         |
+| --------- | ------------ |
+| `boolean` | 是否删除成功 |
+
+**示例:**
+
+```javascript
+const deleted = file.deleteAllFile("/path/to/file.txt");
+if (deleted) {
+  logi("文件删除成功");
+}
+```
+
+### 文件读写操作
+
+#### readFile - 读取整个文件内容。
+
+```typescript
+function readFile(path: string): string | null;
+```
+
+**参数:**
+
+| 参数名 | 类型   | 是否必填 | 默认值 | 描述     |
+| ------ | ------ | -------- | ------ | -------- |
+| `path` | string | 是       | -      | 文件路径 |
+
+**返回值:**
+
+| 类型             | 描述                            |
+| ---------------- | ------------------------------- |
+| `string \| null` | 文件内容；失败或不存在返回 null |
+
+**示例:**
+
+```javascript
+const content = file.readFile("/path/to/file.txt");
+if (content !== null) {
+  logi(`文件内容: ${content}`);
+} else {
+  logw("文件不存在或读取失败");
+}
+```
+
+#### readResFile -读取`res`目录中的文本文件内容。
+
+**注意事项:**
+
+- 该函数仅适用于读取脚本 res 目录中的文本文件。
+- res 目录文件只读，不能修改。
+
+```typescript
+function readResFile(fileName: string): string | null;
+```
+
+**参数:**
+
+| 参数名     | 类型   | 是否必填 | 默认值 | 描述         |
+| ---------- | ------ | -------- | ------ | ------------ |
+| `fileName` | string | 是       | -      | res 目录路径 |
+
+**返回值:**
+
+| 类型           | 描述                                    |
+| -------------- | --------------------------------------- |
+| `string\|null` | 文件内容 文件不存在或读取失败 返回 null |
+
+**示例:**
+
+```javascript
+// 读取配置文件
+const config = file.readResFile("config.json");
+if (config) {
+  const configObj = JSON.parse(config);
+  logi(`配置加载成功: ${JSON.stringify(configObj)}`);
+} else {
+  logi("配置文件不存在或读取失败");
+}
+```
+
+#### writeFile - 写入文件内容（覆盖原有内容）。
+
+```typescript
+function writeFile(path: string, content: string): boolean;
+```
+
+**参数:**
+
+| 参数名    | 类型   | 是否必填 | 默认值 | 描述         |
+| --------- | ------ | -------- | ------ | ------------ |
+| `path`    | string | 是       | -      | 文件路径     |
+| `content` | string | 是       | -      | 要写入的内容 |
+
+**返回值:**
+
+| 类型      | 描述         |
+| --------- | ------------ |
+| `boolean` | 是否写入成功 |
+
+**示例:**
+
+```javascript
+const success = file.writeFile("/path/to/file.txt", "Hello, World!");
+if (success) {
+  logi("文件写入成功");
+}
+```
+
+#### appendLine - 向文件追加内容。
+
+```typescript
+function appendLine(path: string, content: string): boolean;
+```
+
+**参数:**
+
+| 参数名    | 类型   | 是否必填 | 默认值 | 描述         |
+| --------- | ------ | -------- | ------ | ------------ |
+| `path`    | string | 是       | -      | 文件路径     |
+| `content` | string | 是       | -      | 要追加的内容 |
+
+**返回值:**
+
+| 类型      | 描述         |
+| --------- | ------------ |
+| `boolean` | 是否追加成功 |
+
+**示例:**
+
+```javascript
+const appended = file.appendLine("/path/to/log.txt", "新的日志条目");
+if (appended) {
+  logi("内容追加成功");
+}
+```
+
+### 按行操作
+
+#### readLine - 读取文件指定行的内容。
+
+```typescript
+function readLine(path: string, lineNo: number): string | null;
+```
+
+**参数:**
+
+| 参数名   | 类型   | 是否必填 | 默认值 | 描述              |
+| -------- | ------ | -------- | ------ | ----------------- |
+| `path`   | string | 是       | -      | 文件路径          |
+| `lineNo` | number | 是       | -      | 行号（从 1 开始） |
+
+**返回值:**
+
+| 类型             | 描述                          |
+| ---------------- | ----------------------------- |
+| `string \| null` | 行内容；失败或不存在返回 null |
+
+**示例:**
+
+```javascript
+const firstLine = file.readLine("/path/to/file.txt", 1);
+if (firstLine !== null) {
+  logi(`第一行内容: ${firstLine}`);
+} else {
+  logw("读取失败或行不存在");
+}
+```
+
+#### readAllLines - 读取文件所有行内容。
+
+```typescript
+function readAllLines(path: string): string[] | null;
+```
+
+**参数:**
+
+| 参数名 | 类型   | 是否必填 | 默认值 | 描述     |
+| ------ | ------ | -------- | ------ | -------- |
+| `path` | string | 是       | -      | 文件路径 |
+
+**返回值:**
+
+| 类型      | 描述  |
+| --------- | ----- | ----------------------------- |
+| `string[] | null` | 所有行内容数组；失败返回 null |
+
+**示例:**
+
+```javascript
+const lines = file.readAllLines("/path/to/file.txt");
+if (lines !== null) {
+  lines.forEach((line, index) => {
+    logi(`第${index + 1}行: ${line}`);
+  });
+} else {
+  logw("读取所有行失败或文件不存在");
+}
+```
+
+#### deleteLine - 删除文件中符合条件的行。
+
+```typescript
+function deleteLine(
+  path: string,
+  line: number,
+  contains: string | null
+): boolean;
+```
+
+**参数:**
+
+| 参数名     | 类型   | 是否必填 | 默认值 | 描述                                |
+| ---------- | ------ | -------- | ------ | ----------------------------------- |
+| `path`     | string | 是       | -      | 文件路径                            |
+| `line`     | number | 是       | -      | 行号（-1 表示不按行号删除）         |
+| `contains` | string | 否       | null   | 包含的内容（null 表示不按内容删除） |
+
+**返回值:**
+
+| 类型      | 描述         |
+| --------- | ------------ |
+| `boolean` | 是否删除成功 |
+
+**示例:**
+
+```javascript
+// 删除第3行
+file.deleteLine("/path/to/file.txt", 3, null);
+
+// 删除包含"error"的行
+file.deleteLine("/path/to/file.txt", -1, "error");
+
+// 删除第5行且包含"debug"的行
+file.deleteLine("/path/to/file.txt", 5, "debug");
+```
+
+### 文件信息
+
+#### fileMD5 - 获取文件的 MD5 哈希值。
+
+```typescript
+function fileMD5(path: string): string | null;
+```
+
+**参数:**
+
+| 参数名 | 类型   | 是否必填 | 默认值 | 描述     |
+| ------ | ------ | -------- | ------ | -------- |
+| `path` | string | 是       | -      | 文件路径 |
+
+**返回值:**
+
+| 类型             | 描述                      |
+| ---------------- | ------------------------- |
+| `string \| null` | 文件 MD5 值 失败返回 null |
+
+**示例:**
+
+```javascript
+const md5 = file.fileMD5("/path/to/file.txt");
+if (md5) {
+  logi(`文件MD5: ${md5}`);
+} else {
+  logi("获取MD5失败");
+}
+```