Back to Details

pixijs-color

Compare original and translation side by side

🇺🇸

Original

English
🇨🇳

Translation

Chinese
The 
Color
class creates and converts colors for tints, fills, strokes, and anywhere PixiJS accepts a 
ColorSource
. Most APIs accept raw hex/strings directly, so explicit 
new Color(...)
is only needed when converting formats or manipulating values.
Color
类用于为色调、填充、描边以及所有PixiJS接受
ColorSource
的场景创建和转换颜色。大多数API直接支持原始十六进制值/字符串，因此仅在需要转换格式或操作颜色值时，才需要显式使用
new Color(...)
。

Quick Start

快速入门

ts
const fillColor = new Color("#ff6600");
console.log(fillColor.toHex()); // '#ff6600'
console.log(fillColor.toNumber()); // 0xff6600
console.log(fillColor.toArray()); // [1, 0.4, 0, 1]

const g = new Graphics().rect(0, 0, 200, 100).fill(fillColor);
app.stage.addChild(g);

const sprite = Sprite.from("hero.png");
sprite.tint = "dodgerblue";
app.stage.addChild(sprite);

const t = Color.shared.setValue(0xffffff).multiply([1, 0.5, 0.5]).toNumber();
sprite.tint = t;
Related skills: 
pixijs-scene-graphics
(fill/stroke colors), 
pixijs-scene-sprite
(tint), 
pixijs-blend-modes
(compositing).
ts
const fillColor = new Color("#ff6600");
console.log(fillColor.toHex()); // '#ff6600'
console.log(fillColor.toNumber()); // 0xff6600
console.log(fillColor.toArray()); // [1, 0.4, 0, 1]

const g = new Graphics().rect(0, 0, 200, 100).fill(fillColor);
app.stage.addChild(g);

const sprite = Sprite.from("hero.png");
sprite.tint = "dodgerblue";
app.stage.addChild(sprite);

const t = Color.shared.setValue(0xffffff).multiply([1, 0.5, 0.5]).toNumber();
sprite.tint = t;
相关技能： 
pixijs-scene-graphics
（填充/描边颜色）、
pixijs-scene-sprite
（色调）、
pixijs-blend-modes
（合成）。

Core Patterns

核心用法

Accepted input formats

支持的输入格式

ts
import { Color } from "pixi.js";

// Hex integer
new Color(0xff0000);

// Hex strings
new Color("#ff0000");
new Color("#f00");
new Color("ff0000");

// CSS color names
new Color("red");
new Color("dodgerblue");

// RGB/RGBA objects (components 0-255)
new Color({ r: 255, g: 0, b: 0 });
new Color({ r: 255, g: 0, b: 0, a: 0.5 });

// HSL/HSLA objects
new Color({ h: 0, s: 100, l: 50 });
new Color({ h: 0, s: 100, l: 50, a: 0.5 });

// HSV/HSVA objects
new Color({ h: 0, s: 100, v: 100 });

// CSS strings
new Color("rgb(255, 0, 0)");
new Color("rgba(255, 0, 0, 0.5)");
new Color("hsl(0, 100%, 50%)");

// Normalized 0-1 arrays (Float32Array or plain arrays)
new Color([1, 0, 0]); // RGB
new Color([1, 0, 0, 0.5]); // RGBA

// Uint8 arrays (components 0-255)
new Color(new Uint8Array([255, 0, 0]));
new Color(new Uint8ClampedArray([255, 0, 0, 128]));

// 8-digit hex with alpha
new Color("#ff0000ff");
new Color("#f00f");

// Copy from another Color instance
const red = new Color("red");
const copy = new Color(red);
ts
import { Color } from "pixi.js";

// Hex integer
new Color(0xff0000);

// Hex strings
new Color("#ff0000");
new Color("#f00");
new Color("ff0000");

// CSS color names
new Color("red");
new Color("dodgerblue");

// RGB/RGBA objects (components 0-255)
new Color({ r: 255, g: 0, b: 0 });
new Color({ r: 255, g: 0, b: 0, a: 0.5 });

// HSL/HSLA objects
new Color({ h: 0, s: 100, l: 50 });
new Color({ h: 0, s: 100, l: 50, a: 0.5 });

// HSV/HSVA objects
new Color({ h: 0, s: 100, v: 100 });

// CSS strings
new Color("rgb(255, 0, 0)");
new Color("rgba(255, 0, 0, 0.5)");
new Color("hsl(0, 100%, 50%)");

// Normalized 0-1 arrays (Float32Array or plain arrays)
new Color([1, 0, 0]); // RGB
new Color([1, 0, 0, 0.5]); // RGBA

