跳至主要內容

colors 颜色模块

大约 6 分钟

colors 颜色模块

colors 是 ScriptX 直接注入到脚本运行时里的全局对象，专门负责“解析颜色、拆通道、拼颜色、拿常量色”。

这页尽量按第一次接触也能直接照着写的方式来讲，不只告诉你“有这个方法”，还会把下面这些容易踩坑的点写清楚：

  1. 颜色参数到底能写成哪些样子。
  2. rgba(...) 在这里和网页 CSS 里的习惯有什么不同。
  3. 数字颜色、字符串颜色、数组颜色分别怎么解释。
  4. 通道值越界时会不会报错。
  5. 返回值到底是数字还是字符串。

先记住这 8 条

  1. colors 是全局对象，直接写 colors.parseColor(...) 就能用，不需要额外导入。
  2. 这里的颜色内部本质上是 32 位整数，常见写法会被统一解释成 AARRGGBB。
  3. #RRGGBB 这种 6 位写法会自动补成不透明，也就是前面补 FF。
  4. rgba(255, 0, 0, 128) 的第 4 个参数在这里是 0..255，不是 CSS 里常见的 0..1。
  5. 数组颜色顺序是 [r, g, b, a]，不是 [a, r, g, b]。
  6. 通道值会被夹到 0..255 范围内，所以传 300 不会报错，而是按 255 处理。
  7. colors.toString(...) 返回的一定是大写的 #AARRGGBB。
  8. 空白字符串会被当成透明色，也就是 #00000000。

colors.toString(color)

把任意支持的颜色写法统一转成大写的 #AARRGGBB 字符串。

参数

参数类型可填值说明
colornumber | string | array | Java Collection见下表要转换的颜色值

color 支持的写法

写法例子实际解释
24 位整数0x3366ff自动补成 #FF3366FF
32 位整数0x803366ff直接按 #803366FF 解释
#RRGGBB"#3366ff"自动补不透明 alpha
#AARRGGBB"#803366ff"直接按带 alpha 颜色解释
0x... 字符串"0x803366ff"直接转成整数颜色
rgb(...)"rgb(51, 102, 255)"按 r, g, b 解析
rgba(...)"rgba(51, 102, 255, 128)"第 4 个值是 alpha 0..255
argb(...)"argb(128, 51, 102, 255)"第 1 个值是 alpha
三元数组[51, 102, 255]按 [r, g, b]，alpha 自动补 255
四元数组[51, 102, 255, 128]按 [r, g, b, a]

返回值

string

说明

  • 返回值总是形如 #AARRGGBB。
  • 字母总是大写。
  • 如果你传的是 24 位颜色，返回值里会自动补 FF alpha。
  • 如果你传的是空白字符串，例如 "" 或 " "，会返回 #00000000。

示例

log(colors.toString("#33cc99"));             // #FF33CC99
log(colors.toString("rgba(51, 204, 153, 8)")); // #0833CC99
log(colors.toString([51, 204, 153, 128]));  // #8033CC99

colors.red(color)

取红色通道。

参数

和 colors.toString(color) 的 color 完全一致。

返回值

number

返回范围始终是 0..255。

示例

log(colors.red("#33cc99"));   // 51
log(colors.red(0xff112233));  // 17

colors.green(color)

取绿色通道。

参数

和 colors.toString(color) 的 color 完全一致。

返回值

number

返回范围始终是 0..255。

示例

log(colors.green("#33cc99"));  // 204
log(colors.green([1, 2, 3]));  // 2

colors.blue(color)

取蓝色通道。

参数

和 colors.toString(color) 的 color 完全一致。

返回值

number

返回范围始终是 0..255。

示例

log(colors.blue("#33cc99"));  // 153
log(colors.blue("rgb(1, 2, 3)")); // 3

colors.alpha(color)

取透明度通道。

参数

和 colors.toString(color) 的 color 完全一致。

返回值

number

返回范围始终是 0..255。

说明

  • #RRGGBB、24 位整数、三元数组这类没显式写 alpha 的输入，都会按 255 处理。
  • 空白字符串会先被解释成透明色，所以 colors.alpha("") 会得到 0。

示例

log(colors.alpha("#33cc99"));      // 255
log(colors.alpha("#8033cc99"));    // 128
log(colors.alpha(""));             // 0

colors.rgb(red, green, blue)

按 red + green + blue 组一个不透明颜色。

参数

