FAST 颜色工具 parseColorHexRGB 解析指南：十六进制颜色字符串与 ColorRGBA64 的转换-育师

前端
UI组件

【免费下载链接】fast

The adaptive interface system for modern web experiences.

项目地址：https://gitcode.com/gh_mirrors/fa/fast

导读

parseColorHexRGB()是@microsoft/fast-colors包中用于把#RRGGBB或#RGB形式的十六进制颜色字符串解析为 ColorRGBA64 对象的入口函数。在 FAST 生态中，它服务于设计令牌（design tokens）、组件主题与颜色运算管线，是将外部颜色输入规范化为内部 64 位浮点 RGBA 表示的第一步。读完本文，你将掌握该函数的签名、参数约束、返回值语义、与parseColorHexRGBA/parseColorHexARGB的差异，以及如何借助配套的字符串校验与反向格式化方法构建完整可用的颜色处理链路。

parseColorHexRGB 函数总览

parseColorHexRGB()的核心作用是将十六进制颜色字符串转换为ColorRGBA64实例。它的声明位于 fast-colors.parsecolorhexrgb.md，完整签名如下：

export declare function parseColorHexRGB(raw: string): ColorRGBA64 | null;

参数说明

参数	类型	说明
raw	string	形如`#RRGGBB`或`#RGB`的颜色字符串

返回值语义

成功：返回一个ColorRGBA64实例；
解析失败：返回null，不会抛出异常，因此在非确定输入场景下可以直接把返回值作为可空值处理。

该函数只接受 RGB（不含透明度）的十六进制写法，若输入携带 Alpha 通道，应改用parseColorHexRGBA()（#RRGGBBAA/#RGBA）或parseColorHexARGB()（#AARRGGBB/#ARGB），三者声明完全同构，文档分别见 parsecolorhexrgba.md 与 parsecolorhexargb.md。

ColorRGBA64：64 位通道的颜色表示

parseColorHexRGB()的返回类型 ColorRGBA64 是 FAST 颜色系统的统一载体：每个通道（r/g/b/a）都用0～1 范围的浮点数表示，而不是 CSS 中习惯的 0～255 整数。构造方式为：

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

该类的关键能力（完整方法清单见 colorrgba64.md）：

方法	说明
`clamp()`	返回通道值被钳制在 0～1 之间的新`ColorRGBA64`
`roundToPrecision(precision)`	按指定精度取整生成新实例
`equalValue(rhs)`	判断两颜色是否相等
`fromObject(data)`/`toObject()`	与`ColorRGBA64Config`配置对象互转
`toStringHexRGB()`	格式化为`#RRGGBB`字符串
`toStringHexRGBA()`/`toStringHexARGB()`	格式化为`#RRGGBBAA`/`#AARRGGBB`
`toStringWebRGB()`/`toStringWebRGBA()`	格式化为`rgb(0xRR, 0xGG, 0xBB)`/`rgba(...)`

从源码结构看：正是这种"十六进制字符串 ↔ 0～1 浮点通道"的双向设计，使parseColorHexRGB()的输入输出可以无缝接入 fast-colors.md 中列出的rgbToHSL、rgbToLAB、contrastRatio、blend*系列运算，构成完整颜色处理管线。

函数族定位：parseColorHexRGB 与其他解析入口

@microsoft/fast-colors提供了一组互补的颜色解析函数，parseColorHexRGB只是其中针对"十六进制 RGB"的专用入口，与之并列的还包括：

函数	接受的格式	文档
`parseColorHexRGB(raw)`	`#RRGGBB`、`#RGB`	parsecolorhexrgb.md
`parseColorHexRGBA(raw)`	`#RRGGBBAA`、`#RGBA`	parsecolorhexrgba.md
`parseColorHexARGB(raw)`	`#AARRGGBB`、`#ARGB`	parsecolorhexargb.md
`parseColorWebRGB(raw)`	`rgb(RR,GG,BB)`	见 fast-colors.md 函数表
`parseColorWebRGBA(raw)`	`rgba(RR,GG,BB,a)`	同上
`parseColorNamed(raw)`	CSS 颜色名，如`red`	同上
`parseColor(raw)`	自动识别以上任意格式	parsecolor.md

对应的字符串格式校验函数isColorStringHexRGB()（#RRGGBB/#RGB）在 iscolorstringhexrgb.md 中定义，返回boolean，可在调用parseColorHexRGB之前先做格式预检，或在解析结果为null后做失败原因排查。

标准用法与边界情形

基本示例（来自官方文档）

parseColorHexRGBA("#FF0000"); parseColorHexRGBA("#F00");

注意：官方 API 文档中的示例文本保留了历史写法parseColorHexRGBA，但其意图与签名均为parseColorHexRGB的 6 位 / 3 位十六进制 RGB 解析（#RRGGBB与#RGB）。实际调用时应使用parseColorHexRGB函数名。

典型调用模式

import { parseColorHexRGB, ColorRGBA64 } from "@microsoft/fast-colors"; const color: ColorRGBA64 | null = parseColorHexRGB("#FF0000"); if (color !== null) { console.log(color.r, color.g, color.b); // 1, 0, 0 console.log(color.toStringHexRGB()); // "#FF0000" } else { // 输入不是合法的 #RRGGBB / #RGB 格式 }

边界情形

3 位缩写：#F00会按"每字符重复一次"展开为#FF0000，parseColorHexRGB的文档签名与isColorStringHexRGB的描述（"Test if a color matches #RRGGBB or #RGB"）均明确支持该缩写形式；
缺少#前缀或混入非法字符：解析失败，返回null；
超出 6 位/3 位长度的十六进制串：属于#RRGGBBAA/#AARRGGBB范畴，应改用parseColorHexRGBA/parseColorHexARGB；
返回值不抛出异常：对来自表单、配置文件、设计令牌等不可信输入，直接判空即可安全处理。

与字符串格式化方法组成完整闭环

parseColorHexRGB的逆操作是ColorRGBA64.toStringHexRGB()，其方法文档 tostringhexrgb.md 表明它将实例格式化为#RRGGBB字符串。配合使用即可实现"字符串 → 解析 → 运算 → 重新序列化"的完整回路：

const input = "#336699"; const parsed = parseColorHexRGB(input); const roundTrip = parsed?.toStringHexRGB(); // "#336699"

这种闭环能力在 FAST 的设计系统与主题切换场景中非常实用：外部以十六进制字符串传入品牌色，内部归一化为ColorRGBA64参与明度、饱和度、对比度等运算（rgbToHSL、rgbToLCH、contrastRatio等均以ColorRGBA64为输入，见 fast-colors.md 函数表），再以字符串形式输出到 CSS 变量或令牌系统。

结语

parseColorHexRGB虽小，却是 FAST 颜色体系对外的标准入口之一：它以null表达失败、以 0～1 浮点通道承载颜色，并通过ColorRGBA64无缝衔接整套颜色运算 API。配合isColorStringHexRGB做预检、toStringHexRGB做回写，即可在任意 Fast 项目或独立使用@microsoft/fast-colors的应用中搭建健壮、可复用的十六进制颜色解析与转换链路。