app.string - 字符串工具 API

扩展字符串处理功能，增强 Lua 原生字符串功能。

基础操作

app.string.trim(str)

去除首尾空白字符。

app.string.trim("  hello world  ")  -- "hello world"
app.string.trim("\t hello \n")      -- "hello"

app.string.trimLeft(str)

去除左侧空白字符。

app.string.trimLeft("  hello")  -- "hello"

app.string.trimRight(str)

去除右侧空白字符。

app.string.trimRight("hello  ")  -- "hello"

app.string.split(str, separator)

分割字符串。

参数:

• str (string) - 要分割的字符串
• separator (string) - 分隔符（空字符串则按字符分割）

返回值: array - 分割后的数组

app.string.split("a,b,c", ",")     -- {"a", "b", "c"}
app.string.split("hello", "")      -- {"h", "e", "l", "l", "o"}
app.string.split("a::b", "::")     -- {"a", "b"}

app.string.join(array, separator)

连接数组为字符串。

参数:

• array (table) - 字符串数组
• separator (string) - 分隔符

返回值: string

app.string.join({"a", "b", "c"}, ", ")  -- "a, b, c"
app.string.join({1, 2, 3}, "-")         -- "1-2-3"

判断方法

app.string.startsWith(str, prefix)

检查是否以指定前缀开头。

app.string.startsWith("hello", "he")     -- true
app.string.startsWith("hello", "world")  -- false

app.string.endsWith(str, suffix)

检查是否以指定后缀结尾。

app.string.endsWith("hello.txt", ".txt")  -- true
app.string.endsWith("hello", "world")     -- false

app.string.contains(str, substr)

检查是否包含子串。

app.string.contains("hello world", "world")  -- true
app.string.contains("hello", "x")            -- false

app.string.isEmpty(str)

检查是否为空或仅空白。

app.string.isEmpty("")       -- true
app.string.isEmpty("   ")    -- true
app.string.isEmpty("hello")  -- false

大小写转换

app.string.upper(str)

转换为大写。

app.string.upper("Hello World")  -- "HELLO WORLD"

app.string.lower(str)

转换为小写。

app.string.lower("Hello World")  -- "hello world"

app.string.capitalize(str)

首字母大写（其余小写）。

app.string.capitalize("hello")  -- "Hello"
app.string.capitalize("HELLO")  -- "Hello"

app.string.camelCase(str)

转换为驼峰命名。

app.string.camelCase("hello_world")   -- "helloWorld"
app.string.camelCase("hello-world")   -- "helloWorld"
app.string.camelCase("Hello World")   -- "helloWorld"

app.string.snakeCase(str)

转换为蛇形命名。

app.string.snakeCase("helloWorld")    -- "hello_world"
app.string.snakeCase("HelloWorld")    -- "hello_world"
app.string.snakeCase("hello-world")   -- "hello_world"

app.string.kebabCase(str)

转换为短横线命名。

app.string.kebabCase("helloWorld")    -- "hello-world"
app.string.kebabCase("HelloWorld")    -- "hello-world"

格式化

app.string.format(template, …)

格式化字符串（支持 %s, %d, %f, %@ 占位符）。

app.string.format("Hello, %s!", "World")     -- "Hello, World!"
app.string.format("Value: %d", 42)           -- "Value: 42"
app.string.format("Price: %f", 3.14)         -- "Price: 3.14"

app.string.padLeft(str, length, char?)

左侧填充字符。

参数:

• str (string) - 原字符串
• length (number) - 目标长度
• char (string, 可选) - 填充字符（默认空格）

app.string.padLeft("123", 6, "0")  -- "000123"
app.string.padLeft("hi", 5)        -- "   hi"

app.string.padRight(str, length, char?)

右侧填充字符。

app.string.padRight("123", 6, "0")  -- "123000"
app.string.padRight("hi", 5)        -- "hi   "

app.string.repeat(str, count)

重复字符串。

