# Picocolors 使用指南

> 轻量级终端颜色库，仅 2KB，性能优秀，API 简洁

## 📦 安装

```bash
# 使用 Bun
bun add picocolors

# 使用 npm
npm install picocolors

# 使用 yarn
yarn add picocolors
```

## 🚀 快速开始

```typescript
import pc from 'picocolors';

console.log(pc.red('红色文字'));
console.log(pc.green('绿色文字'));
console.log(pc.blue('蓝色文字'));
```

## 🎨 完整 API 参考

### 基本文字颜色

```typescript
pc.black('黑色文字'); // 黑色
pc.red('红色文字'); // 红色
pc.green('绿色文字'); // 绿色
pc.yellow('黄色文字'); // 黄色
pc.blue('蓝色文字'); // 蓝色
pc.magenta('洋红色文字'); // 洋红色
pc.cyan('青色文字'); // 青色
pc.white('白色文字'); // 白色
```

### 明亮文字颜色

```typescript
pc.blackBright('明亮黑色'); // 灰色
pc.redBright('明亮红色'); // 明亮红色
pc.greenBright('明亮绿色'); // 明亮绿色
pc.yellowBright('明亮黄色'); // 明亮黄色
pc.blueBright('明亮蓝色'); // 明亮蓝色
pc.magentaBright('明亮洋红'); // 明亮洋红
pc.cyanBright('明亮青色'); // 明亮青色
pc.whiteBright('明亮白色'); // 明亮白色
```

### 背景颜色

```typescript
pc.bgBlack('黑色背景');
pc.bgRed('红色背景');
pc.bgGreen('绿色背景');
pc.bgYellow('黄色背景');
pc.bgBlue('蓝色背景');
pc.bgMagenta('洋红背景');
pc.bgCyan('青色背景');
pc.bgWhite('白色背景');
```

### 明亮背景颜色

```typescript
pc.bgBlackBright('明亮黑色背景');
pc.bgRedBright('明亮红色背景');
pc.bgGreenBright('明亮绿色背景');
pc.bgYellowBright('明亮黄色背景');
pc.bgBlueBright('明亮蓝色背景');
pc.bgMagentaBright('明亮洋红背景');
pc.bgCyanBright('明亮青色背景');
pc.bgWhiteBright('明亮白色背景');
```

### 文字样式

```typescript
pc.bold('粗体文字'); // 粗体
pc.dim('暗淡文字'); // 暗淡
pc.italic('斜体文字'); // 斜体
pc.underline('下划线文字'); // 下划线
pc.strikethrough('删除线文字'); // 删除线
pc.inverse('反转颜色'); // 反转前景色和背景色
pc.hidden('隐藏文字'); // 隐藏文字
pc.reset('重置样式'); // 重置所有样式
```

## 🔧 特殊功能

### 颜色支持检测

```typescript
// 检测终端是否支持颜色
if (pc.isColorSupported) {
    console.log(pc.green('终端支持颜色！'));
} else {
    console.log('终端不支持颜色');
}
```

### 自定义颜色支持

```typescript
// 强制启用颜色
const forceColors = pc.createColors(true);
console.log(forceColors.red('强制显示红色'));

// 强制禁用颜色
const noColors = pc.createColors(false);
console.log(noColors.red('不会显示颜色'));
```

## 🎯 组合使用

⚠️ **重要**：Picocolors 不支持链式调用，需要使用嵌套方式

```typescript
// ❌ 错误用法 - 不支持链式调用
// pc.red.bold('文字')

// ✅ 正确用法 - 嵌套调用
pc.red(pc.bold('红色粗体文字'));
pc.blue(pc.underline('蓝色下划线文字'));
pc.bgYellow(pc.black('黄底黑字'));
pc.green(pc.italic(pc.bold('绿色粗斜体')));

// 复杂组合
pc.bgRed(pc.white(pc.bold(' ERROR '))) + ' ' + pc.red('错误信息');
```

## 💡 实用示例

### 日志级别颜色化

```typescript
import pc from 'picocolors';

const logger = {
    error: (msg: string) => console.log(pc.red(pc.bold(`❌ ERROR: ${msg}`))),
    warn: (msg: string) => console.log(pc.yellow(`⚠️  WARN:  ${msg}`)),
    info: (msg: string) => console.log(pc.blue(`ℹ️  INFO:  ${msg}`)),
    success: (msg: string) => console.log(pc.green(pc.bold(`✅ SUCCESS: ${msg}`))),
    debug: (msg: string) => console.log(pc.gray(`🐛 DEBUG: ${msg}`)),
};

// 使用
logger.error('数据库连接失败');
logger.warn('配置文件缺少某些字段');
logger.info('服务器启动中...');
logger.success('用户登录成功');
logger.debug('变量值: user_id = 123');
```

