# color-printf

**Repository Path**: nodets/color-printf

## Basic Information

- **Project Name**: color-printf
- **Description**: 一个轻量级、高兼容的终端彩色打印工具，支持 **ESM 与 CommonJS 双模块系统**，提供 **便捷颜色函数**（如 `red("文本")`）、**自定义十六进制颜色**、**printf 风格格式化** 及 **字符串格式化（color.format）**，无需手动处理 ANSI 转义码，适配绝大多数终端。
- **Primary Language**: Unknown
- **License**: MIT
- **Default Branch**: main
- **Homepage**: None
- **GVP Project**: No

## Statistics

- **Stars**: 0
- **Forks**: 0
- **Created**: 2025-09-19
- **Last Updated**: 2025-09-20

## Categories & Tags

**Categories**: Uncategorized

**Tags**: None

## README

# 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 混合使用）

### 安装包
```bash
# npm 安装
npm install color-printf --save

# yarn 安装
yarn add color-printf
```


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

### 1. ESM 导入（推荐，适用于 `package.json` 含 `"type": "module"`）
```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 输出
```

### 2. CommonJS 导入（适用于传统 Node.js 项目，无 `"type": "module"`）
```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); // 自定义打印时机
```


## 📋 详细用法
### 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()`：直接打印多颜色文本
支持 **混合颜色** 和 **自定义十六进制颜色**，语法规则：
- 前景色：`#颜色值: 文本内容`（颜色值可为名称或十六进制）；
- 背景色：`##颜色值: 文本内容`（双 `#` 开头表示背景色）；
- 分隔符：必须用冒号（英文 `:` 或中文 `：`）分隔颜色与文本；
- 结尾处理：无需手动加 `#`，颜色自动生效到下一个标记或文本结束。

#### 示例：混合颜色与格式化
```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. `color.format()`：生成彩色字符串
返回带 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()`  | 返回彩色字符串        | 需自定义打印（如日志系统、延迟打印）|


### 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. 执行命令（永久生效）：
   ```cmd
   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`；若需混合使用，可通过动态导入：
  ```javascript
  // CommonJS 中动态导入 ESM 模块（Node.js ≥ 14.8）
  import('color-printf').then(({ red, color }) => {
    red("动态导入的红色文本");
    console.log(color.format("#ff00ff: 动态生成的紫色文本"));
  });
  ```

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

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


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