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 位颜色。
- 语法友好：无需结尾 #，支持中英文冒号（: 或 ：）分隔颜色与文本。

📦 安装

$3

- Node.js ≥ 14（支持 ESM 和 CommonJS 混合使用）

$3

``bash

npm 安装

npm install color-printf --save

yarn 安装

yarn add color-printf
`

🚀 快速开始

根据项目使用的模块系统，选择对应的导入方式，并体验核心功能：

$3

`typescript
// 按需导入（推荐）
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 输出
`

$3


`javascript
// 按需导入
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); // 自定义打印时机
`




📋 详细用法

$3

直接调用预设颜色函数，快速打印单色文本，支持格式化参数：

| 类型 | 函数名 | 描述 | 示例 |
|------------|--------------|--------------------|-------------------------------|
| 前景色 | 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("白底黑字：重点强调")|




$3


支持 混合颜色 和 自定义十六进制颜色，语法规则：
- 前景色：#颜色值: 文本内容（颜色值可为名称或十六进制）；
- 背景色：##颜色值: 文本内容（双 # 开头表示背景色）；
- 分隔符：必须用冒号（英文 : 或中文 ：）分隔颜色与文本；
- 结尾处理：无需手动加 #，颜色自动生效到下一个标记或文本结束。

#### 示例：混合颜色与格式化
`typescript
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


返回带 ANSI 颜色代码的字符串，不直接打印，用户可自主决定打印时机（如结合 console.log、日志系统等）。

#### 基本用法
`typescript
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() | 返回彩色字符串 | 需自定义打印（如日志系统、延迟打印）|




$3


兼容 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 说明

$3

- 功能：直接打印指定颜色的文本，支持格式化。
- 参数：
- format：字符串或格式化模板（如 "错误：%s"）；
- ...args：可选，与格式化模板对应的参数。
- 返回值：无（直接打印到终端）。

$3

- 功能：解析带颜色标记的格式化字符串，直接打印到终端。
- 参数：
- format：带颜色标记的格式化模板（如 "#ff0000: 错误：%s"）；
- ...args：可选，与格式化模板对应的参数。
- 返回值：无（直接打印到终端）。

$3

- 功能：解析带颜色标记的格式化字符串，返回带 ANSI 颜色代码的字符串。
- 参数：
- format：带颜色标记的格式化模板（如 "##ffff00: 黄色背景文本"）；
- ...args：可选，与格式化模板对应的参数。
- 返回值：string（带 ANSI 颜色代码的字符串）。

🖥️ 终端兼容性

| 终端类型 | 支持情况 | 备注 |
|------------------------|-----------------------------------|---------------------------------------|
| Windows Terminal | ✅ 完全支持（24位真彩色） | 推荐使用 |
| VS Code 终端 | ✅ 完全支持（24位真彩色） | 无需额外配置 |
| iTerm2（macOS） | ✅ 完全支持（24位真彩色） | 推荐使用 |
| Linux 终端（gnome-terminal） | ✅ 完全支持（24位真彩色） | - |
| Windows CMD | ⚠️ 部分支持（8位颜色） | 需开启 ANSI 支持（见下方配置） |

$3

1. 以管理员身份打开 CMD。
2. 执行命令（永久生效）：
`cmd
reg add HKCU\Console /v VirtualTerminalLevel /t REG_DWORD /d 1
`
3. 重启 CMD 即可。

❓ 常见问题

$3

1. 确保终端支持 ANSI 转义码（推荐使用 Windows Terminal、VS Code 终端）；
2. 检查颜色标记语法：必须包含冒号（: 或 ：），如 #red: 文本（而非 #red 文本）；
3. 确认返回的字符串未被其他工具过滤 ANSI 代码（如部分日志插件需配置保留转义码）。

$3

- ESM 报错：确保项目 package.json 中添加 "type": "module"，或使用 .mjs 后缀文件。
- CommonJS 报错：避免在 CommonJS 项目中使用 import，改用 require；若需混合使用，可通过动态导入：
`javascript
// CommonJS 中动态导入 ESM 模块（Node.js ≥ 14.8）
import('color-printf').then(({ red, color }) => {
red("动态导入的红色文本");
console.log(color.format("#ff00ff: 动态生成的紫色文本"));
});
`

$3

通过 color.printf() 或 color.format() 嵌套标记实现（先背景色，后前景色）：
`typescript
// 红色文本 + 黄色背景（printf 直接打印）
color.printf("##ffff00:#ff0000: 红文本黄背景");

// 红色文本 + 黄色背景（format 生成字符串）
const mixedColorStr = color.format("##ffff00:#ff0000: 红文本黄背景");
console.log(mixedColorStr);
``

📄 许可证

MIT License | 可自由用于个人和商业项目，修改和分发需保留原作者信息。