app.string.repeat("ab", 3)  -- "ababab"
app.string.repeat("-", 10)  -- "----------"

app.string.reverse(str)

反转字符串。

app.string.reverse("hello")  -- "olleh"

提取方法

app.string.substring(str, start, end?)

截取子串。索引从 0 开始。

参数:

• str (string) - 原字符串
• start (number) - 起始位置（从 0 开始）
• end (number, 可选) - 结束位置（不包含，默认到末尾）

app.string.substring("hello world", 0, 5)   -- "hello"
app.string.substring("hello world", 6)      -- "world"

app.string.charAt(str, index)

获取指定位置的字符。索引从 0 开始。

app.string.charAt("hello", 0)  -- "h"
app.string.charAt("hello", 4)  -- "o"

app.string.indexOf(str, substr)

查找子串位置。

返回值: number - 位置（从 0 开始），未找到返回 -1

app.string.indexOf("hello world", "o")      -- 4
app.string.indexOf("hello world", "x")      -- -1

app.string.lastIndexOf(str, substr)

查找子串最后出现的位置。

app.string.lastIndexOf("hello world", "o")  -- 7

app.string.length(str)

获取字符串长度（字符数，支持 UTF-8）。

app.string.length("hello")   -- 5
app.string.length("你好")    -- 2

替换方法

app.string.replace(str, old, new)

替换首个匹配。

app.string.replace("hello world", "o", "0")  -- "hell0 world"

app.string.replaceAll(str, old, new)

替换所有匹配。

app.string.replaceAll("hello world", "o", "0")  -- "hell0 w0rld"

app.string.remove(str, substr)

移除首个匹配的子串。

app.string.remove("hello world", "o")  -- "hell world"

app.string.removeAll(str, substr)

移除所有匹配的子串。

app.string.removeAll("hello world", "o")  -- "hell wrld"

示例

批量重命名（格式化）

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

    if not result then return end

    local n = result.start
    for _, file in ipairs(context.selectedFiles) do
        local ext = app.path.extension(file)

        -- 生成编号
        local numStr = app.string.padLeft(tostring(n), result.digits, "0")
        local newName = result.prefix .. numStr

        if ext ~= "" then
            newName = newName .. "." .. ext
        end

        local newPath = app.path.join(app.path.dirname(file), newName)
        app.file.move(file, newPath)
        n = n + 1
    end
end

文件名清理

function MyPlugin:handleCleanFilenames(context)
    for _, file in ipairs(context.selectedFiles) do
        local name = app.path.basename(file)
        local cleanName = name

        -- 去除首尾空白
        cleanName = app.string.trim(cleanName)

        -- 替换多个空格为单个
        while app.string.contains(cleanName, "  ") do
            cleanName = app.string.replaceAll(cleanName, "  ", " ")
        end

        -- 替换特殊字符
        cleanName = app.string.replaceAll(cleanName, ":", "-")
        cleanName = app.string.replaceAll(cleanName, "/", "-")

        if cleanName ~= name then
            local newPath = app.path.join(app.path.dirname(file), cleanName)
            app.file.move(file, newPath)
        end
    end
end

驼峰命名转换

function MyPlugin:handleConvertCase(context)
    local result = app.dialog.form({
        title = "命名转换",
        fields = {
            {type = "dropdown", id = "style", label = "目标格式",
             options = {"camelCase", "snake_case", "kebab-case"},
             default = "camelCase"}
        }
    })

    if not result then return end

    for _, file in ipairs(context.selectedFiles) do
        local name = app.path.name(file)
        local ext = app.path.extension(file)
        local newName

        if result.style == "camelCase" then
            newName = app.string.camelCase(name)
        elseif result.style == "snake_case" then
            newName = app.string.snakeCase(name)
        else
            newName = app.string.kebabCase(name)
        end

        if ext ~= "" then
            newName = newName .. "." .. ext
        end

        local newPath = app.path.join(app.path.dirname(file), newName)
        app.file.move(file, newPath)
    end
end