// Uint8 arrays (components 0-255)
new Color(new Uint8Array([255, 0, 0]));
new Color(new Uint8ClampedArray([255, 0, 0, 128]));

// 8-digit hex with alpha
new Color("#ff0000ff");
new Color("#f00f");

// Copy from another Color instance
const red = new Color("red");
const copy = new Color(red);

Conversion methods

转换方法

ts
import { Color } from "pixi.js";

const color = new Color("#ff6600");

color.toHex(); // '#ff6600'
color.toHexa(); // '#ff6600ff' (hex with alpha)
color.toNumber(); // 0xff6600
color.toArray(); // [1, 0.4, 0, 1] (normalized RGBA)
color.toRgbArray(); // [1, 0.4, 0] (normalized RGB, no alpha)
color.toRgbaString(); // 'rgba(255,102,0,1)'
color.toRgba(); // { r: 1, g: 0.4, b: 0, a: 1 }
color.toRgb(); // { r: 1, g: 0.4, b: 0 }
color.toUint8RgbArray(); // [255, 102, 0]

// setValue() is the chainable way to change a color's value
color.setValue(0xff0000).toHex(); // '#ff0000'
ts
import { Color } from "pixi.js";

const color = new Color("#ff6600");

color.toHex(); // '#ff6600'
color.toHexa(); // '#ff6600ff' (hex with alpha)
color.toNumber(); // 0xff6600
color.toArray(); // [1, 0.4, 0, 1] (normalized RGBA)
color.toRgbArray(); // [1, 0.4, 0] (normalized RGB, no alpha)
color.toRgbaString(); // 'rgba(255,102,0,1)'
color.toRgba(); // { r: 1, g: 0.4, b: 0, a: 1 }
color.toRgb(); // { r: 1, g: 0.4, b: 0 }
color.toUint8RgbArray(); // [255, 102, 0]

// setValue() is the chainable way to change a color's value
color.setValue(0xff0000).toHex(); // '#ff0000'

Component access

组件访问

ts
import { Color } from "pixi.js";

const color = new Color("rgba(255, 128, 0, 0.8)");

color.red; // 1
color.green; // ~0.502
color.blue; // 0
color.alpha; // 0.8
All component getters return normalized 0-1 values.
ts
import { Color } from "pixi.js";

const color = new Color("rgba(255, 128, 0, 0.8)");

color.red; // 1
color.green; // ~0.502
color.blue; // 0
color.alpha; // 0.8
所有组件的getter返回0-1范围内的归一化值。

Manipulation

颜色操作

ts
import { Color } from "pixi.js";

const color = new Color("red");

// Set alpha (chainable)
color.setAlpha(0.5);

// Multiply with another color (destructive, modifies in place)
color.multiply(0x808080);

// Premultiply alpha (destructive, RGB channels multiplied by alpha)
color.premultiply(0.8);

// Premultiply alpha only (RGB unchanged)
color.premultiply(0.8, false);

// Chain operations
new Color("white").setAlpha(0.5).multiply([0.8, 0.2, 0.2]);
multiply()
and 
premultiply()
are destructive; they modify the color and set 
value
to null (original format is lost).
ts
import { Color } from "pixi.js";

const color = new Color("red");

// Set alpha (chainable)
color.setAlpha(0.5);

// Multiply with another color (destructive, modifies in place)
color.multiply(0x808080);

// Premultiply alpha (destructive, RGB channels multiplied by alpha)
color.premultiply(0.8);

// Premultiply alpha only (RGB unchanged)
color.premultiply(0.8, false);

// Chain operations
new Color("white").setAlpha(0.5).multiply([0.8, 0.2, 0.2]);
multiply()
和
premultiply()
是破坏性操作；它们会修改当前颜色实例，并将
value
设为null（原始格式会丢失）。

Non-destructive premultiplied output

非破坏性预乘输出

ts
import { Color } from "pixi.js";

const color = new Color("red").setAlpha(0.5);

const packed = color.toPremultiplied(color.alpha); // 0x7F7F0000
const alphaOnly = color.toPremultiplied(color.alpha, false); // 0x7FFF0000
toPremultiplied(alpha, applyToRGB?)
returns a 32-bit 
0xAARRGGBB
integer without mutating 
this
. Use it in batchers and tint math where the source color must be reused. When 
applyToRGB
is 
false
, only the alpha byte is packed; the RGB stays at its full value.
ts
import { Color } from "pixi.js";

const color = new Color("red").setAlpha(0.5);

const packed = color.toPremultiplied(color.alpha); // 0x7F7F0000
const alphaOnly = color.toPremultiplied(color.alpha, false); // 0x7FFF0000
toPremultiplied(alpha, applyToRGB?)
返回一个32位
0xAARRGGBB
整数，且不会修改当前实例。当需要重复使用源颜色时，可在批处理和色调计算中使用此方法。当
applyToRGB
为
false
时，仅打包alpha字节；RGB值保持原始的完整数值。

