tomloprod/colority

Colority是一个轻量级的PHP库，可轻松处理颜色转换、验证和操作。

维护者

详细信息

github.com/tomloprod/colority

源代码

问题

资助包维护！
www.paypal.com/paypalme/tomloprod

安装: 427

依赖项: 0

建议者: 0

安全: 0

星标: 75

关注者: 2

分支: 1

开放问题: 1

v1.1.1 2024-06-03 16:34 UTC

Requires

Requires (Dev)

MIT af84fd72f114bda4878c81a53a3e1e85e2a71f12

  • Tomás López <tomloprod.woop@gmail.com>

utilitycolorsconversion-utiliywcag-contrast

This package is auto-updated.

Last update: 2024-09-08 21:15:26 UTC

README

GitHub Workflow Status (master) Total Downloads Latest Version License

🎨 关于Colority

Colority是一个轻量级的PHP库，可轻松处理颜色转换、验证和操作。

它允许您根据颜色格式（RGB, HSL, 十六进制）实例化具体对象，并从一个格式转换为另一个格式。

此外，它还允许您检查背景颜色是否满足WCAG 2.0可访问性标准，关于文本和UI中的颜色对比度比。

此外，它包括以下多个功能：

  • 它允许您获取图像中的颜色
  • 生成背景颜色的最佳前景颜色（白色、黑色或用户提供的列表中的颜色），确保最佳可能的对比度比。（例如，在彩色徽章上提高文本可见性非常重要）。
  • 根据字符串生成一个固定的颜色。例如，生成与用户名相关的颜色很有用。
  • 允许您获取与给定颜色类似的一个随机颜色。

✨ 快速入门

实例化Color对象

您可以将值颜色（字符串或，根据颜色类型，数组）转换为特定的Color对象。

/** @var RgbColor $rgbColor */
$rgbColor = colority()->fromRgb('rgb(255,255,255)');
$rgbColor = colority()->fromRgb('255,255,255'); 
$rgbColor = colority()->fromRgb([255, 255, 255]); 

/** @var HexColor $hexColor */
$hexColor = colority()->fromHex('#51B389');
$hexColor = colority()->fromHex('51B389'); 
$hexColor = colority()->fromHex('#ABC');

/** @var HslColor $hslColor */
$hslColor = colority()->fromRgb('hsl(168.31deg, 49.58%, 46.67%)');
$hslColor = colority()->fromRgb('168.31, 49.58, 46.67'); 
$hslColor = colority()->fromRgb([168.31, 49.58, 46.67]);

如果您无法指定值颜色的原始格式，您可以使用parse方法。这将检测它是什么类型的颜色，并实例化一个新对象，或者如果接收到的字符串不匹配任何类型的颜色，则返回NULL

/** @var RgbColor|null $rgbColor */
$rgbColor = colority()->parse('rgb(255,255,255)');

/** @var HexColor|null $hexColor */
$hexColor = colority()->parse('#51B389');

/** @var HslColor|null $hslColor */
$hslColor = colority()->parse('hsl(168.31deg, 49.58%, 46.67%)');

对比度比（WCAG 2.0标准）

当您拥有Color对象时，您将能够使用所有它的方法。以下，我们描述了其中两个与对比度比相关的方法。

getBestForegroundColor

返回一个具有最合适的前景颜色（使用亮度对比度比算法）的Color对象。

您可以将包含Color对象的数组作为参数传递，以便选择具有最佳对比度比的前景颜色。如果没有指定参数，则默认为白色或黑色。

/** @var HexColor $hexColor */
$hexColor = colority()->fromHex('#51B389');

/** @var HexColor $bestForegroundHexColor (black or white) */
$bestForegroundHexColor = $hexColor->getBestForegroundColor();

/** @var HexColor $bestForegroundHexColor (#A63F3F, #3FA684 or #6E3FA6) */
$bestForegroundHexColor = $hexColor->getBestForegroundColor([
    new HexColor('#A63F3F'),
    new HexColor('#3FA684'),
    new HexColor('#6E3FA6'),
]);

getContrastRatio

返回调用此方法的颜色与作为参数传递的颜色之间的对比度比（值越高，对比度越好，值越低，对比度越差）。如果没有传递颜色作为参数，则将确定与黑色作为前景的对比度比。

/** @var HexColor $hexColor */
$hexColor = colority()->fromHex('#51B389');

/** @var float $contrastRatio Contrast ratio with black as the foreground color. */
$contrastRatio = $hexColor->getContrastRatio();

/** @var float $contrastRatio Contrast ratio with #3FA684 as the foreground color. */
$contrastRatio = $hexColor->getContrastRatio(new HexColor('#3FA684'));

AA & AAA WCAG级别

以下我们向您展示如何使用Tomloprod\Colority\Support\Algorithms\ContrastRatioScore检查对比度比是否满足WCAG AA和AAA级别。

/** @var HexColor $hexColor */
$hexColor = colority()->fromHex('#51B389');

/**
 * The `getContrastRatio` method can take a `Color` object as the foreground 
 * to calculate the contrast ratio against that color. Black is used by default.
 * 
 * @var float $contrastRatio
 */
$contrastRatio = $hexColor->getContrastRatio();

/**
 * AA Level for texts
 */
$passsesAALevelForLargeText = ContrastRatioScore::passesTextAALevel(
    contrastRatio: $contrastRatio,
    largeText: true
);

$passsesAALevelForNormalText = ContrastRatioScore::passesTextAALevel(
    contrastRatio: $contrastRatio,
    largeText: false
);

/**
 * AAA Level for texts
 */
