app.file - 文件操作 API

文件读写、复制、移动、删除等操作。

注意: 路径类型判断（exists, isDirectory, isFile, isSymlink）请使用 app.path 模块。

基础操作

app.file.read(path)

读取文件内容。

参数:

• path (string) - 文件路径

返回值: string, error - 文件内容，失败时返回 nil, error

local content, err = app.file.read("/path/to/file.txt")

app.file.write(path, content)

写入文件内容（覆盖）。

参数:

• path (string) - 文件路径
• content (string) - 要写入的内容

返回值: boolean, error - 是否成功，失败时返回 false, error

local ok, err = app.file.write("/path/to/file.txt", "Hello World")

app.file.append(path, content)

追加内容到文件末尾。

参数:

• path (string) - 文件路径
• content (string) - 要追加的内容

返回值: boolean, error - 是否成功，失败时返回 false, error

local ok, err = app.file.append("/path/to/log.txt", "新日志行\n")

app.file.copy(src, dest)

复制文件或目录。

参数:

• src (string) - 源路径
• dest (string) - 目标路径

返回值: boolean, error - 是否成功，失败时返回 false, error

local ok, err = app.file.copy("/source/file.txt", "/dest/file.txt")
app.file.copy("/source/folder", "/dest/folder")

app.file.move(src, dest)

移动或重命名文件/目录。

参数:

• src (string) - 源路径
• dest (string) - 目标路径

返回值: boolean, error - 是否成功，失败时返回 false, error

local ok, err = app.file.move("/old/path/file.txt", "/new/path/file.txt")
app.file.move("/path/old_name.txt", "/path/new_name.txt")

app.file.delete(path)

删除文件或目录。

参数:

• path (string) - 要删除的路径

返回值: boolean, error - 是否成功，失败时返回 false, error

local ok, err = app.file.delete("/path/to/file.txt")

app.file.mkdir(path)

创建目录（递归创建父目录）。

参数:

• path (string) - 目录路径

返回值: boolean, error - 是否成功，失败时返回 false, error

local ok, err = app.file.mkdir("/path/to/deep/nested/folder")

文件属性

app.file.size(path)

获取文件大小。

参数:

• path (string) - 文件路径

返回值: number|nil - 字节数或 nil

local size = app.file.size("/path/to/file.txt")

app.file.creationDate(path)

获取文件创建时间。

参数:

• path (string) - 文件路径

返回值: number|nil - Unix 时间戳或 nil

local created = app.file.creationDate("/path/to/file.txt")

app.file.modificationDate(path)

获取文件修改时间。

参数:

• path (string) - 文件路径

返回值: number|nil - Unix 时间戳或 nil

local modified = app.file.modificationDate("/path/to/file.txt")

app.file.permissions(path)

获取文件权限字符串。

参数:

• path (string) - 文件路径

返回值: string|nil - 八进制权限字符串或 nil

local perms = app.file.permissions("/path/to/file.txt")  -- "644"

app.file.attributes(path)

获取文件所有属性。

参数:

• path (string) - 文件路径

返回值: table|nil - 属性表或 nil

local attrs = app.file.attributes("/path/to/file.txt")
-- attrs.size: number
-- attrs.createdDate: number (时间戳)
-- attrs.modifiedDate: number (时间戳)
-- attrs.isDirectory: boolean
-- attrs.permissions: string

app.file.chmod(path, mode)

修改文件权限。

参数:

• path (string) - 文件路径
• mode (number|string) - 权限模式（如 755 或 “755”）

返回值: boolean, error - 是否成功，失败时返回 false, error

local ok, err = app.file.chmod("/path/to/script.sh", 755)
app.file.chmod("/path/to/script.sh", "755")

目录操作

app.file.list(path)

列出目录内容。

参数:

• path (string) - 目录路径

返回值: array|nil - 文件名数组（不含路径）

local items = app.file.list("/path/to/folder")
if items then
    for _, name in ipairs(items) do
        app.log.info(name)
    end
end

app.file.glob(directory, pattern)

使用 glob 模式匹配文件（非递归）。

参数:

• directory (string) - 目录路径
• pattern (string) - glob 模式（如 “*.txt”）

返回值: array|nil - 完整路径数组

local pngs = app.file.glob("/path/to/folder", "*.png")

app.file.find(directory, options?)

递归查找文件。

参数:

• directory (string) - 起始目录
• options (table, 可选):
  • name (string) - 文件名模式（支持 * 和 ? 通配符）
  • type (string) - 类型：”file”、”directory”、”any”（默认）
  • maxDepth (number) - 最大递归深度（0 表示无限制，默认）
  • limit (number) - 最大返回数量（默认 1000）

返回值: array - 完整路径数组

-- 查找所有 plist 文件
local plists = app.file.find("/path/to/folder", {
    name = "*.plist",
    type = "file",
    maxDepth = 5
})

-- 查找所有目录
local dirs = app.file.find("/path/to/folder", {
    type = "directory"
})

符号链接

app.file.link(target, linkPath)

创建符号链接。

参数:

• target (string) - 链接目标路径
• linkPath (string) - 链接文件路径

返回值: boolean, error - 是否成功，失败时返回 false, error

local ok, err = app.file.link("/path/to/target", "/path/to/link")

app.file.readlink(path)

读取符号链接目标。

参数:

• path (string) - 链接文件路径

返回值: string|nil - 目标路径或 nil

local target = app.file.readlink("/path/to/link")

临时文件

app.file.temp(opts?)

创建临时文件或目录。

参数:

• opts (table, 可选):
  • prefix (string) - 前缀，默认 "tmp"
  • suffix (string) - 后缀，默认 ""
  • directory (boolean) - 创建目录而非文件，默认 false
  • dir (string) - 基目录，默认系统临时目录

返回值: string, error - 创建的临时路径

-- 创建临时文件
local tmpFile, err = app.file.temp()
app.file.write(tmpFile, "临时数据")

-- 带后缀的临时文件
local tmpCsv = app.file.temp({suffix = ".csv"})

-- 创建临时目录
local tmpDir = app.file.temp({directory = true, prefix = "export"})

示例

批量重命名

function MyPlugin:handleRename(context)
    local result = app.dialog.form({
        title = "批量重命名",
        fields = {
            {type = "text", id = "prefix", label = "前缀", default = ""},
            {type = "number", id = "start", label = "起始编号", default = 1}
        }
    })

    if not result then return end

    local num = result.start
    for _, file in ipairs(context.selectedFiles) do
        local dir = app.path.dirname(file)
        local ext = app.path.extension(file)
        local newName = string.format("%s%03d.%s", result.prefix, num, ext)
        local newPath = app.path.join(dir, newName)

        app.file.move(file, newPath)
        num = num + 1
    end

    app.notification.show("完成", "重命名了 " .. #context.selectedFiles .. " 个文件")
end

清理空目录

function MyPlugin:handleCleanEmptyDirs(context)
    local dirs = app.file.find(context.currentDirectory, {
        type = "directory"
    })

    local deleted = 0
    -- 从最深的目录开始删除
    for i = #dirs, 1, -1 do
        local dir = dirs[i]
        local items = app.file.list(dir)
        if items and #items == 0 then
            if app.file.delete(dir) then
                deleted = deleted + 1
            end
        end
    end

    app.notification.show("完成", "删除了 " .. deleted .. " 个空目录")
end