### 进度提示

```typescript
// 加载状态
console.log(pc.yellow('⏳ 正在处理...'));

// 成功状态
console.log(pc.bgGreen(pc.white(' SUCCESS ')) + ' 操作完成！');

// 错误状态
console.log(pc.bgRed(pc.white(' ERROR ')) + ' 操作失败！');

// 警告状态
console.log(pc.bgYellow(pc.black(' WARNING ')) + ' 注意事项');
```

### 表格美化

```typescript
const table = [
    ['姓名', '年龄', '状态'],
    ['张三', '25', '在线'],
    ['李四', '30', '离线'],
    ['王五', '28', '在线'],
];

// 表头
console.log(pc.bold(pc.blue(table[0].join(' | '))));
console.log(pc.gray('─'.repeat(20)));

// 数据行
table.slice(1).forEach((row) => {
    const [name, age, status] = row;
    const statusColor = status === '在线' ? pc.green : pc.red;
    console.log(`${name} | ${age} | ${statusColor(status)}`);
});
```

### 代码高亮

```typescript
const code = `
function ${pc.cyan('hello')}(${pc.yellow('name')}) {
    ${pc.gray('// 打印问候语')}
    console.log(${pc.green('"Hello, "')} + ${pc.yellow('name')});
}
`;

console.log(code);
```

## 📊 完整方法列表

| 类型         | 方法                                                                                                                    | 描述                 |
| ------------ | ----------------------------------------------------------------------------------------------------------------------- | -------------------- |
| **基本颜色** | `black, red, green, yellow, blue, magenta, cyan, white`                                                                 | 8种基本文字颜色      |
| **明亮颜色** | `blackBright, redBright, greenBright, yellowBright, blueBright, magentaBright, cyanBright, whiteBright`                 | 8种明亮文字颜色      |
| **基本背景** | `bgBlack, bgRed, bgGreen, bgYellow, bgBlue, bgMagenta, bgCyan, bgWhite`                                                 | 8种基本背景颜色      |
| **明亮背景** | `bgBlackBright, bgRedBright, bgGreenBright, bgYellowBright, bgBlueBright, bgMagentaBright, bgCyanBright, bgWhiteBright` | 8种明亮背景颜色      |
| **文字样式** | `bold, dim, italic, underline, strikethrough, inverse, hidden, reset`                                                   | 8种文字样式          |
| **工具方法** | `isColorSupported, createColors(enabled)`                                                                               | 颜色支持检测和自定义 |

## 🚀 在项目中集成

### 与 Winston 日志器集成

```typescript
import winston from 'winston';
import pc from 'picocolors';

const levelColors = {
    error: pc.red,
    warn: pc.yellow,
    info: pc.blue,
    http: pc.green,
    verbose: pc.cyan,
    debug: pc.gray,
    silly: pc.magenta,
};

const logger = winston.createLogger({
    transports: [
        new winston.transports.Console({
            format: winston.format.combine(
                winston.format.timestamp({ format: 'HH:mm:ss' }),
                winston.format.printf(({ level, message, timestamp }) => {
                    const colorize = levelColors[level as keyof typeof levelColors] || pc.white;
                    return `[${pc.gray(timestamp)}] ${colorize(level.toUpperCase())}: ${message}`;
                }),
            ),
        }),
    ],
});
```

### 创建主题

```typescript
// 定义主题
const theme = {
    primary: pc.blue,
    secondary: pc.cyan,
    success: pc.green,
    warning: pc.yellow,
    error: pc.red,
    muted: pc.gray,
    highlight: (text: string) => pc.bgYellow(pc.black(text)),
    badge: (text: string) => pc.bgBlue(pc.white(` ${text} `)),
};

// 使用主题
console.log(theme.primary('主要信息'));
console.log(theme.success('操作成功'));
console.log(theme.error('发生错误'));
console.log(theme.highlight('重要提示'));
console.log(theme.badge('新功能'));
```

## ⚡ 性能优势

- **轻量级**：仅 2KB，比 chalk 小 14 倍
- **零依赖**：不依赖其他包
- **高性能**：比其他颜色库快 2-3 倍
- **兼容性**：支持 Node.js、Deno、浏览器

## 🔗 相关资源

- [GitHub 仓库](https://github.com/alexeyraspopov/picocolors)
- [npm 页面](https://www.npmjs.com/package/picocolors)
- [性能对比](https://github.com/alexeyraspopov/picocolors#benchmarks)

---

**推荐在所有需要终端颜色输出的项目中使用 Picocolors！**