setAlpha

将任意支持的颜色格式转换为带指定透明度的十六进制颜色字符串，方便在 UI 中创建悬停状态、遮罩层等半透明效果。

示例

基本用法

import { setAlpha } from '@esdora/color'

// 为红色设置 50% 的透明度
setAlpha('#ff0000', 0.5)
// => '#ff000080'

// 当透明度设置为 1 时，返回标准的 6 位十六进制颜色
setAlpha('#ff000080', 1)
// => '#ff0000'

更新已有透明度

import { setAlpha } from '@esdora/color'

// 此函数会覆盖颜色原有的透明度
const semiTransparent = 'rgba(52, 152, 219, 0.3)' // 30% 透明度
setAlpha(semiTransparent, 0.8)
// => '#3498dbcc'

创建遮罩层效果

import { setAlpha } from '@esdora/color'

// 为黑色设置半透明，常用于创建遮罩层
setAlpha('#000000', 0.5)
// => '#00000080'

签名与说明

类型签名

import type { EsdoraColor } from '@esdora/color'

/**
 * 设置颜色的透明度（alpha 通道）到指定值。
 *
 * 此函数会将颜色的透明度设置为指定的值，而不改变颜色的其他属性（色相、饱和度、亮度）。
 * 返回十六进制格式的颜色字符串。
 */
export function setAlpha(color: string | EsdoraColor, alpha: number): string | null

参数说明

参数	类型	描述	必需
color	string | EsdoraColor	基础颜色，可以是 HEX/RGB/HSL 等颜色字符串，或符合内部 EsdoraColor 结构的颜色对象。	是
alpha	number	新的透明度值，范围为 0-1（0 为完全透明，1 为完全不透明），超出范围会被裁剪。	是

返回值

• 类型: string | null
• 说明:
  • 当输入为合法颜色时，返回设置透明度后的十六进制颜色字符串。
  • 当 alpha 为 1 时，返回 6 位十六进制字符串（#rrggbb）。
  • 当 alpha 小于 1 时，返回 8 位十六进制字符串（#rrggbbaa），末尾两位为透明度。
• 特殊情况:
  • 当 color 无法被解析为合法颜色（如无效字符串、null、undefined）时，返回 null。

泛型约束（如适用）

本函数未使用泛型类型参数。

注意事项与边界情况

输入边界

• alpha 会被严格限制在 [0, 1] 范围内：
  • 传入小于 0 的值（如 -0.5）会被当作 0 处理，结果为完全透明。
  • 传入大于 1 的值（如 1.5）会被当作 1 处理，结果为完全不透明。
• 支持多种颜色表示形式，包括：
  • 十六进制颜色：如 '#ff0000'、'#ff000080'
  • rgb(...) / rgba(...)：如 'rgb(255, 0, 0)'、'rgba(255, 0, 0, 0.3)'
  • hsl(...) / hsla(...)：如 'hsl(0, 100%, 50%)'、'hsla(0, 100%, 50%, 0.2)'
  • 标准颜色名称：如 'red'
• 对于已经包含透明度的输入（如 RGBA、HSLA、8 位 HEX），新的 alpha 会覆盖原有透明度。
• 不同颜色格式在相同 alpha 下会被统一转换为相同的十六进制结果，便于在代码中对比和复用。

错误处理

• 当 color 为无效颜色字符串、空字符串、null 或 undefined 时，内部解析会失败，函数返回 null 而不会抛出异常。
• 调用方可以通过判断返回值是否为 null 来区分成功与失败：
  • 返回 string 表示设置透明度成功。
  • 返回 null 表示输入无效或解析失败。
• 一般情况下无需使用 try...catch 包裹调用，只需在使用结果前做空值判断即可。

性能考虑

• 时间复杂度: O(1)，每次调用只对单个颜色进行解析、透明度调整和格式化输出。
• 空间复杂度: O(1)，仅创建固定数量的中间颜色对象。
• 优化建议:
  • 适合在组件渲染前或样式配置阶段预先计算好结果，避免在动画帧中频繁计算。
  • 对于需要批量生成透明色（例如整套主题色的不同状态），可以在业务层对结果进行缓存。

相关链接

• 源码