ms-vite-plugin 1.4.49 → 1.4.51

package/docs/apilua/file.md

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