A lightweight terminal color printing tool with ESM and CommonJS support, providing printf-style formatting and color functions
npm install color-printf一个轻量级、高兼容的终端彩色打印工具,支持 ESM 与 CommonJS 双模块系统,提供 便捷颜色函数(如 red("文本"))、自定义十六进制颜色、printf 风格格式化 及 字符串格式化(color.format),无需手动处理 ANSI 转义码,适配绝大多数终端。
import)和 CommonJS(require)。color.printf():直接打印彩色文本;color.format():返回带颜色的字符串,支持用户自主调用 console.log 等方法。red()、green() 等),无需记忆复杂语法。red)、十六进制颜色(#ff0000 或 #f00,大小写不敏感)。%s、%d、%j 等)。#,支持中英文冒号(: 或 :)分隔颜色与文本。bash
npm 安装
npm install color-printf --saveyarn 安装
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);
``