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 支持

1. 以管理员身份打开 CMD。
2. 执行命令（永久生效）：

   reg add HKCU\Console /v VirtualTerminalLevel /t REG_DWORD /d 1

3. 重启 CMD 即可。

❓ 常见问题

Q1：color.format() 返回的字符串不显色？

1. 确保终端支持 ANSI 转义码（推荐使用 Windows Terminal、VS Code 终端）；
2. 检查颜色标记语法：必须包含冒号（: 或 ：），如 #red: 文本（而非 #red 文本）；
3. 确认返回的字符串未被其他工具过滤 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 | 可自由用于个人和商业项目，修改和分发需保留原作者信息。