cursor-init/docs/picocolors-guide.md

Picocolors 使用指南

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

📦 安装

# 使用 Bun
bun add picocolors

# 使用 npm
npm install picocolors

# 使用 yarn
yarn add picocolors

🚀 快速开始

import pc from 'picocolors';

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

🎨 完整 API 参考

基本文字颜色

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

明亮文字颜色

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

背景颜色

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

明亮背景颜色

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

文字样式

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

🔧 特殊功能

颜色支持检测

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

自定义颜色支持

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

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

🎯 组合使用

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

// ❌ 错误用法 - 不支持链式调用
// 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('错误信息');

💡 实用示例

日志级别颜色化

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

进度提示

// 加载状态
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 ')) + ' 注意事项');

表格美化

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

代码高亮

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

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

创建主题

// 定义主题
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 仓库
• npm 页面
• 性能对比

---

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