Reusing output buffers

复用输出缓冲区

ts
import { Color } from "pixi.js";

const rgba = new Float32Array(4);
const rgb = new Float32Array(3);
const rgb8 = new Uint8Array(3);

app.ticker.add(() => {
  Color.shared.setValue(sprite.tint).toArray(rgba).toRgbArray(rgb);

  Color.shared.toUint8RgbArray(rgb8);
});
toArray(out?)
, 
toRgbArray(out?)
, and 
toUint8RgbArray(out?)
accept a reusable 
number[]
, 
Float32Array
, 
Uint8Array
, or 
Uint8ClampedArray
and write into it. Pass your own buffer in hot paths to avoid allocating per frame; omit the argument and the 
Color
instance returns its internal cache array.
ts
import { Color } from "pixi.js";

const rgba = new Float32Array(4);
const rgb = new Float32Array(3);
const rgb8 = new Uint8Array(3);

app.ticker.add(() => {
  Color.shared.setValue(sprite.tint).toArray(rgba).toRgbArray(rgb);

  Color.shared.toUint8RgbArray(rgb8);
});
toArray(out?)
、
toRgbArray(out?)
和
toUint8RgbArray(out?)
接受可复用的
number[]
、
Float32Array
、
Uint8Array
或
Uint8ClampedArray
并写入数据。在性能敏感的路径中，传入你自己的缓冲区可避免每帧分配内存；若省略参数，
Color
实例会返回其内部缓存数组。

Packing for GPU buffers

为GPU缓冲区打包颜色

MethodReturns
toBgrNumber()
24-bit 
0xBBGGRR
integer with R/B swapped
toLittleEndianNumber()
Same 24-bit swap, convenient for little-endian vertex writes
Both are cheap and useful when emitting colors straight into packed vertex attributes.
MethodReturns
toBgrNumber()
24位
0xBBGGRR
整数，R/B通道交换
toLittleEndianNumber()
同样是24位通道交换，适用于小端字节序的顶点写入操作
这两种方法开销极低，在将颜色直接写入打包的顶点属性时非常实用。

Color.shared for temporary operations

使用Color.shared进行临时操作

ts
import { Color } from "pixi.js";

// One-off conversion without allocating a new Color
const hex = Color.shared.setValue("#ff6600").toNumber();
const arr = Color.shared.setValue(0xff0000).toArray();
Color.shared
is a singleton that avoids allocating a new 
Color
on every call. This matters in hot paths like render loops or per-frame tint calculations where repeated 
new Color()
creates GC pressure. Do not store references to it; other code may mutate it.
ts
import { Color } from "pixi.js";

// Good: reuse shared instance in a per-frame callback
app.ticker.add(() => {
  const t = performance.now() / 1000;
  sprite.tint = Color.shared
    .setValue("white")
    .multiply([Math.sin(t) * 0.5 + 0.5, 0.2, 0.8])
    .toNumber();
});
ts
import { Color } from "pixi.js";

// One-off conversion without allocating a new Color
const hex = Color.shared.setValue("#ff6600").toNumber();
const arr = Color.shared.setValue(0xff0000).toArray();
Color.shared
是一个单例对象，可避免每次调用时都分配新的
Color
实例。这在渲染循环或每帧色调计算等性能敏感路径中至关重要，因为重复调用
new Color()
会造成GC压力。请勿存储对它的引用；其他代码可能会修改它的值。
ts
import { Color } from "pixi.js";

// Good: reuse shared instance in a per-frame callback
app.ticker.add(() => {
  const t = performance.now() / 1000;
  sprite.tint = Color.shared
    .setValue("white")
    .multiply([Math.sin(t) * 0.5 + 0.5, 0.2, 0.8])
    .toNumber();
});

Validating input

输入验证

ts
import { Color } from "pixi.js";

Color.isColorLike("red"); // true
Color.isColorLike("#ff0000"); // true
Color.isColorLike(0xff0000); // true
Color.isColorLike([1, 0, 0]); // true
Color.isColorLike({ r: 1, g: 0, b: 0 }); // true
Color.isColorLike({ foo: 1 }); // false
Color.isColorLike(null); // false
Color.isColorLike()
checks the structural shape (string, number, array, or recognized object). It doesn't validate that a string is a real CSS color name, nor that array values fall in range. Use it as a type guard before passing user input to 
new Color()
or 
setValue()
.
ts
import { Color } from "pixi.js";

