cursor-init/docs/chalk-guide.md

# Chalk 使用指南

> 最流行的终端字符串样式库，支持链式调用，功能强大

## 📦 安装

```bash
# 使用 Bun
bun add chalk

# 使用 npm
npm install chalk

# 使用 yarn
yarn add chalk
```

## 🚀 快速开始

```typescript
import chalk from 'chalk';

console.log(chalk.blue('Hello world!'));
console.log(chalk.red.bold('Error message'));
console.log(chalk.green.underline('Success!'));
```

## 🎨 完整 API 参考

### 基本文字颜色

```typescript
chalk.black('黑色文字'); // 黑色
chalk.red('红色文字'); // 红色
chalk.green('绿色文字'); // 绿色
chalk.yellow('黄色文字'); // 黄色
chalk.blue('蓝色文字'); // 蓝色
chalk.magenta('洋红色文字'); // 洋红色
chalk.cyan('青色文字'); // 青色
chalk.white('白色文字'); // 白色
chalk.gray('灰色文字'); // 灰色（blackBright 的别名）
chalk.grey('灰色文字'); // 灰色（gray 的别名）
```

### 明亮文字颜色

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

### 背景颜色

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

### 明亮背景颜色

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

### 文字样式

```typescript
chalk.bold('粗体文字'); // 粗体
chalk.dim('暗淡文字'); // 暗淡
chalk.italic('斜体文字'); // 斜体
chalk.underline('下划线文字'); // 下划线
chalk.strikethrough('删除线文字'); // 删除线
chalk.inverse('反转颜色'); // 反转前景色和背景色
chalk.hidden('隐藏文字'); // 隐藏文字
chalk.overline('上划线文字'); // 上划线（某些终端支持）
```

## 🔗 链式调用（Chalk 的特色）

```typescript
// 单一样式
chalk.blue('蓝色文字');

// 链式组合样式
chalk.red.bold('红色粗体');
chalk.green.underline('绿色下划线');
chalk.yellow.bgBlue('黄字蓝底');

// 复杂组合
chalk.red.bold.underline('红色粗体下划线');
chalk.blue.bgYellow.italic('蓝字黄底斜体');
chalk.green.dim.strikethrough('绿色暗淡删除线');

// 多重嵌套
chalk.red('红色 ' + chalk.blue('蓝色') + ' 继续红色');
chalk.bold('粗体 ' + chalk.italic('斜体') + ' 继续粗体');
```

## 🔧 高级功能

### RGB 和 HEX 颜色

```typescript
// RGB 颜色
chalk.rgb(255, 136, 0)('橙色文字'); // RGB
chalk.bgRgb(255, 136, 0)('橙色背景'); // RGB 背景

// HEX 颜色
chalk.hex('#FF8800')('橙色文字'); // HEX
chalk.bgHex('#FF8800')('橙色背景'); // HEX 背景

// HSL 颜色
chalk.hsl(32, 100, 50)('橙色文字'); // HSL
chalk.bgHsl(32, 100, 50)('橙色背景'); // HSL 背景

// HSV 颜色
chalk.hsv(32, 100, 100)('橙色文字'); // HSV
chalk.bgHsv(32, 100, 100)('橙色背景'); // HSV 背景

// Keyword 颜色
chalk.keyword('orange')('橙色文字'); // 关键字颜色
chalk.bgKeyword('orange')('橙色背景'); // 关键字背景色
```

### ANSI 256 颜色

```typescript
// ANSI 256 颜色（0-255）
chalk.ansi256(208)('橙色文字'); // ANSI 256 前景色
chalk.bgAnsi256(208)('橙色背景'); // ANSI 256 背景色

// ANSI 16 颜色（0-15）
chalk.ansi(9)('明亮红色'); // ANSI 16 前景色
chalk.bgAnsi(9)('明亮红色背景'); // ANSI 16 背景色
```

### 颜色支持检测

```typescript
// 检测颜色支持级别
console.log(chalk.level); // 0, 1, 2, 3
console.log(chalk.supportsColor); // ColorSupport 对象

// 强制设置颜色级别
chalk.level = 3; // 强制支持真彩色
```

### 创建自定义实例