参数类型可填值默认值说明
rednumber | string任意数字或能转成数字的字符串无红色通道
greennumber | string任意数字或能转成数字的字符串无绿色通道
bluenumber | string任意数字或能转成数字的字符串无蓝色通道

返回值

number

说明

  • alpha 会固定补成 255。
  • 每个通道都会被夹到 0..255。
  • 字符串也能用，例如 "128"、"0x80"。

示例

const color = colors.rgb(51, 204, 153);
log(colors.toString(color)); // #FF33CC99

const clipped = colors.rgb(300, -8, "0x20");
log(colors.toString(clipped)); // #FFFF0020

colors.argb(alpha, red, green, blue)

按 alpha + red + green + blue 组一个颜色。

参数

参数类型可填值默认值说明
alphanumber | string任意数字或能转成数字的字符串无透明度
rednumber | string任意数字或能转成数字的字符串无红色通道
greennumber | string任意数字或能转成数字的字符串无绿色通道
bluenumber | string任意数字或能转成数字的字符串无蓝色通道

返回值

number

说明

  • 每个通道都会被夹到 0..255。
  • 这也是最稳的“显式写 alpha”方式。
  • 如果你不想记整数颜色的位数，优先用它最直观。

示例

const mask = colors.argb(128, 255, 0, 0);
log(colors.toString(mask)); // #80FF0000

colors.parseColor(colorStr)

把一个颜色值解析成整数颜色。

参数

虽然参数名叫 colorStr，但当前实现不只接受字符串，也接受数字和数组。

参数类型可填值
colorStrnumber | string | array | Java Collection与 colors.toString(color) 一致

返回值

number

说明

  • 这是整个 colors 模块最核心的入口。
  • red、green、blue、alpha、toString 本质上都会先走同一套颜色解析逻辑。
  • 如果传入不支持的对象类型，会抛异常。
  • 如果数组元素不足 3 个，也会抛异常。

示例

const color1 = colors.parseColor("#33cc99");
const color2 = colors.parseColor([51, 204, 153, 128]);

log(color1);
log(colors.toString(color2)); // #8033CC99

colors.BLACK

固定黑色，值是 #FF000000。

log(colors.toString(colors.BLACK)); // #FF000000

colors.DKGRAY

固定深灰色，值是 #FF444444。

log(colors.toString(colors.DKGRAY)); // #FF444444

colors.GRAY

固定灰色，值是 #FF888888。

log(colors.toString(colors.GRAY)); // #FF888888

colors.LTGRAY

固定浅灰色，值是 #FFCCCCCC。

log(colors.toString(colors.LTGRAY)); // #FFCCCCCC

colors.WHITE

固定白色，值是 #FFFFFFFF。

log(colors.toString(colors.WHITE)); // #FFFFFFFF

colors.RED

固定红色，值是 #FFFF0000。

log(colors.toString(colors.RED)); // #FFFF0000

colors.GREEN

固定绿色，值是 #FF00FF00。

log(colors.toString(colors.GREEN)); // #FF00FF00

colors.BLUE

固定蓝色，值是 #FF0000FF。

log(colors.toString(colors.BLUE)); // #FF0000FF

colors.YELLOW

固定黄色，值是 #FFFFFF00。

log(colors.toString(colors.YELLOW)); // #FFFFFF00

colors.CYAN

固定青色，值是 #FF00FFFF。

log(colors.toString(colors.CYAN)); // #FF00FFFF

colors.MAGENTA

固定品红色，值是 #FFFF00FF。

log(colors.toString(colors.MAGENTA)); // #FFFF00FF

colors.TRANSPARENT

固定全透明黑色，值是 #00000000。

说明

  • 它不是“没有颜色对象”，而是“alpha 为 0 的颜色值”。
  • 拿它去做比较、赋值、拼色都可以。
log(colors.toString(colors.TRANSPARENT)); // #00000000

常见报错与原因

缺少颜色参数

Missing color
Missing colorStr

这说明你把必填颜色参数漏掉了。

数组长度不够

colorStr must contain at least red, green and blue

这说明你传的是数组或列表，但长度不到 3。

不支持的颜色类型

Unsupported color value: ...

这说明你传进去的不是数字、字符串、数组，也不是 Java/Kotlin 集合。

通道值缺失或空白

Missing red
alpha cannot be blank

这类错误通常出现在 rgb(...)、argb(...) 或数组写法里，某个通道没传、传空串，或者格式不对。

生活原本沉闷，但跑起来就会有风
Copyright © 2026 道无涯i