app.screen - 屏幕与外观 API

屏幕信息、外观模式、亮度控制、截屏和取色。

屏幕信息

app.screen.list()

获取所有连接的显示器。

返回值: array<table> - 每项包含:

• id (number) - 显示器 ID
• name (string) - 显示器名称
• width (number) - 宽度（点）
• height (number) - 高度（点）
• scaleFactor (number) - 缩放因子（Retina 为 2.0）
• isMain (boolean) - 是否主显示器
• isBuiltIn (boolean) - 是否内置显示器

local screens = app.screen.list()
for _, s in ipairs(screens) do
    app.log.info(s.name .. ": " .. s.width .. "x" .. s.height)
end

app.screen.mainScreen()

获取主显示器信息。

返回值: table - 包含以下字段:

• id (number) - 显示器 ID
• name (string) - 显示器名称
• width (number) - 宽度（点）
• height (number) - 高度（点）
• scaleFactor (number) - 缩放因子（Retina 为 2.0）

注意：与 list() 不同，mainScreen() 不包含 isMain 和 isBuiltIn 字段。

local main = app.screen.mainScreen()
app.log.info("主屏: " .. main.width .. "x" .. main.height .. " @" .. main.scaleFactor .. "x")

外观

app.screen.isDarkMode()

检查是否深色模式。

返回值: boolean

if app.screen.isDarkMode() then
    app.log.info("深色模式")
end

app.screen.setDarkMode(enabled)

设置深色模式。

参数:

• enabled (boolean) - 是否启用

返回值: boolean, error

app.screen.setDarkMode(true)   -- 启用深色模式
app.screen.setDarkMode(false)  -- 启用浅色模式

app.screen.accentColor()

获取系统强调色。

返回值: string - "red", "orange", "yellow", "green", "blue", "purple", "pink", "graphite"

local color = app.screen.accentColor()  -- "blue"

亮度

app.screen.brightness()

获取内置显示器亮度。

返回值: number|nil, error - 0.0 到 1.0

local brightness = app.screen.brightness()
if brightness then
    app.log.info("亮度: " .. math.floor(brightness * 100) .. "%")
end

app.screen.setBrightness(value)

设置内置显示器亮度。

参数:

• value (number) - 亮度值（0.0-1.0，自动裁剪）

返回值: boolean, error

app.screen.setBrightness(0.8)  -- 设为 80%

截屏与取色

app.screen.capture(path, opts?)

截取屏幕并保存为图片。

参数:

• path (string) - 保存路径
• opts (table, 可选):
  • displayId (number) - 指定显示器 ID

返回值: boolean, error

-- 截取主屏
app.screen.capture("/tmp/screenshot.png")

-- 截取指定显示器
app.screen.capture("/tmp/ext_screen.jpg", {displayId = 2})

app.screen.colorPicker()

打开系统取色器（需要 macOS 10.15+）。

返回值: table|nil, error

• hex (string) - “#RRGGBB” 格式
• r, g, b (number) - 0-255
• a (number) - 0.0-1.0

用户取消返回 nil。

local color = app.screen.colorPicker()
if color then
    app.log.info("颜色: " .. color.hex)
    app.clipboard.setText(color.hex)
end

事件监听

app.screen.watch(event, callback)

监听屏幕和外观变化事件。

参数:

• event (string) - 事件名称:
  • "darkModeChanged" - 深色/浅色模式切换时触发，回调参数: {isDarkMode}
  • "displayChanged" - 显示器配置变化（连接/断开/分辨率更改）时触发，回调参数: {displays}
• callback (function) - 回调函数:
  • darkModeChanged 事件: 接收 {isDarkMode (boolean)}
  • displayChanged 事件: 接收 {displays (array)} — 格式同 app.screen.list() 返回值

返回值: string, error - watcher 句柄 ID

app.screen.watch("darkModeChanged", function(e)
    if e.isDarkMode then
        app.log.info("已切换到深色模式")
    else
        app.log.info("已切换到浅色模式")
    end
end)

app.screen.watch("displayChanged", function(e)
    app.log.info("显示器配置已变化，当前显示器数量: " .. #e.displays)
end)

app.screen.stopAllWatchers()

停止当前插件注册的所有屏幕事件监听器。

返回值: boolean

app.screen.stopAllWatchers()

app.screen.listWatchers()

列出当前插件已注册的屏幕事件监听器。

返回值: array<table> - 每项包含:

• id (string) - watcher 句柄 ID
• event (string) - 监听的事件名称

local watchers = app.screen.listWatchers()
for _, w in ipairs(watchers) do
    app.log.info(w.id .. " -> " .. w.event)
end

示例

深色模式切换

function MyPlugin:handleToggleDarkMode(context)
    local isDark = app.screen.isDarkMode()
    local ok, err = app.screen.setDarkMode(not isDark)
    if ok then
        app.notification.show("外观", isDark and "已切换到浅色模式" or "已切换到深色模式")
    end
end