WezTerm Lua API 深度解析wezterm.color.gradient颜色渐变采样实战【免费下载链接】weztermA GPU-accelerated cross-platform terminal emulator and multiplexer written by wez and implemented in Rust项目地址: https://gitcode.com/GitHub_Trending/we/weztermwezterm.color.gradient是 WezTerm 内置 Lua API 中的颜色工具函数用于根据一份渐变规格gradient spec与目标颜色数量返回在渐变范围内均匀采样的一组颜色。该函数常被用来为 Tab 标题、状态栏或按时间动态插值的场景生成配色是与window_background_gradient共享同一套渐变语法、却又独立面向程序化取色的核心工具。读完本文你将掌握该函数的完整参数模型、返回值类型以及将其落地到 Tab 配色与时间驱动配色等真实配置中的完整方案。函数签名与核心用途wezterm.color.gradient自 WezTerm 版本20220807-113146-c2fee766起提供定义于 gradient.mdwezterm.color.gradient(gradient, num_colors)gradient一个渐变规格Lua 表其合法取值与window_background_gradient配置项完全一致详见 window_background_gradient.mdnum_colors期望返回的颜色数量返回值一个包含num_colors个元素的 Lua 数组各元素均匀分布在渐变范围内且每个元素都是一个 Color 对象而非纯字符串。文档给出了一个直观示例即打开调试覆盖层 REPL 后直接执行 wezterm.color.gradient({presetRainbow}, 4) [#6e40aa, #ff8c38, #5dea8d, #6e40aa]可见传入Rainbow预设并请求 4 个颜色时得到的是首尾相接的 4 个十六进制色值Rainbow为循环渐变故起点与终点同色。该函数官方用途说明是例如为 Tab 生成一组颜色或实现按一天中的时间在渐变上插值这类有趣的效果。参数详解一份完整的渐变规格gradient参数支持两种描述方式使用预置预设preset或显式给出颜色列表colors二者选其一再配合若干可选的插值参数。方式一colors 颜色列表直接给出将被插值的一组颜色接受 CSS 风格的颜色写法命名颜色、rgb字符串等local colors wezterm.color.gradient({ colors { #0f0c29, #302b63, #24243e, }, }, 5)方式二preset 预设若给出preset字段则忽略colors。WezTerm 通过colorgradcrate 提供了 39 种内置预设全部可枚举于 config/src/background.rs 中的 GradientPreset 枚举Blues、BrBg、BuGn、BuPu、Cividis、Cool、CubeHelixDefault、GnBu、Greens、Greys、Inferno、Magma、OrRd、Oranges、PiYg、Plasma、PrGn、PuBu、PuBuGn、PuOr、PuRd、Purples、Rainbow、RdBu、RdGy、RdPu、RdYlBu、RdYlGn、Reds、Sinebow、Spectral、Turbo、Viridis、Warm、YlGn、YlGnBu、YlOrBr、YlOrRd这些名称大小写敏感均以 PascalCase 拼写例如preset Viridis。可选插值参数以下参数与window_background_gradient完全同源官方参数说明同样适用于本函数参数取值默认值说明interpolationLinear、Basis、CatmullRomLinear插值方式Basis与CatmullRom会带来更平滑的曲线过渡blendRgb、LinearRgb、Hsv、OklabRgb颜色混合的色彩空间Oklab能提供更符合人眼感知的过渡segment_size整数无将渐变划分为若干段用于制造阶梯式色带效果segment_smoothness浮点数无段边缘硬度0.0为硬边1.0为柔和边缘需要特别指出的是segment_size与segment_smoothness必须同时指定或同时省略这与底层 Gradient::build() 中的校验逻辑一致——只给其一会在运行时直接报错 Gradient must either specify both segment_size and segment_smoothness, or neither。一个带分段效果的完整示例local colors wezterm.color.gradient({ colors { #EEBD89, #D13ABD }, interpolation CatmullRom, blend Oklab, segment_size 11, segment_smoothness 0.0, }, 8)关于 orientation 与 noise 的说明window_background_gradient中还存在orientation水平/垂直/线性角度/径向与noise抗色带抖动两个参数。但从源码看Gradient::build() 在构建colorgrad渐变时只读取了 preset、colors、blend、interpolation 与分段参数orientation与noise是渲染窗口背景时才会消费的字段。因此对wezterm.color.gradient而言它们不会影响采样结果——这点可以放心采样输出只取决于颜色序列与插值/混合/分段参数。返回值Color 对象数组函数的每个返回值都是 WezTerm 的 Color 对象内部以 SRGBA 存储这意味着可以直接调用 Color 对象的方法做二次加工。其底层类型为lua-api-crates/color-funcs中的ColorWrap可用的常用方法包括见 lib.rs:lighten(factor)/:darken(factor)按比例调整亮度factor为正浮点数:saturate(factor)/:desaturate(factor)调整饱和度:adjust_hue_fixed(amount)按给定量调整色相:hsla()返回(h, s, l, a)元组:srgba_u8()、:linear_rgba()、:laba()返回各色彩空间的通道值直接tostring(color)或在表中直接展示会得到形如#6e40aa的十六进制字符串这正是 REPL 中看到的结果。例如取渐变采样后再统一提亮local base wezterm.color.gradient({ preset Inferno }, 5) local bright {} for i, c in ipairs(base) do bright[i] c:lighten(0.1) end在调试覆盖层 REPL 中快速试验调试覆盖层是 WezTerm 内建的一个日志 Lua REPL混合面板是试验wezterm.color.gradient最快捷的途径。默认绑定为CTRL-SHIFT-l可通过ShowDebugOverlay动作重新绑定config.keys { { key L, mods CTRL, action wezterm.action.ShowDebugOverlay }, }打开后 REPL 已预导入wezterm模块可以直接输入 wezterm.color.gradient({colors{red, blue}}, 3) [#ff0000, #7f007f, #0000ff]REPL 环境与配置的全局状态相互独立适合先验证参数组合与采样效果再把验证通过的代码搬回wezterm.lua。实战一为 Tab 生成一组配色官方文档明确指出该函数的典型场景之一是为 tabs 生成颜色。结合 Tab 标题格式化format-tab-title可以实现每个 Tab 按索引依次取色local colors wezterm.color.gradient({ preset Turbo }, 8) wezterm.on(format-tab-title, function(tab, tabs, panes, config, hover, max_width) local index tab.tab_index or 0 local color colors[(index % #colors) 1] return { { Background { Color color } }, { Text .. tab.active_pane.title .. }, } end)这里用% #colors做循环取色使 Tab 数量超过采样数时也能平滑回绕。实战二按一天中的时间动态插值官方文档设想的根据一天中的时间在渐变上插值效果可以借助os.date把当前时刻映射到[0, 1]再换算为采样下标。由于wezterm.color.gradient的采样点均匀分布时间比例乘以上限即可命中对应颜色local function color_for_now() local hour tonumber(os.date(%H)) or 12 local minute tonumber(os.date(%M)) or 0 local t (hour minute / 60) / 24 -- 0.0 ~ 1.0 映射到一天 -- 采样一个足够大的数量近似连续渐变 local samples wezterm.color.gradient({ preset Sinebow }, 24) local idx math.max(1, math.min(24, math.floor(t * 24) 1)) return samples[idx] end若希望输出更平滑也可以取两个相邻采样点之间再做一次线性插值配合 Color 对象的通道访问方法这里不再展开。底层实现从 Lua 到 colorgrad 的调用链从源码可以完整还原该函数在 Rust 侧的实现路径Lua 绑定注册在 lua-api-crates/color-funcs/src/lib.rs#L169-L171 中gradient_colors函数被同时注册为两个入口——模块级别名wezterm.gradient_colors与命名空间wezterm.color.gradient参数接收实现函数接收(Gradient, usize)二元组lib.rs#L191-L194其中Gradient正是 config/src/background.rs#L432-L457 中与窗口背景共享的结构体构建渐变调用gradient.build()其内部逻辑为——若有preset则直接映射到colorgrad预设函数否则用CustomGradient::new()装配colors、blend与interpolationbackground.rs#L461-L481均匀采样调用g.colors(num_colors)获得等间距采样点再逐一转为ColorWrap即 Lua 侧看到的 Color 对象后作为数组返回。这意味着wezterm.color.gradient与window_background_gradient底层使用完全相同的渐变引擎只是前者把采样结果以颜色数组的形式交还给 Lua 脚本后者则将渐变渲染为窗口背景位图。旧 API 演进从wezterm.gradient_colors到wezterm.color.gradient自20220807-113146-c2fee766起原函数wezterm.gradient_colors自20210814-124438-54e29167引入已迁移至wezterm.color.gradient官方明确建议使用新名称见 gradient_colors.md。迁移带来两点变化函数入口从wezterm.gradient_colors改为wezterm.color.gradient返回值从纯字符串升级为 Color 对象因而可以直接调用:lighten、:saturate等方法。旧名称目前仍可用Rust 侧保留了wezterm.gradient_colors的注册但新配置应统一使用wezterm.color.gradient以便获得对象化的返回值与后续演进支持。小结wezterm.color.gradient是 WezTerm Lua 配置体系中以编程方式生成调色板的入口它复用window_background_gradient的完整渐变规格colors/preset、interpolation、blend、segment返回均匀采样且对象化的 Color 数组。结合调试覆盖层 REPL 可以快速验证参数效果再落地到 Tab 标题、时间驱动配色等自定义场景中。若要进一步了解其姊妹能力可继续阅读 window_background_gradient.md 中关于线性/径向方向与noise的渲染细节以及 wezterm.color 模块 下的parse、from_hsla、get_default_colors等配套 API。【免费下载链接】weztermA GPU-accelerated cross-platform terminal emulator and multiplexer written by wez and implemented in Rust项目地址: https://gitcode.com/GitHub_Trending/we/wezterm创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考
WezTerm Lua API 深度解析：`wezterm.color.gradient` 颜色渐变采样实战
WezTerm Lua API 深度解析wezterm.color.gradient颜色渐变采样实战【免费下载链接】weztermA GPU-accelerated cross-platform terminal emulator and multiplexer written by wez and implemented in Rust项目地址: https://gitcode.com/GitHub_Trending/we/weztermwezterm.color.gradient是 WezTerm 内置 Lua API 中的颜色工具函数用于根据一份渐变规格gradient spec与目标颜色数量返回在渐变范围内均匀采样的一组颜色。该函数常被用来为 Tab 标题、状态栏或按时间动态插值的场景生成配色是与window_background_gradient共享同一套渐变语法、却又独立面向程序化取色的核心工具。读完本文你将掌握该函数的完整参数模型、返回值类型以及将其落地到 Tab 配色与时间驱动配色等真实配置中的完整方案。函数签名与核心用途wezterm.color.gradient自 WezTerm 版本20220807-113146-c2fee766起提供定义于 gradient.mdwezterm.color.gradient(gradient, num_colors)gradient一个渐变规格Lua 表其合法取值与window_background_gradient配置项完全一致详见 window_background_gradient.mdnum_colors期望返回的颜色数量返回值一个包含num_colors个元素的 Lua 数组各元素均匀分布在渐变范围内且每个元素都是一个 Color 对象而非纯字符串。文档给出了一个直观示例即打开调试覆盖层 REPL 后直接执行 wezterm.color.gradient({presetRainbow}, 4) [#6e40aa, #ff8c38, #5dea8d, #6e40aa]可见传入Rainbow预设并请求 4 个颜色时得到的是首尾相接的 4 个十六进制色值Rainbow为循环渐变故起点与终点同色。该函数官方用途说明是例如为 Tab 生成一组颜色或实现按一天中的时间在渐变上插值这类有趣的效果。参数详解一份完整的渐变规格gradient参数支持两种描述方式使用预置预设preset或显式给出颜色列表colors二者选其一再配合若干可选的插值参数。方式一colors 颜色列表直接给出将被插值的一组颜色接受 CSS 风格的颜色写法命名颜色、rgb字符串等local colors wezterm.color.gradient({ colors { #0f0c29, #302b63, #24243e, }, }, 5)方式二preset 预设若给出preset字段则忽略colors。WezTerm 通过colorgradcrate 提供了 39 种内置预设全部可枚举于 config/src/background.rs 中的 GradientPreset 枚举Blues、BrBg、BuGn、BuPu、Cividis、Cool、CubeHelixDefault、GnBu、Greens、Greys、Inferno、Magma、OrRd、Oranges、PiYg、Plasma、PrGn、PuBu、PuBuGn、PuOr、PuRd、Purples、Rainbow、RdBu、RdGy、RdPu、RdYlBu、RdYlGn、Reds、Sinebow、Spectral、Turbo、Viridis、Warm、YlGn、YlGnBu、YlOrBr、YlOrRd这些名称大小写敏感均以 PascalCase 拼写例如preset Viridis。可选插值参数以下参数与window_background_gradient完全同源官方参数说明同样适用于本函数参数取值默认值说明interpolationLinear、Basis、CatmullRomLinear插值方式Basis与CatmullRom会带来更平滑的曲线过渡blendRgb、LinearRgb、Hsv、OklabRgb颜色混合的色彩空间Oklab能提供更符合人眼感知的过渡segment_size整数无将渐变划分为若干段用于制造阶梯式色带效果segment_smoothness浮点数无段边缘硬度0.0为硬边1.0为柔和边缘需要特别指出的是segment_size与segment_smoothness必须同时指定或同时省略这与底层 Gradient::build() 中的校验逻辑一致——只给其一会在运行时直接报错 Gradient must either specify both segment_size and segment_smoothness, or neither。一个带分段效果的完整示例local colors wezterm.color.gradient({ colors { #EEBD89, #D13ABD }, interpolation CatmullRom, blend Oklab, segment_size 11, segment_smoothness 0.0, }, 8)关于 orientation 与 noise 的说明window_background_gradient中还存在orientation水平/垂直/线性角度/径向与noise抗色带抖动两个参数。但从源码看Gradient::build() 在构建colorgrad渐变时只读取了 preset、colors、blend、interpolation 与分段参数orientation与noise是渲染窗口背景时才会消费的字段。因此对wezterm.color.gradient而言它们不会影响采样结果——这点可以放心采样输出只取决于颜色序列与插值/混合/分段参数。返回值Color 对象数组函数的每个返回值都是 WezTerm 的 Color 对象内部以 SRGBA 存储这意味着可以直接调用 Color 对象的方法做二次加工。其底层类型为lua-api-crates/color-funcs中的ColorWrap可用的常用方法包括见 lib.rs:lighten(factor)/:darken(factor)按比例调整亮度factor为正浮点数:saturate(factor)/:desaturate(factor)调整饱和度:adjust_hue_fixed(amount)按给定量调整色相:hsla()返回(h, s, l, a)元组:srgba_u8()、:linear_rgba()、:laba()返回各色彩空间的通道值直接tostring(color)或在表中直接展示会得到形如#6e40aa的十六进制字符串这正是 REPL 中看到的结果。例如取渐变采样后再统一提亮local base wezterm.color.gradient({ preset Inferno }, 5) local bright {} for i, c in ipairs(base) do bright[i] c:lighten(0.1) end在调试覆盖层 REPL 中快速试验调试覆盖层是 WezTerm 内建的一个日志 Lua REPL混合面板是试验wezterm.color.gradient最快捷的途径。默认绑定为CTRL-SHIFT-l可通过ShowDebugOverlay动作重新绑定config.keys { { key L, mods CTRL, action wezterm.action.ShowDebugOverlay }, }打开后 REPL 已预导入wezterm模块可以直接输入 wezterm.color.gradient({colors{red, blue}}, 3) [#ff0000, #7f007f, #0000ff]REPL 环境与配置的全局状态相互独立适合先验证参数组合与采样效果再把验证通过的代码搬回wezterm.lua。实战一为 Tab 生成一组配色官方文档明确指出该函数的典型场景之一是为 tabs 生成颜色。结合 Tab 标题格式化format-tab-title可以实现每个 Tab 按索引依次取色local colors wezterm.color.gradient({ preset Turbo }, 8) wezterm.on(format-tab-title, function(tab, tabs, panes, config, hover, max_width) local index tab.tab_index or 0 local color colors[(index % #colors) 1] return { { Background { Color color } }, { Text .. tab.active_pane.title .. }, } end)这里用% #colors做循环取色使 Tab 数量超过采样数时也能平滑回绕。实战二按一天中的时间动态插值官方文档设想的根据一天中的时间在渐变上插值效果可以借助os.date把当前时刻映射到[0, 1]再换算为采样下标。由于wezterm.color.gradient的采样点均匀分布时间比例乘以上限即可命中对应颜色local function color_for_now() local hour tonumber(os.date(%H)) or 12 local minute tonumber(os.date(%M)) or 0 local t (hour minute / 60) / 24 -- 0.0 ~ 1.0 映射到一天 -- 采样一个足够大的数量近似连续渐变 local samples wezterm.color.gradient({ preset Sinebow }, 24) local idx math.max(1, math.min(24, math.floor(t * 24) 1)) return samples[idx] end若希望输出更平滑也可以取两个相邻采样点之间再做一次线性插值配合 Color 对象的通道访问方法这里不再展开。底层实现从 Lua 到 colorgrad 的调用链从源码可以完整还原该函数在 Rust 侧的实现路径Lua 绑定注册在 lua-api-crates/color-funcs/src/lib.rs#L169-L171 中gradient_colors函数被同时注册为两个入口——模块级别名wezterm.gradient_colors与命名空间wezterm.color.gradient参数接收实现函数接收(Gradient, usize)二元组lib.rs#L191-L194其中Gradient正是 config/src/background.rs#L432-L457 中与窗口背景共享的结构体构建渐变调用gradient.build()其内部逻辑为——若有preset则直接映射到colorgrad预设函数否则用CustomGradient::new()装配colors、blend与interpolationbackground.rs#L461-L481均匀采样调用g.colors(num_colors)获得等间距采样点再逐一转为ColorWrap即 Lua 侧看到的 Color 对象后作为数组返回。这意味着wezterm.color.gradient与window_background_gradient底层使用完全相同的渐变引擎只是前者把采样结果以颜色数组的形式交还给 Lua 脚本后者则将渐变渲染为窗口背景位图。旧 API 演进从wezterm.gradient_colors到wezterm.color.gradient自20220807-113146-c2fee766起原函数wezterm.gradient_colors自20210814-124438-54e29167引入已迁移至wezterm.color.gradient官方明确建议使用新名称见 gradient_colors.md。迁移带来两点变化函数入口从wezterm.gradient_colors改为wezterm.color.gradient返回值从纯字符串升级为 Color 对象因而可以直接调用:lighten、:saturate等方法。旧名称目前仍可用Rust 侧保留了wezterm.gradient_colors的注册但新配置应统一使用wezterm.color.gradient以便获得对象化的返回值与后续演进支持。小结wezterm.color.gradient是 WezTerm Lua 配置体系中以编程方式生成调色板的入口它复用window_background_gradient的完整渐变规格colors/preset、interpolation、blend、segment返回均匀采样且对象化的 Color 数组。结合调试覆盖层 REPL 可以快速验证参数效果再落地到 Tab 标题、时间驱动配色等自定义场景中。若要进一步了解其姊妹能力可继续阅读 window_background_gradient.md 中关于线性/径向方向与noise的渲染细节以及 wezterm.color 模块 下的parse、from_hsla、get_default_colors等配套 API。【免费下载链接】weztermA GPU-accelerated cross-platform terminal emulator and multiplexer written by wez and implemented in Rust项目地址: https://gitcode.com/GitHub_Trending/we/wezterm创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考