```typescript
import { Chalk } from 'chalk';

// 创建无颜色实例
const noColors = new Chalk({ level: 0 });
console.log(noColors.red('不会显示颜色'));

// 创建强制颜色实例
const forceColors = new Chalk({ level: 3 });
console.log(forceColors.rgb(255, 0, 0)('强制显示红色'));
```

## 💡 实用示例

### 日志级别颜色化

```typescript
import chalk from 'chalk';

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

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

### 进度条和状态

```typescript
// 进度条
const progress = (percent: number) => {
    const filled = Math.floor(percent / 5);
    const empty = 20 - filled;
    const bar = chalk.green('█'.repeat(filled)) + chalk.gray('░'.repeat(empty));
    return `${bar} ${percent}%`;
};

console.log(progress(75));

// 状态标签
const status = {
    running: chalk.yellow('⏳ RUNNING'),
    success: chalk.white.bgGreen(' SUCCESS '),
    error: chalk.white.bgRed(' ERROR '),
    warning: chalk.black.bgYellow(' WARNING '),
    info: chalk.white.bgBlue(' INFO '),
};

console.log(status.running + ' 正在处理...');
console.log(status.success + ' 操作完成！');
console.log(status.error + ' 操作失败！');
```

### 表格美化

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

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

// 数据行
table.slice(1).forEach((row) => {
    const [name, age, status, score] = row;
    const statusColor = status === '在线' ? chalk.green : chalk.red;
    const scoreColor = parseInt(score) >= 90 ? chalk.green.bold : parseInt(score) >= 80 ? chalk.yellow : chalk.red;

    console.log(`${name} | ${age} | ${statusColor(status)} | ${scoreColor(score)}`);
});
```

### 代码语法高亮

```typescript
const highlightCode = (code: string) => {
    return code
        .replace(/\b(function|const|let|var|if|else|for|while|return)\b/g, (match) => chalk.blue.bold(match))
        .replace(/\b(true|false|null|undefined)\b/g, (match) => chalk.magenta(match))
        .replace(/(['"`])(.*?)\1/g, (match) => chalk.green(match))
        .replace(/\/\/.*/g, (match) => chalk.gray(match))
        .replace(/\b\d+\b/g, (match) => chalk.cyan(match));
};

const code = `
function hello(name) {
    // 打印问候语
    const message = "Hello, " + name;
    return message;
}
`;

console.log(highlightCode(code));
```

### 彩虹文字效果

```typescript
const rainbow = (text: string) => {
    const colors = [chalk.red, chalk.yellow, chalk.green, chalk.cyan, chalk.blue, chalk.magenta];

    return text
        .split('')
        .map((char, i) => colors[i % colors.length](char))
        .join('');
};

console.log(rainbow('Rainbow Text!'));
```

### 渐变效果

```typescript
const gradient = (text: string, startColor: [number, number, number], endColor: [number, number, number]) => {
    const length = text.length;
    return text
        .split('')
        .map((char, i) => {
            const ratio = i / (length - 1);
            const r = Math.round(startColor[0] + (endColor[0] - startColor[0]) * ratio);
            const g = Math.round(startColor[1] + (endColor[1] - startColor[1]) * ratio);
            const b = Math.round(startColor[2] + (endColor[2] - startColor[2]) * ratio);
            return chalk.rgb(r, g, b)(char);
        })
        .join('');
};

console.log(gradient('Gradient Text!', [255, 0, 0], [0, 0, 255])); // 红到蓝渐变
```

## 🚀 在项目中集成

### 与 Winston 日志器集成

```typescript
import winston from 'winston';
import chalk from 'chalk';

const levelStyles = {
    error: chalk.red.bold,
    warn: chalk.yellow,
    info: chalk.blue,
    http: chalk.green,
    verbose: chalk.cyan,
    debug: chalk.gray,
    silly: chalk.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 styleLevel = levelStyles[level as keyof typeof levelStyles] || chalk.white;
                    return `[${chalk.gray(timestamp)}] ${styleLevel(level.toUpperCase())}: ${message}`;
                }),
            ),
        }),
    ],
});
```

### CLI 工具美化

```typescript
// 命令行工具的美化输出
class CLI {
    static title(text: string) {
        console.log(chalk.bold.blue(`\n🚀 ${text}\n`));
    }

    static section(text: string) {
        console.log(chalk.bold.yellow(`📋 ${text}`));
    }

