color-printf一个轻量级、高兼容的终端彩色打印工具
color-printf
一个轻量级、高兼容的终端彩色打印工具，支持 ESM 与 CommonJS 双模块系统，提供 便捷颜色函数（如 red("文本")）、自定义十六进制颜色、printf 风格格式化 及 字符串格式化（color.format），无需手动处理 ANSI 转义码，适配绝大多数终端。
🌟 核心特性
- 双模块支持：无缝兼容 ESM（
import）和 CommonJS（require）。 - 双功能模式：
color.printf()：直接打印彩色文本；color.format()：返回带颜色的字符串，支持用户自主调用console.log等方法。
- 简单直观：直接调用颜色函数（
red()、green()等），无需记忆复杂语法。 - 灵活扩展：支持颜色名称（
red）、十六进制颜色（#ff0000或#f00，大小写不敏感）。 - 格式兼容：支持 printf 风格格式化参数（
%s、%d、%j等）。 - 终端适配：自动检测终端是否支持 24 位真彩色，旧终端自动降级为 8 位颜色。
- 语法友好：无需结尾
#，支持中英文冒号（:或：）分隔颜色与文本。
📦 安装
前提
- Node.js ≥ 14（支持 ESM 和 CommonJS 混合使用）
安装包
# npm 安装
npm install color-printf --save# yarn 安装
yarn add color-printf
🚀 快速开始
根据项目使用的模块系统，选择对应的导入方式，并体验核心功能：
1. ESM 导入（推荐，适用于 package.json 含 "type": "module"）
// 按需导入（推荐）
import { red, color } from 'color-printf';// 1. 便捷颜色函数：直接打印
red("这是红色文本");// 2. color.printf()：直接打印多颜色文本
color.printf("##ffff00: 黄色背景文本 #0000ff: 蓝色文本");// 3. color.format()：生成彩色字符串，自主打印
const coloredStr = color.format("#ff00ff: 紫色文本，%s", "带格式化参数");
console.log(coloredStr); // 手动调用 console.log 输出
2. CommonJS 导入（适用于传统 Node.js 项目，无 "type": "module"）
// 按需导入
const { green, color } = require('color-printf');// 1. 便捷颜色函数
green("这是绿色文本，支持格式化：%d", 123);// 2. color.printf()
color.printf("#red: 错误提示 ##yellow: 警告内容");// 3. color.format()
const mixedStr = color.format("##00ff00: 绿色背景，#ff8800: 橙色文本");
console.log(mixedStr); // 自定义打印时机
📋 详细用法
1. 便捷颜色函数
直接调用预设颜色函数，快速打印单色文本，支持格式化参数：
| 类型 | 函数名 | 描述 | 示例 |
|---|---|---|---|
| 前景色 | black() | 黑色文本 | black("黑色文本，%s", "带参数") |
red() | 红色文本 | red("错误：操作失败") | |
green() | 绿色文本 | green("成功：数据已保存") | |
yellow() | 黄色文本 | yellow("警告：磁盘空间不足") | |
blue() | 蓝色文本 | blue("信息：正在加载") | |
magenta() | 品红色文本 | magenta("调试：参数值") | |
cyan() | 青色文本 | cyan("日志：请求时间") | |
white() | 白色文本 | white("高亮：重点内容") | |
| 背景色 | bgBlack() | 黑色背景 | bgBlack("黑底白字文本") |
bgRed() | 红色背景 | bgRed("红底文本：紧急错误") | |
bgGreen() | 绿色背景 | bgGreen("绿底文本：操作成功") | |
bgYellow() | 黄色背景 | bgYellow("黄底文本：注意事项") | |
bgBlue() | 蓝色背景 | bgBlue("蓝底文本：信息提示") | |
bgMagenta() | 品红色背景 | bgMagenta("品红底：调试信息") | |
bgCyan() | 青色背景 | bgCyan("青底文本：日志详情") | |
bgWhite() | 白色背景 | bgWhite("白底黑字：重点强调") |
2. color.printf()：直接打印多颜色文本
支持 混合颜色 和 自定义十六进制颜色，语法规则：
- 前景色：
#颜色值: 文本内容（颜色值可为名称或十六进制）； - 背景色：
##颜色值: 文本内容（双#开头表示背景色）； - 分隔符：必须用冒号（英文
:或中文：）分隔颜色与文本； - 结尾处理：无需手动加
#，颜色自动生效到下一个标记或文本结束。
示例：混合颜色与格式化
import { color } from 'color-printf';// 1. 自定义十六进制颜色
color.printf("#1E90FF: 天蓝色文本（6位十六进制） ##f00: 红色背景文本");// 2. 混合多颜色 + 格式化参数
color.printf("#red: 错误 ##yellow: 警告 #blue: 用户 %s 提交了 %d 条数据","张三",5
);// 3. 中英文冒号兼容
color.printf("#green：中文冒号的成功文本 ##ff8800：橙色背景文本");
3. color.format()：生成彩色字符串
返回带 ANSI 颜色代码的字符串，不直接打印，用户可自主决定打印时机（如结合 console.log、日志系统等）。
基本用法
import { color } from 'color-printf';// 1. 生成单颜色字符串
const redStr = color.format("#ff0000: 这是红色字符串");
console.log(redStr); // 手动打印// 2. 生成多颜色混合字符串
const mixedStr = color.format("##ffff00: 黄色背景 #0000ff: 蓝色文本，%s", "带参数");
console.log(mixedStr); // 结合 console.log 输出// 3. 结合其他日志工具
// logger.info(color.format("#00ff00: 日志信息：%j", { code: 200 })); // 示例：日志系统
与 color.printf() 的区别
| 方法 | 行为 | 适用场景 |
|---|---|---|
color.printf() | 直接打印到终端 | 简单场景，无需自定义打印逻辑 |
color.format() | 返回彩色字符串 | 需自定义打印（如日志系统、延迟打印） |
4. 格式化参数支持
兼容 Node.js util.format() 的所有格式化规则，常用参数如下：
| 参数 | 描述 | 示例 |
|---|---|---|
%s | 字符串 | red("用户名：%s", "admin") |
%d | 数字（整数/浮点数） | green("分数：%d", 95.5) |
%j | JSON 格式（对象/数组） | blue("配置：%j", { theme: "dark" }) |
%% | 转义为百分号 | yellow("完成率：%d%%", 80) |
%o | 对象详细格式（含原型） | magenta("对象详情：%o", new Date()) |
🔧 API 说明
1. 便捷颜色函数（如 red(format, ...args)）
- 功能：直接打印指定颜色的文本，支持格式化。
- 参数：
format：字符串或格式化模板（如"错误：%s"）；...args：可选，与格式化模板对应的参数。
- 返回值：无（直接打印到终端）。
2. color.printf(format, ...args)
- 功能：解析带颜色标记的格式化字符串，直接打印到终端。
- 参数：
format：带颜色标记的格式化模板（如"#ff0000: 错误：%s"）；...args：可选，与格式化模板对应的参数。
- 返回值：无（直接打印到终端）。
3. color.format(format, ...args)
- 功能：解析带颜色标记的格式化字符串，返回带 ANSI 颜色代码的字符串。
- 参数：
format：带颜色标记的格式化模板（如"##ffff00: 黄色背景文本"）；...args：可选，与格式化模板对应的参数。
- 返回值：
string（带 ANSI 颜色代码的字符串）。
🖥️ 终端兼容性
| 终端类型 | 支持情况 | 备注 |
|---|---|---|
| Windows Terminal | ✅ 完全支持（24位真彩色） | 推荐使用 |
| VS Code 终端 | ✅ 完全支持（24位真彩色） | 无需额外配置 |
| iTerm2（macOS） | ✅ 完全支持（24位真彩色） | 推荐使用 |
| Linux 终端（gnome-terminal） | ✅ 完全支持（24位真彩色） | - |
| Windows CMD | ⚠️ 部分支持（8位颜色） | 需开启 ANSI 支持（见下方配置） |
开启 Windows CMD ANSI 支持
- 以管理员身份打开 CMD。
- 执行命令（永久生效）：
reg add HKCU\Console /v VirtualTerminalLevel /t REG_DWORD /d 1 - 重启 CMD 即可。
❓ 常见问题
Q1：color.format() 返回的字符串不显色？
- 确保终端支持 ANSI 转义码（推荐使用 Windows Terminal、VS Code 终端）；
- 检查颜色标记语法：必须包含冒号（
:或：），如#red: 文本（而非#red 文本）； - 确认返回的字符串未被其他工具过滤 ANSI 代码（如部分日志插件需配置保留转义码）。
Q2：模块导入报错怎么办？
- ESM 报错：确保项目
package.json中添加"type": "module"，或使用.mjs后缀文件。 - CommonJS 报错：避免在 CommonJS 项目中使用
import，改用require；若需混合使用，可通过动态导入：// CommonJS 中动态导入 ESM 模块（Node.js ≥ 14.8） import('color-printf').then(({ red, color }) => {red("动态导入的红色文本");console.log(color.format("#ff00ff: 动态生成的紫色文本")); });
Q3：如何混合前景色和背景色？
通过 color.printf() 或 color.format() 嵌套标记实现（先背景色，后前景色）：
// 红色文本 + 黄色背景（printf 直接打印）
color.printf("##ffff00:#ff0000: 红文本黄背景");// 红色文本 + 黄色背景（format 生成字符串）
const mixedColorStr = color.format("##ffff00:#ff0000: 红文本黄背景");
console.log(mixedColorStr);
📄 许可证
MIT License | 可自由用于个人和商业项目，修改和分发需保留原作者信息。