 方法)
前端UI组件【免费下载链接】fastThe adaptive interface system for modern web experiences.项目地址https://gitcode.com/gh_mirrors/fa/fast点击查看免费下载导读Palette.colorContrast()是 FAST 设计系统microsoft/fast-components中负责按对比度目标查找色板的核心方法给定一个参考颜色Swatch和一个对比度数值如 WCAG 要求的 4.5:1它会从当前调色板中返回最接近该对比度目标的颜色。本文将以该方法为主线串联Palette接口的完整能力source、swatches、closestIndexOf、get并配合Swatch、SwatchRGB、PaletteRGB等配套 API讲解如何在自定义组件与设计系统中实现符合可访问性标准的动态取色。读完后你将掌握该方法每个参数的含义与典型取值、其与调色板其他方法的配合方式以及基于调色板构建自适应对比度配色方案的完整思路。Palette 接口colorContrast 的宿主colorContrast是Palette接口 上定义的方法。Palette被描述为 A collection of Swatch instances——即一组Swatch实例的集合是 FAST 设计系统中一切颜色计算的基础数据结构。其完整签名如下export interface PaletteT extends Swatch Swatch它是一个泛型接口默认类型参数T为Swatch。接口上同时暴露了三个方法和一个get方法整体结构为成员类型说明sourcereadonly T生成该调色板的源色种子颜色swatchesreadonly ReadonlyArrayT调色板中包含的全部色板按亮度有序排列closestIndexOf(reference: RelativeLuminance): number方法返回与给定RelativeLuminance相对亮度最接近的色板索引colorContrast(reference, contrast, initialIndex?, direction?)方法返回与参考色对比度最接近的色板get(index: number): T方法按索引取色板索引会自动钳制clamp到调色板边界保证永远返回一个有效色板从文档描述可以推断colorContrast与closestIndexOf、get构成了调色板检索能力的完整闭环closestIndexOf按亮度检索colorContrast按对比度检索get则提供带边界保护的索引访问。这种设计使得上层组件可以完全不关心调色板内部有多少个色板、亮度步长是多少只需按语义目标亮度或对比度取色即可。colorContrast 方法签名与参数详解Palette.colorContrast()方法文档 给出的官方描述为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;各参数含义如下表参数类型必填说明referenceSwatch是作为对比度计算基准的参考颜色如组件所在层的背景色contrastnumber是期望达到的对比度目标值通常为 WCAG 对比度比值如 3:1、4.5:1、7:1initialIndexnumber否搜索的起始索引用于给出检索的起点提示direction1 \| -1否搜索方向1表示向调色板亮端索引增大方向搜索-1表示向暗端索引减小方向搜索返回值为T默认即Swatch——即满足对比度目标的最匹配色板。关键参数contrast对比度目标contrast参数对应的是Swatch上contrast(target: RelativeLuminance): number方法见 Swatch 接口文档 与 Swatch.contrast() 方法文档计算出的对比度比值。FAST 的色彩体系遵循 WCAG 对比度算法实践中常用目标值包括3:1WCAG AA 对大型文本18px 以上或 14px 加粗及 UI 组件边界的最低要求4.5:1WCAG AA 对普通文本的最低要求也是大多数文本前景色选择的默认目标7:1WCAG AAA 对普通文本的增强要求。传入的目标值越大返回的色板与参考色的明度差异就越大目标值越小返回的色板就越接近参考色自身。关键参数initialIndex 与 direction搜索起点与方向initialIndex和direction是成对使用的可选参数。可以推断该方法的内部实现是在有序调色板swatches按亮度排列上进行定向搜索从initialIndex位置出发沿着direction指定的方向逐色板计算与reference的对比度直到跨越目标对比度为止。这对参数的价值在于性能与稳定性提供合理的initialIndex可以显著缩小搜索区间避免每次都从调色板一端开始全量扫描direction决定了在参考色两侧更亮或更暗中选取哪一侧的色板。例如当参考色是深色背景时通常以direction: 1向亮端寻找前景色反之以direction: -1向暗端寻找。配套 APISwatch、SwatchRGB 与 PaletteRGB要实际使用colorContrast必须先理解它依赖的Swatch与两个工厂对象。Swatch调色板中的基本色Swatch接口文档 将Swatch定义为 Represents a color in a Palette其签名export interface Swatch extends RelativeLuminance表明它继承了RelativeLuminance相对亮度因此任何Swatch都可以直接参与亮度与对比度计算。Swatch还定义了两个方法contrast(target: RelativeLuminance): number计算当前色与目标色的对比度比值见 Swatch.contrast()toColorString(): string将色板转换为可用于 CSS 的颜色字符串如#RRGGBB或rgb(...)见 Swatch.toColorString()。SwatchRGBRGB 色板的工厂SwatchRGB变量文档 给出其签名SwatchRGB: Readonly{ create(r: number, g: number, b: number): SwatchRGB; from(obj: { r: number; g: number; b: number; }): SwatchRGB; }它提供了两种创建 RGB 色板的方式create(r, g, b)直接以三个 0~1 范围的数值创建from(obj)则接受{ r, g, b }对象。这通常在把十六进制颜色解析为可参与亮度计算的结构时使用。PaletteRGB调色板的工厂PaletteRGB变量文档 给出其签名PaletteRGB: Readonly{ create: typeof create; from: typeof from; }PaletteRGB是对应SwatchRGB的调色板工厂负责从源色生成一条有序的 RGB 调色板。在设计系统初始化阶段通常就是通过它创建neutralPalette与accentPalette两条核心调色板在 fast-components API 总览 中可以看到neutralPalette、accentPalette等导出的调色板变量。实战用 colorContrast 构建自适应文本前景色下面是一个将上述 API 组合使用的典型场景根据任意背景色从调色板中选取满足对比度要求的前景文本色。import { Palette, PaletteRGB, Swatch, SwatchRGB, isDark, } from microsoft/fast-components; // 1. 从源色生成调色板 const accentPalette: Palette PaletteRGB.create( SwatchRGB.create(0.33, 0.44, 0.78) // 以 0~1 范围的 RGB 作为源色 ); // 2. 传入背景色与目标对比度获取满足要求的前景色 function pickForeground( palette: Palette, background: Swatch, targetContrast: number ): Swatch { // 背景偏暗则向亮端找前景背景偏亮则向暗端找前景 const direction: 1 | -1 isDark(background) ? 1 : -1; return palette.colorContrast(background, targetContrast, undefined, direction); } // 3. 使用示例在深色背景上寻找 4.5:1 的文本色 const background SwatchRGB.create(0.05, 0.05, 0.1); const textColor pickForeground(accentPalette, background, 4.5); // 4. 应用到样式 element.style.color textColor.toColorString();其中isDark(color: Swatch): boolean是 fast-components 提供的辅助函数见 isDark() 函数文档用于判断颜色是否属于暗色模式据此选择搜索方向。这是colorContrast中direction参数最常见的用法。与其他调色板方法的配合closestIndexOf 与 getcolorContrast返回的色板后续通常会落到get(index)或closestIndexOf()的配合使用中closestIndexOf(reference: RelativeLuminance): number返回与参考亮度最接近的色板索引。当colorContrast找不到精确满足目标的色板时这是常态因为调色板是离散的其结果本质上也是最接近的近似值——两者配合可以在按亮度定位与按对比度定位两种检索语义间自由切换get(index: number): T按索引取色且索引会被自动钳制到调色板边界a Swatch will always be returned因此即使在动态计算索引时越界也不会返回undefined。这在把colorContrast的结果进一步按状态rest / hover / active做偏移delta取值时非常有用。从文档描述推断colorContrast的内部实现很可能复用了closestIndexOf所基于的有序性——正因为swatches按亮度有序排列对比度随索引呈单调变化找到最接近目标对比度的索引才能在O(log n)级别完成这也是initialIndex与direction两个提示参数存在的意义。使用注意与边界基于 API 文档与类型定义使用colorContrast时有几点需要留意对比度目标是近似值而非精确值文档明确使用 most closely matches最接近匹配表述即调色板是离散色板序列无法保证返回色板与参考色的对比度恰好等于目标值只能保证是全部色板中与该目标最接近的一个。若业务上必须严格达到某个 WCAG 级别建议在取值后自行用contrast()复核或选择略高于目标的contrast值作为安全余量direction只接受1 | -1类型签名限制了仅两个合法取值分别对应向亮端索引增大与向暗端索引减小搜索传其他数值属于类型错误initialIndex是可选优化参数不传时方法也能工作但传入接近目标色板位置的索引可以让搜索更快、结果更可预测颜色空间该 API 系列基于 RGB见SwatchRGB的r/g/b通道且Swatch继承RelativeLuminance因此对比度计算遵循标准相对亮度定义适用于 WCAG 场景但在高饱和特殊色上仍需结合目视验证。延伸阅读Palette 接口总览source、swatches属性及三个检索方法Palette.closestIndexOf() 与 Palette.get()按亮度检索与安全索引取值Swatch 接口 及 Swatch.contrast()对比度计算的底层实现入口SwatchRGB 与 PaletteRGBRGB 色板与调色板的工厂fast-components API 总览neutralPalette、accentPalette等调色板变量以及isDark辅助函数的完整索引。赞分享前端UI组件【免费下载链接】fastThe adaptive interface system for modern web experiences.项目地址https://gitcode.com/gh_mirrors/fa/fast点击查看免费下载相关推荐FAST Components 调色板接口Palette深度解析Swatch 取色与对比度算法实战FAST Components 调色板接口Palette深度解析Swatch 取色与对比度算法实战 本文围绕 microsoft/fast compon前端UI组件FAST 库 microsoft/fast-colors 中 QuantizeConfig.fractionByPopulation 参数详解让高对比度小面积颜色进入最终调色板FAST 库 microsoft/fast colors 中 QuantizeConfig.fractionByPopulation 参数详解让高对比度小面前端UI组件深入解析 FAST 组件库 Palette.closestIndexOf()按相对亮度定位色板索引深入解析 FAST 组件库 Palette.closestIndexOf 按相对亮度定位色板索引 导读 Palette.closestIndexOf 是 m前端UI组件上一篇探秘交互叙事的未来inkjs - 编程语言ink的JavaScript实现下一篇CANN算子模板AddExample创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考
