# 对比度

> 在 React 或原生 JavaScript 中检查颜色对比度：用 APCA 选出易读的文字颜色，并按 WCAG AA 和 AAA 标准检测一组颜色。

Source: https://chroma-panel.jscrate.dev/zh/react/utils/contrast
Last updated: 2026-09-21

对比度辅助函数可以为背景选出合适的文字颜色，或者按 WCAG 检测一组颜色。每个函数都接受 HSVA 值，或任何 [parse](https://chroma-panel.jscrate.dev/zh/react/utils/parsing) 支持的字符串。这些函数在 React 和原生 JavaScript 中都能用。

不依赖 React 也能使用：

```ts
import { contrastReport, readableTextColor } from "chroma-panel/contrast";
```

## 选择文字颜色

```ts
readableTextColor("#001f3f"); // '#ffffff'
```

默认在黑色和白色之间选择。传入 `dark` 和 `light`，就会改为在你自己的一对颜色之间选择。

```ts
function readableTextColor(background: string | Hsva, options?: {
  dark?: string;
  light?: string;
}): string
```

Picks black or white for text on the given background. Uses APCA rather than plain luminance, so it chooses white over mid-blues where the older method wrongly picks black.

## 检测一组颜色

WCAG 检查采用标准阈值：普通文字 AA 级为 4.5:1，AAA 级为 7:1；大号文字分别放宽到 3:1 和 4.5:1；UI 组件为 3:1。

`wcagLevel` 只根据对比度返回 `'AAA'`、`'AA'`、`'AA Large'` 或 `'Fail'`，并会在开发环境中提示它已弃用。建议改用 `meetsContrast`，并传入 `level` 和 `size`。

```ts
function contrastReport(a: string | Hsva, b: string | Hsva): ContrastReport
```

Everything WCAG says about a pair of colors at once: the contrast ratio, which text levels it passes at normal and large sizes, and whether it passes for non-text UI.

```ts
function contrastRatio(a: string | Hsva, b: string | Hsva): number
```

The WCAG 2.1 contrast ratio, from 1 to 21.

```ts
function meetsContrast(a: string | Hsva, b: string | Hsva, options: ContrastOptions): boolean
```

Whether a pair clears a WCAG level for text. The thresholds are 4.5:1 for AA and 7:1 for AAA, relaxed for large text.

```ts
function meetsNonTextContrast(a: string | Hsva, b: string | Hsva): boolean
```

Whether a pair clears the 3:1 threshold WCAG applies to UI components and graphical objects rather than text.

```ts
function wcagLevel(a: string | Hsva, b: string | Hsva): WcagLevel
```

The highest WCAG level a pair reaches, rather than a yes or no against one threshold.

## 底层的度量方法

```ts
function apcaContrast(text: string | Hsva, background: string | Hsva): number
```

The APCA lightness contrast, which models perceived contrast better than the WCAG ratio, particularly for light text on dark grounds.

```ts
function relativeLuminance(color: string | Hsva): number
```

The WCAG relative luminance of a color, the quantity the contrast ratio is built from.

> **为什么用 APCA 选文字颜色**
>
> `readableTextColor` 用的是
> APCA，而不是单纯比较亮度。遇到中等明度的蓝色，它会选白色，而旧方法会错选黑色。