fast-colors ColorScale.createBalancedColorScale()：用一组颜色快速构建平衡色阶的完整指南

前端UI组件【免费下载链接】fastThe adaptive interface system for modern web experiences.项目地址https://gitcode.com/gh_mirrors/fa/fast点击查看免费下载导读ColorScale.createBalancedColorScale()是 FAST Design System 的颜色工具库microsoft/fast-colors1.x 版本中ColorScale类提供的一个静态工厂方法它接受一组ColorRGBA64颜色作为输入返回一个基于线性色标linear stops构建的ColorScale实例帮助开发者用最少的样板代码把任意一组离散颜色转换为可在 0–1 区间内连续取色的色阶。读完本文你将掌握该方法的精确签名、参数与返回类型、底层ColorScale/ColorRGBA64/ColorScaleStop类型模型以及如何与getColor()、trim()、findNextColor()等成员组合出可复用的色板工具。一、方法签名与定位createBalancedColorScale()是ColorScale类的静态方法可以直接在类上调用无需先构造实例。它由 API Documenter 自动生成并收录在官方 1.x API 参考中完整签名如下static createBalancedColorScale(colors: ColorRGBA64[]): ColorScale;在类结构中的位置见 ColorScale 类文档该方法属于ColorScale的全部方法集合clone()、createBalancedColorScale()、findNextColor()、getColor()、trim()它是其中唯一标记为static静态的方法其余均为实例方法返回类型为ColorScale即该方法产出的是一个完整可用的色阶对象而不是裸的颜色数组或回调函数。从 API 设计可以推断与实例构造器不同静态工厂方法无需关心色标stop的摆放细节只需提供颜色本身方法内部会负责把输入颜色平衡地分布到色阶的线性位置上从而得到一条平滑过渡的连续色阶。二、参数与返回类型详解2.1 参数表原文档fast-colors.colorscale.createbalancedcolorscale.md给出的参数定义如下参数类型说明colorsColorRGBA64[]用于构建色阶的一组颜色通道值为 64 位精度的 RGBA 颜色返回值为 ColorScale 类型即一个由线性色标创建的色阶实例。2.2 参数类型 ColorRGBA64 是什么ColorRGBA64是microsoft/fast-colors的核心颜色表示类定义在 ColorRGBA64 类文档 中其官方描述为 A RGBA color with 64 bit channels64 位通道的 RGBA 颜色。注意它不是用 0–255 表示通道值而是用 0–1 之间的浮点数new ColorRGBA64(1, 0, 0, 1) // red构造器签名为constructor(red, green, blue, alpha)四个通道属性r、g、b、a均为number类型。除了构造器该类还提供一组实用的转换与处理能力方便把颜色接入你的管线clamp()返回通道值被钳制在 0–1 之间的新ColorRGBA64roundToPrecision(precision)按指定精度四舍五入生成新实例equalValue(rhs)判断两个颜色是否相等toObject()/fromObject(data)与配置对象ColorRGBA64Config互转toStringHexRGB()、toStringHexARGB()、toStringHexRGBA()、toStringWebRGB()、toStringWebRGBA()输出#RRGGBB、#AARRGGBB、#RRGGBBAA、rgb(...)、rgba(...)等常见字符串格式。因此在调用createBalancedColorScale()之前你可以通过ColorRGBA64的构造器、clamp()、roundToPrecision()等成员对输入颜色做归一化与清洗确保传入的颜色通道值合法。2.3 返回类型 ColorScale 的完整能力ColorScale的官方描述是 A color scale created from linear stops由线性色标创建的色阶完整能力见 ColorScale 类文档。除了静态方法createBalancedColorScale()它还提供以下实例成员理解这些成员能让你把返回的色阶用起来构造器参考constructor(stops: ColorScaleStop[]);其中ColorScaleStop是一个接口参考包含两个属性属性类型说明colorColorRGBA64该色标的颜色positionnumber该色标在色阶上的位置结合 0–1 取值区间推断也就是说createBalancedColorScale(colors)的实质是根据传入的颜色数组生成一组平衡的ColorScaleStop[]再以此构造出一个标准的ColorScale——这解释了为什么它是静态工厂方法以及为什么返回值可以直接当普通ColorScale使用。实例方法供色阶创建后使用getColor(position, interpolationMode?)参考在指定position处取得插值后的颜色返回ColorRGBA64interpolationMode为可选的ColorInterpolationSpace插值空间。trim(lowerBound, upperBound, interpolationMode?)参考截取色阶的一部分按lowerBound/upperBound区间返回一个新的ColorScale。findNextColor(position, contrast, searchDown?, interpolationMode?, contrastErrorMargin?, maxSearchIterations?)参考在色阶中按对比度要求查找下一个符合条件的颜色位置返回number位置值。clone()复制一份色阶实例。插值空间枚举ColorInterpolationSpace参考在getColor()、trim()、findNextColor()中作为可选项使用成员值如下成员值说明RGB0RGB 空间插值HSL1HSL 空间插值HSV2HSV 空间插值XYZ3XYZ 空间插值LAB4Lab 空间插值LCH5LCH 空间插值默认情况下createBalancedColorScale()生成的色阶会在相邻色标间做线性插值当你需要更符合视觉感知的过渡例如避免 RGB 空间下中间色发灰时可以在调用getColor()时显式传入ColorInterpolationSpace.LAB或LCH等空间。三、使用示例从一组颜色到连续色阶下面给出一个完整的可运行示例演示从构造输入颜色到创建平衡色阶再到取色与格式化的完整链路。所有 API 均来自上文引用的官方 1.x API 文档。import { ColorRGBA64, ColorScale, ColorInterpolationSpace, } from microsoft/fast-colors; // 1. 构造一组输入颜色通道值范围 0–1构造器签名见上文 ColorRGBA64 文档 const colors: ColorRGBA64[] [ new ColorRGBA64(1, 0, 0, 1), // 红 new ColorRGBA64(1, 0.5, 0, 1), // 橙 new ColorRGBA64(1, 1, 0, 1), // 黄 new ColorRGBA64(0, 1, 0, 1), // 绿 new ColorRGBA64(0, 0, 1, 1), // 蓝 ]; // 2. 用静态工厂方法创建平衡色阶 const scale: ColorScale ColorScale.createBalancedColorScale(colors); // 3. 在 0–1 区间任意位置取色默认线性插值 const start: ColorRGBA64 scale.getColor(0); const mid: ColorRGBA64 scale.getColor(0.5); const end: ColorRGBA64 scale.getColor(1); // 4. 指定更符合视觉感知的插值空间 const labMid: ColorRGBA64 scale.getColor(0.5, ColorInterpolationSpace.LAB); // 5. 将颜色格式化为可直接写入 CSS 的字符串 const cssStart start.toStringWebRGB(); // rgb(0xRR, 0xGG, 0xBB) const cssMid labMid.toStringHexRGB(); // #RRGGBB在此基础上还可以结合trim()截取子色阶用findNextColor()按对比度在色阶中定位颜色例如为深色背景挑选满足可读性对比度要求的前景色——这些都是把平衡色阶落地的典型用法。四、典型应用场景把生成调色板接入色阶createBalancedColorScale()的一个重要价值在于它可以与调色板生成功能组合。ColorPalette类提供了generatePaletteColorScale()方法参考其签名同样返回ColorScalegeneratePaletteColorScale(): ColorScale;这意味着ColorScale有两条常见的生产路径显式指定由开发者自己准备一组ColorRGBA64通过createBalancedColorScale()构建色阶本文核心方法算法生成由ColorPalette基于基准色等配置自动生成调色板再通过generatePaletteColorScale()得到色阶。二者产出的都是同一类型ColorScale因此后续的取色、截取、对比度搜索代码完全可以共用——这也是静态工厂方法把输入形态与使用方式解耦的设计价值所在。五、使用注意事项通道值范围ColorRGBA64的通道值是 0–1 之间的浮点数不是 0–255 的整数值。传入前建议通过clamp()或roundToPrecision()做归一化。输入数量传入的colors数组元素个数即决定了色阶的色标数量元素过少如仅 1 个时色阶退化为单一颜色实际使用时建议至少提供 2 个端点颜色。插值空间选择默认行为为线性插值对需要感知均匀过渡的场景优先考虑ColorInterpolationSpace.LAB/LCH。不可变性trim()、clone()等成员返回新的ColorScale实例从签名返回类型推断原地修改色阶并不是该 API 的推荐方式。文档来源本文全部 API 签名与类型定义均来自仓库内的官方 1.x API 参考文档fast-colors API 索引如需进一步核对其他颜色工具混合、调色板、各色彩空间类可继续查阅该索引下的对应页面。六、小结ColorScale.createBalancedColorScale(colors)是microsoft/fast-colors中最快捷的色阶工厂输入一组ColorRGBA64输出一条可直接取色的线性ColorScale。它继承了ColorScale全部实例能力getColor、trim、findNextColor、clone并可与ColorPalette.generatePaletteColorScale()产出的色阶无缝互换。在设计系统令牌design tokens、数据可视化渐变、主题色板等需要一组颜色 → 连续渐变的场景中它是一个开箱即用、行为可预期的基础工具。赞分享前端UI组件【免费下载链接】fastThe adaptive interface system for modern web experiences.项目地址https://gitcode.com/gh_mirrors/fa/fast点击查看免费下载相关推荐CleanArchitecture.WorkerService数据持久化指南EfRepository与AppDbContext深度应用CleanArchitecture.WorkerService数据持久化指南EfRepository与AppDbContext深度应用 想要构建健壮的后台服务前端UI组件FAST fast-colors 之 saturateViaLCH用 LCH 色彩空间对颜色做饱和度调整FAST fast colors 之 saturateViaLCH用 LCH 色彩空间对颜色做饱和度调整 saturateViaLCH 是 microsof前端UI组件Mantine colors-generator 使用指南基于单一颜色值生成 10 阶调色板Mantine colors generator 使用指南基于单一颜色值生成 10 阶调色板 mantine/colors generator 是 Mant前端UI组件设计系统上一篇问题描述下一篇Windows 11 PL2303驱动终极解决方案3步告别黄色感叹号创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考