Color.isColorLike("red"); // true
Color.isColorLike("#ff0000"); // true
Color.isColorLike(0xff0000); // true
Color.isColorLike([1, 0, 0]); // true
Color.isColorLike({ r: 1, g: 0, b: 0 }); // true
Color.isColorLike({ foo: 1 }); // false
Color.isColorLike(null); // false
Color.isColorLike()
检查输入的结构类型（字符串、数字、数组或可识别的对象）。它不会验证字符串是否为有效的CSS颜色名称，也不会验证数组值是否在范围内。在将用户输入传递给
new Color()
或
setValue()
之前，可将其作为类型守卫使用。

Common Mistakes

常见误区

[MEDIUM] Expecting toRgba() to return 0-255 values

[MEDIUM] 期望toRgba()返回0-255范围的值

Wrong:
ts
import { Color } from "pixi.js";

const { r, g, b } = new Color({ r: 255, g: 128, b: 0 }).toRgba();
// r = 1, g = ~0.502, b = 0 (NOT 255, 128, 0)
Correct:
ts
import { Color } from "pixi.js";

// Use toUint8RgbArray() for 0-255 output
const [r, g, b] = new Color({ r: 255, g: 128, b: 0 }).toUint8RgbArray();
// r = 255, g = 128, b = 0
RGB object inputs use 0-255 range (
{ r: 255, g: 0, b: 0 }
), but all output methods (
toRgba()
, 
toRgb()
, 
toArray()
, 
toRgbArray()
) normalize to 0-1. Use 
toUint8RgbArray()
when you need 0-255 integers for CSS or external APIs.
错误示例：
ts
import { Color } from "pixi.js";

const { r, g, b } = new Color({ r: 255, g: 128, b: 0 }).toRgba();
// r = 1, g = ~0.502, b = 0 (NOT 255, 128, 0)
正确示例：
ts
import { Color } from "pixi.js";

// Use toUint8RgbArray() for 0-255 output
const [r, g, b] = new Color({ r: 255, g: 128, b: 0 }).toUint8RgbArray();
// r = 255, g = 128, b = 0
RGB对象输入使用0-255范围（
{ r: 255, g: 0, b: 0 }
），但所有输出方法（
toRgba()
、
toRgb()
、
toArray()
、
toRgbArray()
）都会归一化到0-1范围。当你需要为CSS或外部API提供0-255整数时，请使用
toUint8RgbArray()
。

[MEDIUM] Using 0-255 range in color arrays

[MEDIUM] 在颜色数组中使用0-255范围的值

Wrong:
ts
import { Color } from "pixi.js";

new Color([255, 0, 0]); // NOT red; values are interpreted as 0-1
Correct:
ts
import { Color } from "pixi.js";

new Color([1, 0, 0]); // red via normalized array
new Color(0xff0000); // red via hex
new Color("red"); // red via CSS name
new Color(new Uint8Array([255, 0, 0])); // red via Uint8Array (0-255)
Plain number arrays (
number[]
and 
Float32Array
) use normalized 0-1 range. 
[255, 0, 0]
clamps to 
[1, 0, 0]
because values are clamped, but 
[200, 100, 50]
does not produce the expected color. Use 
Uint8Array
or 
Uint8ClampedArray
for 0-255 input.
错误示例：
ts
import { Color } from "pixi.js";

new Color([255, 0, 0]); // NOT red; values are interpreted as 0-1
正确示例：
ts
import { Color } from "pixi.js";

new Color([1, 0, 0]); // red via normalized array
new Color(0xff0000); // red via hex
new Color("red"); // red via CSS name
new Color(new Uint8Array([255, 0, 0])); // red via Uint8Array (0-255)
普通数字数组（
number[]
和
Float32Array
）使用0-1的归一化范围。
[255, 0, 0]
会被钳位到
[1, 0, 0]
，但
[200, 100, 50]
无法生成预期的颜色。若要使用0-255范围的输入，请使用
Uint8Array
或
Uint8ClampedArray
。

[MEDIUM] Using utils.string2hex or utils.hex2string

[MEDIUM] 使用utils.string2hex或utils.hex2string

Wrong:
ts
import { utils } from "pixi.js";

const hex = utils.string2hex("#ff0000");
Correct:
ts
import { Color } from "pixi.js";

const hex = new Color("#ff0000").toNumber();
const str = new Color(0xff0000).toHex();
The 
utils
namespace was removed in v8. Use the 
Color
class for all color conversions.
错误示例：
ts
import { utils } from "pixi.js";

const hex = utils.string2hex("#ff0000");
正确示例：
ts
import { Color } from "pixi.js";

const hex = new Color("#ff0000").toNumber();
const str = new Color(0xff0000).toHex();
在v8版本中，
utils
命名空间已被移除。请使用
Color
类完成所有颜色转换操作。

API Reference

API参考