cursor-init/docs/chalk-guide.md

Chalk 使用指南

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

📦 安装

# 使用 Bun
bun add chalk

# 使用 npm
npm install chalk

# 使用 yarn
yarn add chalk

🚀 快速开始

import chalk from 'chalk';

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

🎨 完整 API 参考

基本文字颜色

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

明亮文字颜色

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

背景颜色

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

明亮背景颜色

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

文字样式

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

🔗 链式调用（Chalk 的特色）

// 单一样式
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 颜色

// 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 颜色

// 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 背景色

颜色支持检测

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

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

创建自定义实例

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)('强制显示红色'));

💡 实用示例

日志级别颜色化

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');

进度条和状态

// 进度条
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 + ' 操作失败！');

表格美化

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)}`);
});

代码语法高亮

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));

彩虹文字效果

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!'));

渐变效果

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 日志器集成

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 工具美化

// 命令行工具的美化输出
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();

创建主题系统

// 定义主题
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 仓库
• npm 页面
• 官方文档
• 颜色支持检测

💡 最佳实践

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

---

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