    static item(text: string, status?: 'success' | 'error' | 'warning') {
        const icon = status === 'success' ? '✅' : status === 'error' ? '❌' : status === 'warning' ? '⚠️' : '•';
        const color =
            status === 'success'
                ? chalk.green
                : status === 'error'
                  ? chalk.red
                  : status === 'warning'
                    ? chalk.yellow
                    : chalk.white;
        console.log(`  ${icon} ${color(text)}`);
    }

    static divider() {
        console.log(chalk.gray('─'.repeat(50)));
    }
}

// 使用
CLI.title('项目构建工具');
CLI.section('检查依赖');
CLI.item('Node.js 版本检查', 'success');
CLI.item('npm 包完整性检查', 'success');
CLI.item('TypeScript 编译检查', 'warning');
CLI.divider();
```

### 创建主题系统

```typescript
// 定义主题
const themes = {
    default: {
        primary: chalk.blue,
        secondary: chalk.cyan,
        success: chalk.green,
        warning: chalk.yellow,
        error: chalk.red,
        muted: chalk.gray,
        highlight: chalk.yellow.bgBlack,
        badge: (text: string) => chalk.white.bgBlue(` ${text} `),
    },
    dark: {
        primary: chalk.blueBright,
        secondary: chalk.cyanBright,
        success: chalk.greenBright,
        warning: chalk.yellowBright,
        error: chalk.redBright,
        muted: chalk.gray,
        highlight: chalk.black.bgYellow,
        badge: (text: string) => chalk.black.bgWhite(` ${text} `),
    },
};

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

## 📊 完整方法列表

| 类型          | 方法                                                                                                                                                   | 描述                     |
| ------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------ | ------------------------ |
| **基本颜色**  | `black, red, green, yellow, blue, magenta, cyan, white, gray, grey`                                                                                    | 10种基本文字颜色         |
| **明亮颜色**  | `blackBright, redBright, greenBright, yellowBright, blueBright, magentaBright, cyanBright, whiteBright`                                                | 8种明亮文字颜色          |
| **基本背景**  | `bgBlack, bgRed, bgGreen, bgYellow, bgBlue, bgMagenta, bgCyan, bgWhite, bgGray, bgGrey`                                                                | 10种基本背景颜色         |
| **明亮背景**  | `bgBlackBright, bgRedBright, bgGreenBright, bgYellowBright, bgBlueBright, bgMagentaBright, bgCyanBright, bgWhiteBright`                                | 8种明亮背景颜色          |
| **文字样式**  | `bold, dim, italic, underline, strikethrough, inverse, hidden, overline`                                                                               | 8种文字样式              |
| **真彩色**    | `rgb(r, g, b), bgRgb(r, g, b), hex(color), bgHex(color), hsl(h, s, l), bgHsl(h, s, l), hsv(h, s, v), bgHsv(h, s, v), keyword(color), bgKeyword(color)` | 真彩色支持               |
| **ANSI 颜色** | `ansi(code), bgAnsi(code), ansi256(code), bgAnsi256(code)`                                                                                             | ANSI 颜色码支持          |
| **工具方法**  | `level, supportsColor, Chalk`                                                                                                                          | 颜色支持检测和自定义实例 |

## ⚡ 性能和特性

### 优势

- **链式调用**：支持优雅的链式语法
- **真彩色支持**：支持 1600万种颜色
- **自动检测**：自动检测终端颜色支持
- **零依赖**：不依赖其他库
- **TypeScript支持**：完整的类型定义

### 性能对比

- **功能最全**：支持最多的颜色格式和样式
- **生态丰富**：最多项目使用，社区支持好
- **文件大小**：相对较大（~25KB），但功能更丰富

## 🔗 相关资源

- [GitHub 仓库](https://github.com/chalk/chalk)
- [npm 页面](https://www.npmjs.com/package/chalk)
- [官方文档](https://github.com/chalk/chalk#readme)
- [颜色支持检测](https://github.com/chalk/supports-color)

## 💡 最佳实践

1. **链式调用**：充分利用 Chalk 的链式语法
2. **颜色一致性**：在项目中保持颜色使用的一致性
3. **主题系统**：为复杂项目创建统一的主题系统
4. **性能考虑**：在高频调用时考虑缓存样式函数
5. **可读性**：不要过度使用颜色，保持输出的可读性

---

**Chalk 是功能最全面的终端颜色库，适合需要丰富颜色功能的项目！**