FAST 1.x @microsoft/fast-colors：temperatureToRGB() 色温转 RGB 颜色函数详解

• 前端
• UI组件

在 FAST 1.x 的@microsoft/fast-colors颜色工具库中，temperatureToRGB()负责把一个以开尔文（Kelvin）为单位的色温值转换为 64 位 RGBA 颜色对象ColorRGBA64。它是“黑体辐射色温 → 屏幕颜色”这一常见设计场景（例如暖冷色调渐变、白平衡示意、主题色推导）的入口函数，并与rgbToTemperature()构成一对互逆的转换工具。读完本文，你可以掌握该函数的完整签名、参数语义、返回类型ColorRGBA64的用法与格式化输出方式，并了解它在fast-colors1.x 整个颜色函数族中的定位与版本适用范围。

函数定位与 API 出处

temperatureToRGB()属于 FAST 1.x 时代的@microsoft/fast-colors包。在当前仓库中，它的官方参考页由 API Documenter 自动生成，位于：

• fast-colors 1.x API 总览
• temperatureToRGB() 函数参考页

参考页文件头部明确标注了Do not edit this file. It is automatically generated by API Documenter.，说明该页面的签名、参数表与返回值均以发布包的类型声明（.d.ts）为准。在 fast-colors.md 的函数索引表中，该函数登记的描述为 “Converts a color temperature to a ColorRGBA64”，即“将色温转换为ColorRGBA64”。

函数签名与参数

TypeScript 签名

export declare function temperatureToRGB(tempKelvin: number, alpha?: number): ColorRGBA64;

这是一个纯函数式导出（export declare function），无需实例化任何类即可直接调用；从签名看，它属于fast-colors中大量以独立函数形式暴露的转换工具之一（同族函数还包括hslToRGB、labToRGB、lchToRGB、xyzToRGB等，见 函数索引）。

参数说明

要点：

• tempKelvin是唯一必填参数，物理含义为黑体辐射的色温，数值越大颜色越偏冷（蓝白），数值越小颜色越偏暖（红橙）。参考页未给出该参数的合法取值范围约束，因此调用方通常应自行将输入收敛到常用色温区间（如白炽灯到日光的大致范围），避免传入无物理意义的极端值；这一点属于调用侧的约定，而非文档中声明的实现限制。
• alpha为可选参数。从同库rgbToTemperature()参考页中 “The alpha channel of the input is ignored” 的备注可以推断，色温换算本身只涉及 RGB 三通道，alpha 仅作为输出颜色的透明度透传；未显式指定 alpha 时的具体默认行为，参考页未作文字说明。

返回值

ColorRGBA64

返回一个ColorRGBA64实例。

返回类型 ColorRGBA64 详解

ColorRGBA64是fast-colors的通用颜色载体，官方定义为 “A RGBA color with 64 bit channels.”，即每个通道采用 64 位浮点精度（double）存储的 RGBA 颜色。选择 64 位而非 8 位整数的意义在于：色温转换、插值、调色板生成等计算过程中会产生大量小数中间值，64 位通道可以避免提前量化带来的精度损失。

构造方式

constructor(red: number, green: number, blue: number, alpha?: number);

详见 ColorRGBA64.(constructor)。参考页给出的示例：

new ColorRGBA64(1, 0, 0, 1) // red

可见四个构造参数依次为 red、green、blue、alpha（alpha 可选）。

属性

常用方法

temperatureToRGB()的返回值可直接利用ColorRGBA64上的方法做后续处理（见 ColorRGBA64 class 参考页）：

其中clamp()与roundToPrecision()对temperatureToRGB()尤为实用：由于 64 位通道的中间值理论上可能略微越出 [0,1] 或携带过多小数位，落到 CSS 前做一次钳制与精度规整，能保证产物可直接用于样式。

典型用法示例

结合上述 API（均为参考页中已确认存在的签名），一个完整的调用链路可以是：

