app.date - 日期时间 API

日期时间格式化和计算。

获取当前时间

app.date.now()

获取当前 Unix 时间戳（秒）。

返回值: number - Unix 时间戳

local ts = app.date.now()  -- 1701234567.123

app.date.nowMs()

获取当前 Unix 时间戳（毫秒）。

返回值: number - 毫秒时间戳

local ms = app.date.nowMs()  -- 1701234567123

app.date.today()

获取今天的日期字符串。

返回值: string - YYYY-MM-DD 格式

local today = app.date.today()  -- "2024-12-01"

app.date.time()

获取当前时间字符串。

返回值: string - HH:mm:ss 格式

local time = app.date.time()  -- "14:30:00"

格式化

app.date.format(timestamp?, pattern?)

格式化时间戳。

参数:

• timestamp (number, 可选) - Unix 时间戳（默认当前时间）
• pattern (string, 可选) - 格式字符串（默认 “yyyy-MM-dd HH:mm:ss”）

返回值: string - 格式化的日期时间

app.date.format()                          -- "2024-12-01 14:30:00"
app.date.format(nil, "yyyy年MM月dd日")      -- "2024年12月01日"
app.date.format(1701234567)                -- "2023-11-29 10:49:27"
app.date.format(1701234567, "HH:mm")       -- "10:49"

app.date.parse(dateString, pattern?)

解析日期字符串为时间戳。

参数:

• dateString (string) - 日期字符串
• pattern (string, 可选) - 格式字符串（默认 “yyyy-MM-dd HH:mm:ss”）

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

app.date.parse("2024-12-01 14:30:00")                    -- 1701434200
app.date.parse("2024/12/01", "yyyy/MM/dd")

app.date.iso(timestamp?)

返回 ISO 8601 格式的日期时间。

参数:

• timestamp (number, 可选) - Unix 时间戳（默认当前时间）

返回值: string - ISO 8601 格式

app.date.iso()  -- "2024-12-01T14:30:00Z"

日期组件

app.date.year(timestamp?)

获取年份。

参数:

• timestamp (number, 可选) - Unix 时间戳（默认当前时间）

返回值: number - 年份

app.date.year()  -- 2024

app.date.month(timestamp?)

获取月份（1-12）。

app.date.month()  -- 12

app.date.day(timestamp?)

获取日期（1-31）。

app.date.day()  -- 1

app.date.hour(timestamp?)

获取小时（0-23）。

app.date.hour()  -- 14

app.date.minute(timestamp?)

获取分钟（0-59）。

app.date.minute()  -- 30

app.date.second(timestamp?)

获取秒（0-59）。

app.date.second()  -- 0

app.date.weekday(timestamp?)

获取星期（1=周日, 7=周六）。

app.date.weekday()  -- 1 (周日)

app.date.dayOfYear(timestamp?)

获取年中第几天（1-366）。

app.date.dayOfYear()  -- 336

日期计算

app.date.add(timestamp, value, unit)

向日期添加时间。

参数:

• timestamp (number) - 基准时间戳
• value (integer) - 数量（可为负数，必须为整数）
• unit (string) - 单位：year/years, month/months, week/weeks, day/days, hour/hours, minute/minutes, second/seconds

返回值: number|nil - 新时间戳

local now = app.date.now()
app.date.add(now, 1, "days")     -- 明天
app.date.add(now, -7, "days")    -- 7 天前
app.date.add(now, 2, "months")   -- 2 个月后

app.date.diff(timestamp1, timestamp2, unit?)

计算两个时间的差值。

参数:

• timestamp1 (number) - 第一个时间戳
• timestamp2 (number) - 第二个时间戳
• unit (string, 可选) - 单位（默认 “seconds”）

返回值: number - 差值

local diff = app.date.diff(ts1, ts2, "days")
-- 返回相差天数

app.date.startOf(timestamp, unit)

获取时间单位的起点。

参数:

• timestamp (number) - 时间戳
• unit (string) - 单位：year, month, week, day, hour, minute

返回值: number|nil - 起点时间戳

local startOfDay = app.date.startOf(app.date.now(), "day")     -- 今天 0:00
local startOfMonth = app.date.startOf(app.date.now(), "month") -- 本月 1 日

app.date.endOf(timestamp, unit)

获取时间单位的终点。

参数:

• timestamp (number) - 时间戳
• unit (string) - 单位：year, month, week, day, hour, minute

返回值: number|nil - 终点时间戳

local endOfDay = app.date.endOf(app.date.now(), "day")  -- 今天 23:59:59

判断

app.date.isBefore(timestamp1, timestamp2)

判断 timestamp1 是否在 timestamp2 之前。

返回值: boolean

app.date.isBefore(ts1, ts2)  -- true/false

app.date.isAfter(timestamp1, timestamp2)

判断 timestamp1 是否在 timestamp2 之后。

返回值: boolean

app.date.isAfter(ts1, ts2)  -- true/false

app.date.isSame(timestamp1, timestamp2, unit?)

判断两个时间是否在同一单位内。

参数:

• timestamp1 (number)
• timestamp2 (number)
• unit (string, 可选) - 单位（默认 “day”）

返回值: boolean

app.date.isSame(ts1, ts2, "month")  -- 是否同一个月

app.date.isToday(timestamp)

判断是否为今天。

app.date.isToday(app.date.now())  -- true

app.date.isWeekend(timestamp)

判断是否为周末。

app.date.isWeekend(app.date.now())  -- true/false

app.date.isLeapYear(year)

判断是否为闰年。

app.date.isLeapYear(2024)  -- true

示例

按日期整理文件

function MyPlugin:handleOrganizeByDate(context)
    for _, file in ipairs(context.selectedFiles) do
        local modTime = app.file.modificationDate(file)
        if modTime then
            local dateStr = app.date.format(modTime, "yyyy-MM")
            local destDir = app.path.join(context.currentDirectory, dateStr)

            if not app.path.exists(destDir) then
                app.file.mkdir(destDir)
            end

            local destPath = app.path.join(destDir, app.path.basename(file))
            app.file.move(file, destPath)
        end
    end

    app.notification.show("完成", "文件已按日期整理")
end

添加日期戳

function MyPlugin:handleAddDateStamp(context)
    local dateStr = app.date.format(nil, "yyyyMMdd")

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

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

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