ms-vite-plugin 1.1.2 → 1.1.3

package/docs/apicn/file.md

@@ -0,0 +1,511 @@
+# 文件模块 ($文件)
+
+文件模块提供了完整的文件和目录操作功能，包括文件的创建、读写、删除、复制等操作，以及目录的管理和遍历功能。
+
+## 功能概览
+
+- **目录管理**: 获取应用目录、创建目录、列出目录内容
+- **文件操作**: 创建、删除、复制、检查文件存在性
+- **文件读写**: 支持整个文件和按行的读写操作
+- **文件信息**: 获取文件 MD5 值等信息
+
+## 注意事项
+
+- **文件路径**: 所有文件路径均为绝对路径，不支持相对路径。
+- **目录查看**: `documents`目录可以通过`文件`->`我的iPhone`->`快点JS`查看，其他目录不可直接查看
+
+## API 参考
+
+### 目录操作
+
+#### 获取内部目录
+
+```typescript
+function 获取内部目录(
+  目录类型: "documents" | "library" | "temp" | "libraryCaches"
+): 字符串;
+```
+
+**参数:**
+
+| 参数名     | 类型   | 是否必填 | 默认值 | 描述                                                                                                                          |
+| ---------- | ------ | -------- | ------ | ----------------------------------------------------------------------------------------------------------------------------- |
+| `目录类型` | string | 是       | -      | 目录类型 <br>-`"documents"` - 文档目录 <br>-`"library"` - 库目录 <br>-`"temp"` - 临时目录 <br>-`"libraryCaches"` - 库缓存目录 |
+
+**返回值:**
+
+| 类型     | 描述             |
+| -------- | ---------------- |
+| `字符串` | 应用内部目录路径 |
+
+**示例:**
+
+```javascript
+const 文档目录 = $文件.获取内部目录("documents");
+const 临时目录 = $文件.获取内部目录("temp");
+$打印信息日志(`文档目录: ${文档目录}`);
+$打印信息日志(`临时目录: ${临时目录}`);
+```
+
+#### 获取数据目录
+
+```typescript
+function 获取数据目录(): 字符串;
+```
+
+**返回值:**
+
+| 类型     | 描述             |
+| -------- | ---------------- |
+| `字符串` | 应用数据目录路径 |
+
+**示例:**
+
+```javascript
+const 数据目录 = $文件.获取数据目录();
+$打印信息日志(`数据目录: ${数据目录}`);
+```
+
+#### 获取数据文件路径
+
+```typescript
+function 获取数据文件路径(文件名称: 字符串): 字符串;
+```
+
+**参数:**
+
+| 参数名     | 类型   | 是否必填 | 默认值 | 描述         |
+| ---------- | ------ | -------- | ------ | ------------ |
+| `文件名称` | 字符串 | 是       | -      | 文件名或路径 |
+
+**返回值:**
+
+| 类型     | 描述         |
+| -------- | ------------ |
+| `字符串` | 文件完整路径 |
+
+**示例:**
+
+```javascript
+const 配置文件路径 = $文件.获取数据文件路径("config.json");
+$打印信息日志(`配置文件路径: ${配置文件路径}`);
+```
+
+#### 创建目录 - 创建目录（支持递归创建）。
+
+```typescript
+function 创建目录(目录路径: 字符串): 布尔值;
+```
+
+**参数:**
+
+| 参数名     | 类型   | 是否必填 | 默认值 | 描述     |
+| ---------- | ------ | -------- | ------ | -------- |
+| `目录路径` | 字符串 | 是       | -      | 目录路径 |
+
+**返回值:**
+
+| 类型     | 描述         |
+| -------- | ------------ |
+| `布尔值` | 是否创建成功 |
+
+**示例:**
+
+```javascript
+const 目录创建成功 = $文件.创建目录("/path/to/nested/directory");
+if (目录创建成功) {
+  $打印信息日志("目录创建成功");
+}
+```
+
+#### 列出目录列表 - 列出目录下的所有文件和子目录。
+
+```typescript
+function 列出目录列表(目录路径: 字符串, 是否递归: 布尔值): 数组<字符串>;
+```
+
+**参数:**
+
+| 参数名     | 类型   | 是否必填 | 默认值 | 描述                   |
+| ---------- | ------ | -------- | ------ | ---------------------- |
+| `目录路径` | 字符串 | 是       | -      | 目录路径               |
+| `是否递归` | 布尔值 | 是       | -      | 是否递归列出子目录内容 |
+
+**返回值:**
+
+| 类型           | 描述               |
+| -------------- | ------------------ |
+| `数组<字符串>` | 文件和目录路径数组 |
+
+**示例:**
+
+```javascript
+// 列出目录内容（不递归）
+const 文件列表 = $文件.列出目录列表("/path/to/directory", false);
+$打印信息日志(`目录内容: ${JSON.stringify(文件列表)}`);
+
+// 递归列出所有内容
+const 所有文件列表 = $文件.列出目录列表("/path/to/directory", true);
+$打印信息日志(`所有文件: ${JSON.stringify(所有文件列表)}`);
+```
+
+### 文件基础操作
+
+#### 创建文件
+
+```typescript
+function 创建文件(文件路径: 字符串): 布尔值;
+```
+
+**参数:**
+
+| 参数名     | 类型   | 是否必填 | 默认值 | 描述     |
+| ---------- | ------ | -------- | ------ | -------- |
+| `文件路径` | 字符串 | 是       | -      | 文件路径 |
+
+**返回值:**
+
+| 类型     | 描述         |
+| -------- | ------------ |
+| `布尔值` | 是否创建成功 |
+
+**示例:**
+
+```javascript
+const 文件创建成功 = $文件.创建文件("/path/to/newfile.txt");
+if (文件创建成功) {
+  $打印信息日志("文件创建成功");
+}
+```
+
+#### 文件是否存在
+
+```typescript
+function 文件是否存在(文件路径: 字符串): 布尔值;
+```
+
+**参数:**
+
+| 参数名     | 类型   | 是否必填 | 默认值 | 描述           |
+| ---------- | ------ | -------- | ------ | -------------- |
+| `文件路径` | 字符串 | 是       | -      | 文件或目录路径 |
+
+**返回值:**
+
+| 类型     | 描述     |
+| -------- | -------- |
+| `布尔值` | 是否存在 |
+
+**示例:**
+
+```javascript
+if ($文件.文件是否存在("/path/to/file.txt")) {
+  $打印信息日志("文件存在");
+} else {
+  $打印信息日志("文件不存在");
+}
+```
+
+#### 复制文件
+
+```typescript
+function 复制文件(源文件路径: 字符串, 目标文件路径: 字符串): 布尔值;
+```
+
+**参数:**
+
+| 参数名         | 类型   | 是否必填 | 默认值 | 描述         |
+| -------------- | ------ | -------- | ------ | ------------ |
+| `源文件路径`   | 字符串 | 是       | -      | 源文件路径   |
+| `目标文件路径` | 字符串 | 是       | -      | 目标文件路径 |
+
+**返回值:**
+
+| 类型     | 描述         |
+| -------- | ------------ |
+| `布尔值` | 是否复制成功 |
+
+**示例:**
+
+```javascript
+const 是否复制成功 = $文件.复制文件(
+  "/path/to/source.txt",
+  "/path/to/destination.txt"
+);
+if (是否复制成功) {
+  $打印信息日志("文件复制成功");
+}
+```
+
+#### 删除所有文件
+
+```typescript
+function 删除所有文件(文件或目录路径: 字符串): 布尔值;
+```
+
+**参数:**
+
+| 参数名           | 类型   | 是否必填 | 默认值 | 描述           |
+| ---------------- | ------ | -------- | ------ | -------------- |
+| `文件或目录路径` | 字符串 | 是       | -      | 文件或目录路径 |
+
+**返回值:**
+
+| 类型     | 描述         |
+| -------- | ------------ |
+| `布尔值` | 是否删除成功 |
+
+**示例:**
+
+```javascript
+const 是否删除成功 = $文件.删除所有文件("/path/to/file.txt");
+if (是否删除成功) {
+  $打印信息日志("文件删除成功");
+}
+```
+
+### 文件读写操作
+
+#### 读取文件 - 读取整个文件内容。
+
+```typescript
+function 读取文件(文件路径: 字符串): 字符串 | null;
+```
+
+**参数:**
+
+| 参数名     | 类型   | 是否必填 | 默认值 | 描述     |
+| ---------- | ------ | -------- | ------ | -------- |
+| `文件路径` | 字符串 | 是       | -      | 文件路径 |
+
+**返回值:**
+
+| 类型             | 描述                            |
+| ---------------- | ------------------------------- |
+| `字符串 \| null` | 文件内容；失败或不存在返回 null |
+
+**示例:**
+
+```javascript
+const 文件内容 = $文件.读取文件("/path/to/file.txt");
+if (文件内容 !== null) {
+  $打印信息日志(`文件内容: ${文件内容}`);
+} else {
+  $打印警告日志("文件不存在或读取失败");
+}
+```
+
+#### 读取`res`目录文件 - 读取`res`目录中的文本文件内容。
+
+**注意事项:**
+
+- 该函数仅适用于读取脚本 res 目录中的文本文件。
+- res 目录文件只读，不能修改。
+
+```typescript
+function 读取资源文件(文件名: 字符串): 字符串 | null;
+```
+
+**参数:**
+
+| 参数名   | 类型   | 是否必填 | 默认值 | 描述                               |
+| -------- | ------ | -------- | ------ | ---------------------------------- |
+| `文件名` | 字符串 | 是       | -      | 资源文件名（相对于资源目录的路径） |
+
+**返回值:**
+
+| 类型           | 描述                                    |
+| -------------- | --------------------------------------- |
+| `字符串\|null` | 文件内容 文件不存在或读取失败 返回 null |
+
+**示例:**
+
+```javascript
+// 读取配置文件
+const 配置文件内容 = $文件.读取资源文件("config.json");
+if (配置文件内容) {
+  const configObj = JSON.parse(配置文件内容);
+  $打印信息日志(`配置加载成功: ${JSON.stringify(configObj)}`);
+} else {
+  $打印信息日志("配置文件不存在或读取失败");
+}
+```
+
+#### 写入文件 - 写入文件内容（覆盖原有内容）。
+
+```typescript
+function 写入文件(文件路径: 字符串, 文件内容: 字符串): 布尔值;
+```
+
+**参数:**
+
+| 参数名     | 类型   | 是否必填 | 默认值 | 描述         |
+| ---------- | ------ | -------- | ------ | ------------ |
+| `文件路径` | 字符串 | 是       | -      | 文件路径     |
+| `文件内容` | 字符串 | 是       | -      | 要写入的内容 |
+
+**返回值:**
+
+| 类型     | 描述         |
+| -------- | ------------ |
+| `布尔值` | 是否写入成功 |
+
+**示例:**
+
+```javascript
+const success = $文件.写入文件("/path/to/file.txt", "Hello, World!");
+if (success) {
+  $打印信息日志("文件写入成功");
+}
+```
+
+#### 追加行 - 向文件追加内容。
+
+```typescript
+function 追加行(文件路径: 字符串, 文件内容: 字符串): 布尔值;
+```
+
+**参数:**
+
+| 参数名     | 类型   | 是否必填 | 默认值 | 描述         |
+| ---------- | ------ | -------- | ------ | ------------ |
+| `文件路径` | 字符串 | 是       | -      | 文件路径     |
+| `文件内容` | 字符串 | 是       | -      | 要追加的内容 |
+
+**返回值:**
+
+| 类型     | 描述         |
+| -------- | ------------ |
+| `布尔值` | 是否追加成功 |
+
+**示例:**
+
+```javascript
+const 是否追加成功 = $文件.追加行("/path/to/log.txt", "新的日志条目");
+if (是否追加成功) {
+  $打印信息日志("内容追加成功");
+}
+```
+
+### 按行操作
+
+#### 读取指定行 - 读取文件指定行的内容。
+
+```typescript
+function 读取指定行(文件路径: 字符串, 行号: 数字): 字符串 | null;
+```
+
+**参数:**
+
+| 参数名     | 类型   | 是否必填 | 默认值 | 描述              |
+| ---------- | ------ | -------- | ------ | ----------------- |
+| `文件路径` | 字符串 | 是       | -      | 文件路径          |
+| `行号`     | 数字   | 是       | -      | 行号（从 1 开始） |
+
+**返回值:**
+
+| 类型             | 描述                          |
+| ---------------- | ----------------------------- |
+| `字符串 \| null` | 行内容；失败或不存在返回 null |
+
+**示例:**
+
+```javascript
+const 第一行内容 = $文件.读取指定行("/path/to/file.txt", 1);
+$打印信息日志(`第一行内容: ${第一行内容}`);
+```
+
+#### 读取所有行 - 读取文件所有行内容。
+
+```typescript
+function 读取所有行(文件路径: 字符串): 数组<字符串> | null;
+```
+
+**参数:**
+
+| 参数名     | 类型   | 是否必填 | 默认值 | 描述     |
+| ---------- | ------ | -------- | ------ | -------- |
+| `文件路径` | 字符串 | 是       | -      | 文件路径 |
+
+**返回值:**
+
+| 类型                   | 描述                          |
+| ---------------------- | ----------------------------- |
+| `数组<字符串> \| null` | 所有行内容数组；失败返回 null |
+
+**示例:**
+
+```javascript
+const 所有行内容 = $文件.读取所有行("/path/to/file.txt");
+if (所有行内容 !== null) {
+  所有行内容.forEach((line, index) => {
+    $打印信息日志(`第${index + 1}行: ${line}`);
+  });
+} else {
+  $打印警告日志("读取所有行失败或文件不存在");
+}
+```
+
+#### 删除指定行 - 删除文件中符合条件的行。
+
+```typescript
+function 删除指定行(文件路径: 字符串, 行号: 数字, 包含内容?: 字符串): 布尔值;
+```
+
+**参数:**
+
+| 参数名     | 类型   | 是否必填 | 默认值 | 描述                                |
+| ---------- | ------ | -------- | ------ | ----------------------------------- |
+| `文件路径` | 字符串 | 是       | -      | 文件路径                            |
+| `行号`     | 数字   | 是       | -      | 行号（-1 表示不按行号删除）         |
+| `包含内容` | 字符串 | 否       | null   | 包含的内容（null 表示不按内容删除） |
+
+**返回值:**
+
+| 类型     | 描述         |
+| -------- | ------------ |
+| `布尔值` | 是否删除成功 |
+
+**示例:**
+
+```javascript
+// 删除第3行
+$文件.删除指定行("/path/to/file.txt", 3, null);
+
+// 删除包含"error"的行
+$文件.删除指定行("/path/to/file.txt", -1, "error");
+
+// 删除第5行且包含"debug"的行
+$文件.删除指定行("/path/to/file.txt", 5, "debug");
+```
+
+### 文件信息
+
+#### 计算文件 MD5。
+
+```typescript
+function 计算文件MD5(文件路径: 字符串): 字符串 | null;
+```
+
+**参数:**
+
+| 参数名     | 类型   | 是否必填 | 默认值 | 描述     |
+| ---------- | ------ | -------- | ------ | -------- |
+| `文件路径` | 字符串 | 是       | -      | 文件路径 |
+
+**返回值:**
+
+| 类型             | 描述                      |
+| ---------------- | ------------------------- |
+| `字符串 \| null` | 文件 MD5 值 失败返回 null |
+
+**示例:**
+
+```javascript
+const 文件MD5 = $文件.计算文件MD5("/path/to/file.txt");
+if (文件MD5) {
+  $打印信息日志(`文件MD5: ${文件MD5}`);
+} else {
+  $打印信息日志("获取MD5失败");
+}
+```