app.color - 颜色工具 API

颜色格式转换、混合、对比度计算和颜色拾取。

方法

app.color.parse(str)

解析颜色字符串。

参数:

• str (string) - 颜色字符串，支持格式:
  • "#RGB" - 3 位十六进制
  • "#RRGGBB" - 6 位十六进制
  • "#RRGGBBAA" - 8 位十六进制（含透明度）
  • "rgb(r, g, b)" - RGB 函数
  • "rgba(r, g, b, a)" - RGBA 函数

返回值: table, error - {r, g, b, a, hex}

local c = app.color.parse("#FF6600")
-- c = {r=255, g=102, b=0, a=1.0, hex="#FF6600"}

local c = app.color.parse("rgb(100, 200, 50)")
-- c = {r=100, g=200, b=50, a=1.0, hex="#64C832"}

app.color.hex(r, g, b)

RGB 值转十六进制字符串。

参数:

• r (number) - 红色 (0-255)
• g (number) - 绿色 (0-255)
• b (number) - 蓝色 (0-255)

返回值: string - 如 "#FF6600"

local hex = app.color.hex(255, 102, 0)  -- "#FF6600"

app.color.rgb(hex)

十六进制字符串转 RGB。

参数:

• hex (string) - 十六进制颜色

返回值: table, error - {r, g, b, a}

local c = app.color.rgb("#FF6600")
-- c = {r=255, g=102, b=0, a=1.0}

app.color.hsl(r, g, b)

RGB 转 HSL。

参数:

• r, g, b (number) - RGB 值 (0-255)

返回值: table, error - {h, s, l} (h: 0-360, s: 0-100, l: 0-100)

local hsl = app.color.hsl(255, 0, 0)
-- hsl = {h=0, s=100, l=50}

app.color.hsv(r, g, b)

RGB 转 HSV。

参数:

• r, g, b (number) - RGB 值 (0-255)

返回值: table, error - {h, s, v} (h: 0-360, s: 0-100, v: 0-100)

local hsv = app.color.hsv(255, 0, 0)
-- hsv = {h=0, s=100, v=100}

app.color.fromHSL(h, s, l)

HSL 转 RGB。

参数:

• h (number) - 色相 (0-360)
• s (number) - 饱和度 (0-100)
• l (number) - 亮度 (0-100)

返回值: table - {r, g, b, hex}

local c = app.color.fromHSL(0, 100, 50)
-- c = {r=255, g=0, b=0, hex="#FF0000"}

app.color.fromHSV(h, s, v)

HSV 转 RGB。

参数:

• h (number) - 色相 (0-360)
• s (number) - 饱和度 (0-100)
• v (number) - 明度 (0-100)

返回值: table - {r, g, b, hex}

local c = app.color.fromHSV(120, 100, 100)
-- c = {r=0, g=255, b=0, hex="#00FF00"}

app.color.blend(color1, color2, ratio?)

混合两个颜色。

参数:

• color1 (string) - 第一个颜色（十六进制）
• color2 (string) - 第二个颜色（十六进制）
• ratio (number, 可选) - 混合比例 (0-100)，默认 50

返回值: table, error - {r, g, b, hex}

local c = app.color.blend("#FF0000", "#0000FF")
-- 50% 混合 → 紫色

local c = app.color.blend("#FF0000", "#0000FF", 25)
-- 25% 偏向蓝色

app.color.lighten(hex, amount?)

使颜色变亮。

参数:

• hex (string) - 十六进制颜色
• amount (number, 可选) - 变亮程度 (0-100)，默认 10

返回值: string, error - 新的十六进制颜色

local lighter = app.color.lighten("#336699", 20)

app.color.darken(hex, amount?)

使颜色变暗。

参数:

• hex (string) - 十六进制颜色
• amount (number, 可选) - 变暗程度 (0-100)，默认 10

返回值: string, error - 新的十六进制颜色

local darker = app.color.darken("#336699", 20)

app.color.contrast(hex1, hex2)

计算 WCAG 2.0 对比度比值。

参数:

• hex1 (string) - 第一个颜色
• hex2 (string) - 第二个颜色

返回值: number, error - 对比度比值 (1.0-21.0)

local ratio = app.color.contrast("#000000", "#FFFFFF")
-- ratio = 21.0（最大对比度）

local ratio = app.color.contrast("#336699", "#FFFFFF")
-- 用于检查是否满足 WCAG AA 标准（>= 4.5）

app.color.isLight(hex)

判断颜色是否为浅色。

参数:

• hex (string) - 十六进制颜色

返回值: boolean, error

app.color.isLight("#FFFFFF")  -- true
app.color.isLight("#000000")  -- false

app.color.pick()

打开系统颜色拾取器。

返回值: table - {hex, r, g, b, a}，用户取消返回 nil

local c = app.color.pick()
if c then
    app.log.info("选择的颜色: " .. c.hex)
end

示例

生成颜色调色板

function MyPlugin:handlePalette(context)
    local baseHex = "#3366CC"
    local palette = {baseHex}

    -- 生成 5 个渐亮色阶
    for i = 1, 5 do
        table.insert(palette, app.color.lighten(baseHex, i * 10))
    end

    -- 生成 5 个渐暗色阶
    for i = 1, 5 do
        table.insert(palette, app.color.darken(baseHex, i * 10))
    end

    local result = "调色板:\n"
    for _, hex in ipairs(palette) do
        local c = app.color.rgb(hex)
        result = result .. hex .. "  rgb(" .. c.r .. "," .. c.g .. "," .. c.b .. ")\n"
    end

    app.dialog.alert("调色板", result)
end

检查文本可读性

function MyPlugin:handleCheckContrast(context)
    local bg = app.color.pick()
    if not bg then return end

    local fg = app.color.pick()
    if not fg then return end

    local ratio = app.color.contrast(bg.hex, fg.hex)
    local level = "不合格"
    if ratio >= 7 then level = "AAA"
    elseif ratio >= 4.5 then level = "AA"
    elseif ratio >= 3 then level = "AA (大文本)"
    end

    app.dialog.alert("对比度检查",
        "前景: " .. fg.hex .. "\n" ..
        "背景: " .. bg.hex .. "\n" ..
        "对比度: " .. ratio .. ":1\n" ..
        "WCAG 级别: " .. level
    )
end