app.path - 路径工具 API

路径解析、组合和特殊目录访问。

路径组件提取

app.path.basename(path)

获取路径的文件名（含扩展名）。

app.path.basename("/path/to/file.txt")  -- "file.txt"
app.path.basename("/path/to/folder")    -- "folder"

app.path.name(path)

获取路径的文件名（不含扩展名）。

app.path.name("/path/to/file.txt")      -- "file"
app.path.name("/path/to/archive.tar.gz") -- "archive.tar"

app.path.extension(path)

获取文件扩展名（不含点号）。

app.path.extension("/path/to/file.txt")      -- "txt"
app.path.extension("/path/to/archive.tar.gz") -- "gz"
app.path.extension("/path/to/folder")         -- ""

app.path.dirname(path)

获取父目录路径。

app.path.dirname("/path/to/file.txt")   -- "/path/to"

路径操作

app.path.join(…)

拼接路径组件。

app.path.join("/path", "to", "file.txt")     -- "/path/to/file.txt"

app.path.normalize(path)

规范化路径（解析 . 和 ..）。

app.path.normalize("/path/../to/./file")     -- "/to/file"

app.path.expandTilde(path)

展开波浪号为用户主目录。

app.path.expandTilde("~/Documents")          -- "/Users/username/Documents"

app.path.absolute(path)

转换为绝对路径（同时展开 ~）。

app.path.absolute("./file.txt")              -- "/current/dir/file.txt"
app.path.absolute("~/file.txt")              -- "/Users/username/file.txt"

app.path.relative(path, base)

获取相对路径。

app.path.relative("/a/b/c/file.txt", "/a/b")  -- "c/file.txt"
app.path.relative("/a/b/c", "/a/d")           -- "../b/c"

路径字符串判断

app.path.isAbsolute(path)

检查是否为绝对路径（以 / 或 ~ 开头）。

app.path.isAbsolute("/path/to/file")     -- true
app.path.isAbsolute("~/Documents")       -- true
app.path.isAbsolute("./relative/path")   -- false

app.path.isRelative(path)

检查是否为相对路径。

app.path.isRelative("./path/to/file")    -- true
app.path.isRelative("/absolute/path")    -- false

app.path.hasExtension(path, ext?)

检查文件是否有扩展名。如果指定 ext，检查是否匹配（不区分大小写）。

app.path.hasExtension("/file.txt")            -- true（有扩展名）
app.path.hasExtension("/file.txt", "txt")     -- true
app.path.hasExtension("/file.TXT", "txt")     -- true（不区分大小写）
app.path.hasExtension("/file.txt", ".txt")    -- true（带点号也可以）
app.path.hasExtension("/folder")              -- false

文件系统检查

app.path.exists(path)

检查路径是否存在。

if app.path.exists("/path/to/file") then
    -- 文件或目录存在
end

app.path.isDirectory(path)

检查是否为目录。

if app.path.isDirectory("/path/to/folder") then
    -- 是目录
end

app.path.isFile(path)

检查是否为普通文件（非目录、非符号链接）。

if app.path.isFile("/path/to/file.txt") then
    -- 是文件
end

app.path.isSymlink(path)

检查是否为符号链接。

if app.path.isSymlink("/path/to/link") then
    -- 是符号链接
end

路径修改

app.path.withExtension(path, ext)

更改扩展名。

app.path.withExtension("/path/file.txt", "md")     -- "/path/file.md"
app.path.withExtension("/path/file.txt", ".md")    -- "/path/file.md"

app.path.withName(path, name)

更改文件名（保留扩展名）。

app.path.withName("/path/old.txt", "new")          -- "/path/new.txt"

app.path.withBasename(path, basename)

更改完整文件名（含扩展名）。

app.path.withBasename("/path/old.txt", "new.md")   -- "/path/new.md"

app.path.withDirname(path, dirname)

更改父目录。

app.path.withDirname("/old/file.txt", "/new")      -- "/new/file.txt"

特殊目录

获取系统特殊目录路径：

app.path.home()         -- "/Users/username"
app.path.temp()         -- "/var/folders/.../T"
app.path.desktop()      -- "/Users/username/Desktop"
app.path.documents()    -- "/Users/username/Documents"
app.path.downloads()    -- "/Users/username/Downloads"
app.path.applications() -- "/Applications"
app.path.caches()       -- "/Users/username/Library/Caches"
app.path.library()      -- "/Users/username/Library"
app.path.movies()       -- "/Users/username/Movies"
app.path.music()        -- "/Users/username/Music"
app.path.pictures()     -- "/Users/username/Pictures"

路径分析

app.path.components(path)

分解路径为组件数组。

app.path.components("/a/b/c")    -- {"/", "a", "b", "c"}
app.path.components("a/b/c")     -- {"a", "b", "c"}

app.path.split(path)

分解为目录和文件名。

local parts = app.path.split("/path/to/file.txt")
-- { dirname = "/path/to", basename = "file.txt" }

app.path.splitext(path)

分解为名称和扩展名。

local parts = app.path.splitext("/path/file.txt")
-- { name = "file", extension = "txt" }

示例

批量更改扩展名

function MyPlugin:handleChangeExt(context)
    local result = app.dialog.form({
        title = "更改扩展名",
        fields = {
            {type = "text", id = "ext", label = "新扩展名", default = "md"}
        }
    })
    if not result then return end

    for _, file in ipairs(context.selectedFiles) do
        local newPath = app.path.withExtension(file, result.ext)
        app.file.move(file, newPath)
    end
end

整理文件到子目录

function MyPlugin:handleOrganize(context)
    local dir = context.currentDirectory

    for _, file in ipairs(context.selectedFiles) do
        local ext = app.path.extension(file)
        if ext ~= "" then
            local subdir = app.path.join(dir, ext:upper())
            if not app.path.exists(subdir) then
                app.file.mkdir(subdir)
            end

            local dest = app.path.join(subdir, app.path.basename(file))
            app.file.move(file, dest)
        end
    end
end