$passsesAAALevelForLargeText = ContrastRatioScore::passesTextAAALevel(
    contrastRatio: $contrastRatio,
    largeText: true
);

$passsesAAALevelForNormalText = ContrastRatioScore::passesTextAAALevel(
    contrastRatio: $contrastRatio,
    largeText: false
);
/**
 * AA Level for Graphical Objects and User Interface Components
 */
$passsesAALevelForUI = ContrastRatioScore::passesUIAALevel(
    $contrastRatio
);

颜色验证

具体的Color类有一个名为getParser()的静态方法，它返回一个ValueColorParser的实例。

parse方法返回一个字符串，其中包含适合与Colority一起工作的值颜色，或者当它无效时抛出InvalidArgumentException。

/** @var ValueColorParser $hexParser */
$hexParser = HexColor::getParser();

// will throw InvalidArgumentException
$valueColor = $hexParser->parse('Not a valid value color'); 

// will return #FFFFFF
$valueColor = $hexParser->parse('#FFF');

您可以使用特定解析器为任何类型的颜色

$hslParser = HslColor::getParser();

$rgbParser = RgbColor::getParser();

$hexParser = HexColor::getParser();

颜色转换

Colority允许您将颜色对象转换为任何其他所需格式的Color对象。

/** @var HexColor|null $hexColor */
$hexColor = colority()->fromHex('#51B389');

/** @var HexColor $hexColor */
$hexColor = $hexColor->toHex();

/** @var RgbColor $rgbColor */
$rgbColor = $hexColor->toRgb();

/** @var HslColor $hslColor */
$hslColor = $hexColor->toHsl();

颜色工具

getImageColors

它允许您获取图像中检测到的颜色。必须提供图像的路径作为第一个参数。

它有一个可选的第二个参数（默认为5），指定要返回的颜色数量。

getImageColors gif

/** @var array<RgbColor> $imageColors */
$imageColors = colority()->getImageColors(
    imagePath: __DIR__.'/image-colors.png',
    desiredNumColors: 10
);

textToColor

基于字符串生成固定颜色。

getSimilarColor gif

/** @var HslColor $hslColor */
$hslColor = colority()->textToColor("Hi, I'm Tomás");

🧙 建议 对于生成与用户名、电子邮件地址等相关的颜色非常有用，因为字符串总是返回相同的颜色。

getSimilarColor

允许您获取与给定颜色相似（在同一调色板中）的随机颜色。

getSimilarColor gif

/** @var HexColor|null $hexColor */
$hexColor = colority()->fromHex('#51B389');

/** @var HexColor|null $similarHexColor */
$similarHexColor = colority()->getSimilarColor($hexColor);

Colority 的使用方法

您可以使用别名 colority() 使用 Colority。

/** @var HexColor $hexColor */
$hexColor = colority()->fromHex('#CCC');

或直接调用 Colority 面板的静态方法

/** @var HexColor $hexColor */
$hexColor = Colority::fromHex('#CCC');

您决定如何使用它 ☺️

🧱 架构

Colority 由几种类型的元素组成。以下是这些元素的一些特性。

Colority

Tomloprod\Colority\Support\Facades\Colority 是一个面板，充当使用 Colority 其他元素的简化接口。

方法

Colority::parse(string $valueColor): Color|null

Colority::fromHex(string $hexValue): HexColor

Colority::fromRgb(string|array<int> $rgbValue): RgbColor

Colority::fromHsl(string|array<float> $hslValue): HslColor

Colority::textToColor(string $text): HslColor

Colority::getSimilarColor(Color $color, int $hueRange = 30, int $saturationRange = 10, int $lightnessRange = 10): Color

颜色

所有具体颜色类都扩展了抽象类 Color。具体颜色类

  • Tomloprod\Colority\Colors\HexColor
  • Tomloprod\Colority\Colors\HslColor
  • Tomloprod\Colority\Colors\RgbColor

方法

/** @var HexColor $hexColor */
$hexColor = Colority::fromHex('#CCCCCC');

$hexColor->toHex(): HexColor;
$hexColor->toRgb(): RgbColor;
$hexColor->toHsl(): HslColor;

// Returns the value color in string format. Example: #CCCCCC
$hexColor->getValueColor(): string;

对于 HslColor 和 RgbColor 对象，您还有一个方法 getArrayValueColor，它将以数组格式返回值颜色。

/** @var RgbColor $rgbColor */
$rgbColor = Colority::fromRgb('255,255,255');

/** @var array $arrayValueColor [255,255,255] */
$arrayValueColor = $rgbColor->getArrayValueColor();

另一方面，HslColor 对象还有一个名为 getValueColorWithMeasureUnits 的额外方法，它返回带有测量单位的价值颜色（例如，用于 CSS 样式）。

/** @var HslColor $hslColor */
$hslColor = Colority::fromHsl('hsl(32.4, 60.48, 51.37)');

/** @var string $valueColorWithMeasureUnits hsl(32.4deg,60.48%,51.37%) */
$valueColorWithMeasureUnits = $hslColor->getValueColorWithMeasureUnits();

/** @var string $valueColor hsl(32.4,60.48,51.37) */
$valueColor = $hslColor->getValueColor(): string;

🚀 安装 & 要求

需要 PHP 8.2+

您可以使用 Composer 将 Colority 安装到您的 PHP 项目中

composer require tomloprod/colority

🧑‍🤝‍🧑 贡献

欢迎贡献，并通过拉取请求接受。请在提交任何拉取请求之前审查这些指南。

Colority 由 Tomás López 创建，并开源于 MIT 许可证 下。