 方法详解：基于相对亮度计算 WCAG 对比度比率)
前端UI组件【免费下载链接】fastThe adaptive interface system for modern web experiences.项目地址https://gitcode.com/gh_mirrors/fa/fast点击查看免费下载Swatch.contrast()是 Microsoft FAST 组件库microsoft/fast-components中颜色体系Swatch / Palette的核心方法之一用于计算当前色样与目标颜色之间的对比度比率。本文将围绕该方法的方法签名、参数类型、返回值语义结合仓库内fast-components与fast-colors的 API 文档体系深入讲解其背后的相对亮度RelativeLuminance与 WCAG 2.0 对比度公式原理并展示它与Palette.colorContrast()、Palette.closestIndexOf()、isDark()等 API 的协同方式帮助你在 FAST 设计系统中正确实现可访问性配色与颜色决策。Swatch.contrast() 方法签名与参数解析Swatch.contrast()的完整定义记录在仓库文档 fast-components.swatch.contrast.md 中其 API 签名如下contrast(target: RelativeLuminance): number;该签名包含三个关键要素要素类型说明方法名contrast计算当前 Swatch 与目标颜色之间的对比度比率参数targetRelativeLuminance作为对比参照的目标颜色只需满足相对亮度接口约定返回值number对比度比率对比度比值数值越大表示两色之间的对比越强参数约束target的类型是RelativeLuminance而非Swatch本身这意味着任何实现了相对亮度计算能力的颜色对象都可以作为对比参照——这一点正是对比度计算只依赖颜色的亮度分量、与色相/饱和度无关的本质体现详见下文相对亮度小节。Swatch 接口contrast 方法所属的上下文contrast()方法定义在Swatch接口之上。根据 fast-components.swatch.md 的定义export interface Swatch extends RelativeLuminanceSwatch接口描述为Represents a color in a Palette表示一个色板中的颜色它直接继承自RelativeLuminance这从接口层面保证了每个 Swatch 都具备计算相对亮度的能力而contrast()正是建立在这一能力之上的。除contrast()外Swatch接口还定义了另一个方法 toColorString()toColorString(): string;用于将 Swatch 转换为可写入 CSS 的颜色字符串与contrast()的数值计算形成互补一个负责算对比度一个负责产出最终颜色值。在实际使用中Swatch最常见的实现是SwatchRGB。根据 fast-components.swatchrgb.md它提供了工厂方法用于构造 RGB 色样SwatchRGB: Readonly{ create(r: number, g: number, b: number): SwatchRGB; from(obj: { r: number; g: number; b: number; }): SwatchRGB; }即通过SwatchRGB.create(r, g, b)或SwatchRGB.from({ r, g, b })即可创建一个可用于调用contrast()的 Swatch 实例。RelativeLuminance 与 target 参数相对亮度是什么contrast()的参数类型RelativeLuminance相对亮度是 WCAG 对比度计算的基础。仓库中 fast-colors.rgbtorelativeluminance.md 提供了对应的底层函数export declare function rgbToRelativeLuminance(rgb: ColorRGBA64): number;该函数文档明确说明Get the relative luminance of a color. Adjusts the color to sRGB space, which is necessary for the WCAG contrast spec. The alpha channel of the input is ignored.获取颜色的相对亮度。将颜色调整到 sRGB 空间这对于 WCAG 对比度规范是必要的。输入的 alpha 通道会被忽略。需要注意区分的是线性 RGB 亮度。仓库文档 fast-colors.rgbtolinearluminance.md 定义export declare function rgbToLinearLuminance(rgb: ColorRGBA64): number;其说明强调Get the luminance of a color in the linear RGB space. This is not the same as the relative luminance in the sRGB space for WCAG contrast calculations. Use rgbToRelativeLuminance instead.获取线性 RGB 空间中的亮度。这与用于 WCAG 对比度计算的 sRGB 空间相对亮度不同请改用rgbToRelativeLuminance。这两者的区别对理解contrast()至关重要相对亮度RelativeLuminance在 sRGB 颜色空间下、经过伽马校正的亮度值取值范围为 0最暗到 1最亮是 WCAG 对比度公式的直接输入线性亮度Linear Luminance未经 sRGB 伽马校正的中间计算值主要用于色彩科学计算不能直接用于 WCAG 对比度计算。因此当你在 FAST 中向contrast(target)传入目标色样时系统实际依赖的是该色样的相对亮度sRGB 空间而非线性亮度同时 alpha 通道不会参与计算。contrast 的返回值WCAG 2.0 对比度公式contrast()返回number类型即两个颜色之间的对比度比率。仓库中 fast-colors.contrastratio.md 给出了同构的独立函数定义export declare function contrastRatio(a: ColorRGBA64, b: ColorRGBA64): number;该函数说明指出Calculate the contrast ratio between two colors. Uses the formula described by WCAG 2.0计算两种颜色之间的对比度比率使用 WCAG 2.0 描述的公式其 Remarks 同样注明 alpha 通道被忽略。依据 WCAG 2.0 的对比度定义这也是contrast()与contrastRatio()共用的计算语义对比度比率由两个颜色相对亮度记为较亮的L1与较暗的L2按如下关系得出contrast ratio (L1 0.05) / (L2 0.05)由此可以推导出对比度比率的关键特性取值范围介于 1两色亮度相同无对比与 21纯黑与纯白之间与亮度的关系对比度完全由相对亮度决定与色相无关——例如同为中亮度的红与绿可能对比度很低而亮色与暗色的对比度必然较高可访问性阈值行业通用标准可用于校验返回值WCAG AA 要求普通文本 ≥ 4.5:1、大文本 ≥ 3:1AAA 要求普通文本 ≥ 7:1。在 FAST 组件体系中contrast()的返回值通常被用于判断某前景色放在某背景色上是否可读这也是后续一系列 Recipe颜色配方与状态色hover/active/focus算法的基础。与 Palette 颜色系统的协同从对比度到色样选取Swatch.contrast()不是孤立存在的——它服务于 FAST 的Palette色板系统。根据 fast-components.palette.mdexport interface PaletteT extends Swatch SwatchPalette被描述为 A collection of Swatch instances一组 Swatch 实例的集合拥有source与swatchesReadonlyArrayT两个属性并提供三个方法closestIndexOf(reference)返回色板中与传入RelativeLuminance相对亮度最接近的色样索引closestIndexOf(reference: RelativeLuminance): number;colorContrast(reference, contrast, initialIndex, direction)Returns a swatch from the palette that most closely matches the contrast ratio provided to a provided reference返回色板中与给定参照色之间对比度比率最接近所要求比率的色样colorContrast(reference: Swatch, contrast: number, initialIndex?: number, direction?: 1 | -1): T;参数initialIndex指定搜索起点索引可选direction指定在色板中向亮侧1或暗侧-1搜索的方向可选。get(index)Gets a swatch by index. Index is clamped to the limits of the palette so a Swatch will always be returned.按索引获取色样。索引会被钳制到色板边界内因此始终能返回一个色样get(index: number): T;这一组方法构成了完整的对比度工作流先用closestIndexOf()在色板中定位参照色位置再通过colorContrast()结合目标对比度即Swatch.contrast()能产出的那种比率与搜索方向在色板中选出满足可访问性要求的具体色样最后用get()安全取出。Swatch.contrast()在其中扮演度量工具的角色为色样选取提供量化依据。实战方向用 contrast 驱动暗色模式与可访问性配色在 FAST 1.x 的设计系统实践中Swatch.contrast()的典型应用场景集中在以下方面1. 判断明暗模式。仓库提供了 isDark(color) 函数Determines if a color should be considered Dark Mode判断一个颜色是否应被视为暗色模式export declare function isDark(color: Swatch): boolean;该判断本质上是基于颜色的相对亮度阈值进行的而相对亮度正是contrast()计算的基础分量。2. 计算可读的前景色/背景色组合。对任意一组 Swatch 调用contrast()得到比率后可对照 WCAG 的 4.5:1 / 3:1 等阈值决定该组合是否可用于正文或大号文本。3. 生成状态色与层色。fast-components模块暴露了大量依赖对比度算法的设计令牌design tokens例如 fast-components.md 中列出的accentFillRecipe、neutralForegroundRest、neutralFillStealthRest、focusStrokeInner、foregroundOnAccentRest等变量——这些Recipe在运行时通过色板与对比度算法动态求出符合可访问性要求的实际颜色值Swatch.contrast()正是其中度量环节的一部分。你可以围绕Palette.colorContrast(reference, contrast, initialIndex, direction)自行组合出在给定背景上找对比度达标的前景色的实用逻辑。小结Swatch.contrast()虽然是一个单方法 API但它在 FAST 组件颜色体系中处于承上启下的位置承上作为Swatch接口继承自RelativeLuminance的能力成员它把色样与亮度/对比度量统一起来启下其返回的对比度比率是Palette.colorContrast()选取色样的目标值也是isDark()、各类颜色 Recipe 判定可读性的依据原理本质基于 sRGB 空间的相对亮度按 WCAG 2.0 公式(L1 0.05) / (L2 0.05)计算忽略 alpha 通道。相关 API 文档可继续在仓库 sites/website/src/docs/1.x/api 目录下查阅推荐按以下顺序深入Swatch 接口 → Palette 接口 → Palette.colorContrast() → contrastRatio() → rgbToRelativeLuminance()。赞分享前端UI组件【免费下载链接】fastThe adaptive interface system for modern web experiences.项目地址https://gitcode.com/gh_mirrors/fa/fast点击查看免费下载相关推荐FAST 颜色系统中 rgbToRelativeLuminance() 详解WCAG 相对亮度计算与对比度合规FAST 颜色系统中 rgbToRelativeLuminance 详解WCAG 相对亮度计算与对比度合规 rgbToRelativeLuminance 是前端UI组件深入解析 fast-colors 的 contrastRatio() 函数基于 WCAG 2.0 的颜色对比度计算深入解析 fast colors 的 contrastRatio 函数基于 WCAG 2.0 的颜色对比度计算 导读 contrastRatio 是 FAST前端UI组件OpenPose姿态相似度计算基于关键点距离的动作比对算法OpenPose姿态相似度计算基于关键点距离的动作比对算法 OpenPose作为业界领先的实时多人姿态估计库其强大的关键点检测能力为动作识别和姿态分析提供了人工智能计算机视觉深度学习上一篇vite-plugin-vue-inspector高级API指南自定义快捷键与扩展功能开发下一篇VoxCPM2语音合成终极指南无需分词器的30种语言语音生成与高保真克隆技术创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考