import { temperatureToRGB } from "@microsoft/fast-colors"; // 1. 由色温生成颜色：3000K 偏暖，6500K 接近日光 const warm = temperatureToRGB(3000); const daylight = temperatureToRGB(6500, 0.8); // 指定 alpha // 2. 直接读取 64 位通道值参与计算 console.log(warm.r, warm.g, warm.b, warm.a); // 3. 规整后输出为 CSS 可用字符串 console.log(warm.clamp().toStringHexRGB()); // "#RRGGBB" console.log(daylight.clamp().toStringWebRGBA()); // "rgba(0xRR, 0xGG, 0xBB, a)"

需要说明的是，以上代码依据的是 1.x API 参考页中登记的导入名与成员签名；@microsoft/fast-colors的实际包源码（含色温换算算法本体）已不在当前仓库的packages/目录中（见下文“版本适用范围”），因此具体算法实现细节以发布包源码为准，本文不对其展开臆测。

与 rgbToTemperature() 的互逆关系

fast-colors同时提供了反向函数：

export declare function rgbToTemperature(rgb: ColorRGBA64): number;

返回值为number（色温），且参考页 Remarks 明确说明 “The alpha channel of the input is ignored”，即该转换忽略输入颜色的 alpha 通道。详见 rgbToTemperature() 参考页。

从 API 结构看，两个函数构成一对互逆操作：

• temperatureToRGB(tempKelvin, alpha)：已知色温 → 取一个接近该色温的黑体颜色，可用于“由色温生成主题色”；
• rgbToTemperature(rgb)：已知任意 RGB 颜色 → 反解出最接近的色温值，可用于“判断某个颜色偏暖还是偏冷”。

两者组合可用于色温维度的色彩分析，例如先rgbToTemperature()得到基线色温，再用temperatureToRGB()生成该色温的标准化参考色。

在 fast-colors 函数族中的位置

从 fast-colors 1.x 函数索引 看，temperatureToRGB()位于一个完整颜色数学工具链中的“色彩空间转换”环节。与之相邻的关键能力包括：

• 解析：parseColor(raw)支持#RRGGBB、#AARRGGBB、rgb(RR,GG,BB)、rgba(RR,GG,BB,a)及 CSS 命名色等输入；
• 色空间互转：hslToRGB/hsvToRGB/labToRGB/lchToRGB/xyzToRGB及各方向逆变换，覆盖 HSL、HSV、CIELAB、CIELCH、XYZ 等色空间；
• 插值：interpolateRGB、interpolateHSL、interpolateLAB、interpolateXYZ等按色空间插值函数；
• 调色板：ColorPalette、ComponentStateColorPalette、generateOffCenterPalette、centeredRescale、rescale等从单一基础色扩展出完整组件色阶；
• 无障碍：contrastRatio()按 WCAG 2.0 公式计算对比度，rgbToRelativeLuminance()提供 sRGB 相对亮度。

典型的工程用法是：以temperatureToRGB()产出的颜色作为基础色（base color），再交给ComponentStateColorPalette等调色板 API 派生出一整套组件状态色——色温因此成为“主题生成”的第一级输入。

版本适用范围与边界说明

• 适用前提：本文基于仓库sites/website/src/docs/1.x/api/目录下的 FAST 1.x 官方 API 文档。该文档页由 API Documenter 从@microsoft/fast-colors发布包的类型声明生成，适用于@microsoft/fast-colors的 1.x 版本线。
• 仓库现状：当前仓库的 packages 目录 只包含fast-element、fast-router、fast-test-harness三个包，fast-colors的 TS 源码不在其中；因此关于该函数的实现级细节（例如内部采用何种色温近似算法、是否对tempKelvin做范围裁剪），本文仅陈述文档与类型签名能确认的事实，不做推断式结论。
• 注意事项：tempKelvin的合法区间与alpha缺省行为未在参考页中显式声明，集成时建议结合实际运行输出验证；输出颜色在用于 CSS 前建议先clamp()，以消除 64 位浮点计算可能带来的越界值。

相关文档路径

• 前端
• UI组件