Catppuccin Palette API 参考全解析：flavors、colorEntries 与完整类型系统一次看懂

Catppuccin Palette API 参考全解析：flavors、colorEntries 与完整类型系统一次看懂

【免费下载链接】palette🎨 Soothing pastel theme to use within your projects!项目地址: https://gitcode.com/gh_mirrors/pal/palette

🎨Catppuccin Palette是一款为前端项目提供舒缓马卡龙配色的开源色板库，以@catppuccin/palette包发布。它的核心是导出flavors、flavorEntries、colorEntries等 API 和一套完整的 TypeScript 类型系统，让你可以在 Node、Deno 乃至任何 JS/TS 环境里以类型安全的方式取用 4 种口味（flavor）、每种 26 个颜色的 hex、rgb、hsl、oklch 值。本文带你一次看懂它的 API 参考与类型设计。

如需本地阅读源码，可执行：git clone https://gitcode.com/gh_mirrors/pal/palette

一、30 秒上手：安装与导入

📦 项目当前版本为1.8.0（见 deno.json 中的version字段），支持 npm 与 Deno 两种安装方式：

npm install @catppuccin/palette

import { flavors, flavorEntries, version } from "@catppuccin/palette";

整个库的对外入口只有一个文件 mod.ts，颜色数据则由 palette.json 提供，二者共同构成"数据 + 类型"的 API 参考核心。

二、flavors：四口味（flavors）核心入口

flavors是一个对象，键为 4 个口味名，值为该口味的完整色板（类型CatppuccinFlavors）。🐱 四个口味的设计定位如下：

每个口味对象包含以下字段（定义见 mod.ts 的CatppuccinFlavor类型）：

三、Catppuccin 的 26 色系统：Accent 与 Monochromatic

每个口味的colors都包含26 个颜色，由两类组成：

1. Accent（14 个强调色）

类型AccentName（mod.ts）列出了全部强调色名：

rosewater·flamingo·pink·mauve·red·maroon·peach·yellow·green·teal·sky·sapphire·blue·lavender

💡 这些颜色都标记accent: true，适合作为品牌色、链接色、图标高亮等。

2. Monochromatic（12 个中性色）

类型MonochromaticName（mod.ts）是从前景到背景的完整灰阶：

text→subtext1→subtext0→overlay2→overlay1→overlay0→surface2→surface1→surface0→base→mantle→crust

🖼️ 使用建议：text系列用于文字，overlay系列用于悬浮/悬停元素，surface/base/mantle/crust从内到外层层加深背景，是搭建深色 UI 的标准骨架。

两类合并得到总类型：ColorName = AccentName | MonochromaticName。

四、colorEntries 与 flavorEntries：类型安全的遍历器

Object.entries()在原生 TypeScript 里会丢失键的联合类型，而 Catppuccin Palette 专门定义了工具类型Entries<T>（mod.ts），为遍历场景提供"带类型的键值对数组"：

flavorEntries.map(([flavorName, flavor]) => { console.log(`${flavor.emoji} ${flavor.name} is a ${flavor.dark ? "dark" : "light"} theme.`); flavor.colorEntries.map(([colorName, { hex, rgb, accent }]) => { // colorName 是 ColorName 联合类型，hex、rgb 都有完整补全 }); });

• flavorEntries：遍历 4 个口味本身，元素形如["mocha", CatppuccinFlavor]
• flavor.colorEntries：遍历单个口味的 26 个颜色，元素形如["rosewater", ColorFormat]
• flavor.ansiColorEntries：遍历 8 组 ANSI 颜色，元素形如["blue", AnsiColorGroups]

🧭 一句话记忆：要按名取用用flavors.x.colors.y，要循环生成用各种*Entries。

五、ColorFormat：一个颜色的四种色彩空间

ColorFormat是理解整个类型系统的钥匙（mod.ts），每个颜色对象都同时提供：

✅ 这意味着无论是 CSS 变量、终端染色还是设计稿取色，一份数据即可满足所有场景，无需再做格式转换。

六、ANSI 终端配色：ansiColors 参考

🖥️ 做 CLI 工具时，ansiColors字段提供 8 组标准终端色（black/red/green/yellow/blue/magenta/cyan/white），每组内含normal（0–7 号色）与bright（8–15 号色）两个AnsiColorFormat对象，除上述色彩空间外还带code字段（ANSI 转义码编号）。

⚠️ 小细节：bright并不总是"更亮"，而是更饱和；另外black组在暗色口味下映射的是surface1/surface2而非纯黑（可参考 mod.test.ts 中的断言逻辑）。

七、Web 前端用法：CSS 与 Sass

除了 JS 包，仓库还内置了 Web 生态的派生产物：

• CSS 变量：docs/css.md 说明了如何引入@catppuccin/palette/style，之后即可写var(--ctp-mocha-text)、rgba(var(--ctp-macchiato-base-rgb) / 0.9)这样的响应式变量。
• Sass：docs/sass.md 提供两种用法——单口味@use "mocha"直接拿到$base、$text变量；或引入聚合的catppuccin.$palette映射一次性生成 4 个口味的类。
• 构建脚本：这些样式由 scripts/builders/npm/css.ts、scripts/builders/npm/scss.ts、scripts/builders/npm/less.ts 从同一份 JSON 自动生成，保证多格式颜色永不漂移。

八、数据来源与版本追踪

📌 所有颜色并非手写，而是由 scripts/gen_palette.ts 从每个口味的原始 hex 值出发，借助 colorjs.io 计算 rgb/hsl/oklch 后写入 palette.json（当前version: "1.8.0"）。库导出的version常量与之保持一致，方便你的应用做兼容性检查。

📋 完整变更历史可查阅 CHANGELOG.md，例如 1.8.0 新增了oklch数值，1.5.0 引入了整套 ANSI 颜色，1.2.0 为每个口味加入了 emoji。

九、类型速查表

总结

🎯 Catppuccin Palette 的 API 设计思路非常清晰：JSON 存数据、TS 类型保安全、Entries 助遍历、多色彩空间全覆盖。记住flavors（取用）、colorEntries（遍历）、ColorFormat（数据形态）这三件套，再配合 CSS/Sass 派生格式，你就能在任何项目中快速落地这套舒缓马卡龙配色了。

【免费下载链接】palette🎨 Soothing pastel theme to use within your projects!项目地址: https://gitcode.com/gh_mirrors/pal/palette