oh-my-logo

在你的终端中创建带有精美渐变色彩的惊艳 ASCII 艺术 Logo！非常适合用作项目横幅、初创公司 Logo，或者只是让你的终端看起来超酷。

你还可以通过将其作为库集成到自己的程序中，生成类似这样的精彩动画！

oh-my-logo 生成的 Logo 均采用 CC0 协议（公有领域），你可以随意在任何地方使用它们。

✨ 特性

• 🎨 两种渲染模式：选择描边的 ASCII 艺术或填充的方块字符
• 🌈 13 种精美调色板：从日落渐变到矩阵绿
• 📐 渐变方向：垂直、水平和对角线渐变
• 🔤 多行支持：创建包含多行文本的 Logo
• ⚡ 零依赖：只需 npx 即可立即运行，无需安装
• 🎛️ 可定制化：使用不同字体并自定义颜色方案
• 🎭 阴影样式：在填充模式下，可通过不同的方块字体自定义阴影效果
• 🔄 字母间距：针对 --filled 模式，调整字符间距以实现不同的视觉密度
• 🔄 反向渐变：翻转颜色调色板，打造独特效果

🚀 快速开始

无需安装！现在就试试：

npx oh-my-logo "HELLO WORLD"

想要填充字符吗？添加 --filled 标志：

npx oh-my-logo "YOUR LOGO" sunset --filled

🆕 v0.3.0 新增功能

在填充模式下自定义阴影样式：

# 方框绘制阴影（默认）
npx oh-my-logo "STYLE" fire --filled --block-font block

# 极简流畅阴影
npx oh-my-logo "STYLE" fire --filled --block-font chrome

# 点状/阴影效果
npx oh-my-logo "STYLE" fire --filled --block-font shade

控制方块字体的字母间距：

# 宽间距（字母间空 5 格）
npx oh-my-logo "WIDE" ocean --filled --letter-spacing 5

# 紧密间距（无空格）
npx oh-my-logo "TIGHT" ocean --filled --letter-spacing 0

反向渐变带来独特效果：

# 反转任意颜色调色板
npx oh-my-logo "REVERSE" sunset --reverse-gradient

# 同样适用于填充模式
npx oh-my-logo "REVERSE" sunset --filled --reverse-gradient

📦 安装

全局安装（CLI）

npm install -g oh-my-logo

或直接使用 npx

npx oh-my-logo "Your Text"

作为库

npm install oh-my-logo

🎯 使用方法

CLI 使用

oh-my-logo <text> [palette] [options]

自定义颜色调色板（CLI）

通过 --palette-colors <colors> 提供自定义渐变。

# JSON 数组（建议使用双引号）
npx oh-my-logo "MY LOGO" --palette-colors '["#00ff00","#ffa500","#ff0000"]'

# 简单的逗号分隔表示法（每种颜色用引号括起来）
npx oh-my-logo "MY LOGO" --palette-colors "'#00ff00', '#ffa500', '#ff0000'"

• 逗号分隔形式便于快速手动 CLI 使用和单行命令。
• JSON 数组形式则适合将调色板存储在 Shell 脚本或 CI 变量中，从 Node.js 中传递 JSON.stringify 的结果，或将数组保存在配置文件中。
• 多余的空白会自动被移除。
• 颜色字符串可以是十六进制代码，也可以是 gradient-string 支持的任何 CSS 颜色。
• 你可以将自定义调色板与其他选项结合使用，例如 --reverse-gradient 或 --filled。
• 位置参数 [palette] 仍然只接受内置调色板名称。

库使用

import { render, renderFilled, PALETTES, getPaletteNames } from 'oh-my-logo';

// 基础 ASCII 艺术渲染
const logo = await render('HELLO WORLD', {
  palette: 'sunset',
  direction: 'horizontal'
});
console.log(logo);

// 使用自定义颜色
const customLogo = await render('MY BRAND', {
  palette: ['#ff0000', '#00ff00', '#0000ff'],
  font: 'Big',
  direction: 'diagonal'
});
console.log(customLogo);

// 填充方块字符
await renderFilled('AWESOME', {
  palette: 'fire'
});

// 填充并使用自定义阴影风格
await renderFilled('SHADOW', {
  palette: 'sunset',
  font: 'shade'  // 使用点状阴影效果
});

// 填充并设置宽间距
await renderFilled('WIDE', {
  palette: 'fire',
  letterSpacing: 3
});

// TypeScript 使用
import { render, RenderOptions, PaletteName } from 'oh-my-logo';

const options: RenderOptions = {
  palette: 'ocean' as PaletteName,
  direction: 'vertical',
  font: 'Standard'
};

const typedLogo = await render('TYPESCRIPT', options);
console.log(typedLogo);

// 获取调色板信息
console.log('可用调色板：', getPaletteNames());
console.log('日落调色板的颜色：', PALETTES.sunset);

参数

• <text>：要显示的文本
  • 使用 "\n" 表示换行："LINE1\nLINE2"
  • 使用 "-" 从标准输入读取
• [palette]：颜色调色板名称（默认：grad-blue）

选项

选项	描述	默认值
-f, --font <name>	Figlet 字体名称	Standard
-d, --direction <dir>	渐变方向（vertical、horizontal、diagonal）	vertical
--filled	使用填充的方块字符代替描边的 ASCII	false
--block-font <font>	填充模式下的字体（3d、block、chrome、grid、huge、pallet、shade、simple、simple3d、simpleBlock、slick、tiny）	-
--letter-spacing <n>	填充模式下的字母间距（字符间的整数空格，≥0）	1
--reverse-gradient	反转渐变颜色	false
--palette-colors <colors>	自定义颜色（JSON 数组或逗号分隔列表）	-
-l, --list-palettes	显示所有可用的调色板	-
--gallery	将文本以所有可用调色板渲染	-
--color	强制启用彩色输出（适用于管道）	-
--no-color	禁用彩色输出	-
-v, --version	显示版本号	-
-h, --help	显示帮助信息	-

🎨 可用调色板（共13种）

查看所有带有预览颜色的调色板：

npx oh-my-logo "" --list-palettes

调色板	颜色	描述
grad-blue	#4ea8ff → #7f88ff	蓝色渐变（默认）
sunset	#ff9966 → #ff5e62 → #ffa34e	温暖的日落色彩
dawn	#00c6ff → #0072ff	清凉的晨间蓝色
nebula	#654ea3 → #eaafc8	紫色的宇宙星云
ocean	#667eea → #764ba2	深邃的海洋蓝
fire	#ff0844 → #ffb199	强烈的火焰色彩
forest	#134e5e → #71b280	自然的绿色调
gold	#f7971e → #ffd200	奢华的金色渐变
purple	#667db6 → #0082c8 → #0078ff	皇家紫到蓝色
mint	#00d2ff → #3a7bd5	清新的薄荷色
coral	#ff9a9e → #fecfef	柔和的珊瑚粉
matrix	#00ff41 → #008f11	经典的黑客帝国绿色
mono	#f07178 → #f07178	单一的珊瑚色

💡 示例

基本用法

# 使用默认蓝色渐变的简单标志
npx oh-my-logo "STARTUP"

# 多行公司标志
npx oh-my-logo "MY\nCOMPANY" sunset

# 黑客风格的矩阵文字
npx oh-my-logo "HACK THE PLANET" matrix --filled

不同的渲染模式

# 默认的描边 ASCII 图形
npx oh-my-logo "CODE" fire

# 填充的方块字符
npx oh-my-logo "CODE" fire --filled

# 使用不同阴影风格的填充效果
npx oh-my-logo "CODE" fire --filled --block-font chrome   # 极简的方框阴影
npx oh-my-logo "CODE" fire --filled --block-font shade    # 点状阴影效果
npx oh-my-logo "CODE" fire --filled --block-font simpleBlock # 简单的 ASCII 阴影

阴影风格（仅限填充模式）

在填充模式下，使用 --block-font 自定义阴影字符：

阴影风格的视觉对比

block（默认） - 方框绘制的阴影：

 ██╗  ██╗ ██╗
 ██║  ██║ ██║
 ███████║ ██║
 ██╔══██║ ██║
 ██║  ██║ ██║
 ╚═╝  ╚═╝ ╚═╝

chrome - 极简时尚的阴影：

 ╦ ╦ ╦
 ╠═╣ ║
 ╩ ╩ ╩

shade - 点状阴影效果：

░░░░░░░░░
░█░░█░███
░█░░█░ █
░████░░█
░█  █░░█
░█░░█░███
░ ░░ ░
░░░░░░░░░

simpleBlock - 基础的 ASCII 阴影：

  _|    _|  _|_|_|
  _|    _|    _|
  _|_|_|_|    _|
  _|    _|    _|
  _|    _|  _|_|_|

# 尝试不同的阴影风格
npx oh-my-logo "SHADOW" sunset --filled --block-font block
npx oh-my-logo "SHADOW" sunset --filled --block-font chrome
npx oh-my-logo "SHADOW" sunset --filled --block-font shade
npx oh-my-logo "SHADOW" sunset --filled --block-font simpleBlock

字母间距控制

调整字符之间的间距以获得不同的视觉密度：

# 默认间距（1个空格）
npx oh-my-logo "HI" --filled
# 输出：  ██╗  ██╗

# 宽间距（3个空格）
npx oh-my-logo "HI" --filled --letter-spacing 3
# 输出：  ██╗   ██╗

# 无间距（紧贴）
npx oh-my-logo "HI" --filled --letter-spacing 0  
# 输出： ██╗██╗

# 注意：小数会被截断（3.7变为3）
npx oh-my-logo "HI" --filled --letter-spacing 3.7  # 实际使用3个空格

反向渐变效果

翻转任何调色板以获得独特的视觉效果：

# 正常的日落渐变（红色→橙色）
npx oh-my-logo "GRADIENT" sunset

# 反向的日落渐变（橙色→红色）
npx oh-my-logo "GRADIENT" sunset --reverse-gradient

# 填充模式同样适用
npx oh-my-logo "GRADIENT" sunset --filled --reverse-gradient

渐变方向

# 默认的垂直渐变
npx oh-my-logo "LOGO" ocean

# 水平渐变
npx oh-my-logo "LOGO" ocean -d horizontal

# 对角线渐变
npx oh-my-logo "LOGO" ocean -d diagonal

自定义字体

# 列出可用字体（取决于你的 figlet 安装）
figlet -f

# 使用不同的字体
npx oh-my-logo "RETRO" purple -f "Big"

管道与脚本

# 从标准输入读取
echo "DYNAMIC LOGO" | npx oh-my-logo - gold --filled

# 在脚本中强制指定颜色
npx oh-my-logo "DEPLOY SUCCESS" forest --color

# 纯文本输出
npx oh-my-logo "LOG ENTRY" --no-color

画廊模式

# 以所有可用调色板显示文本
npx oh-my-logo "PREVIEW" --gallery

# 填充字符的画廊
npx oh-my-logo "COLORS" --gallery --filled

# 比较多行文本在所有调色板中的效果
npx oh-my-logo "MY\nLOGO" --gallery

# 使用自定义字体的画廊
npx oh-my-logo "STYLES" --gallery -f Big

🎭 使用场景

• 项目横幅：为你的 README 文件添加引人注目的标题
• 终端启动时显示：在打开终端时显示公司标志
• CI/CD 流水线：让部署日志更具视觉吸引力
• 开发工具：为你的命令行应用程序打造品牌
• 演示文稿：创建精彩的终端演示
• 个人品牌：为你的 shell 提示符或脚本增添特色

⚙️ 环境变量

变量	描述	示例
OHMYLOGO_FONT	默认 figlet 字体	export OHMYLOGO_FONT="Big"

📚 库 API

核心函数

render(text, options?)

渲染带有渐变颜色的 ASCII 图形。

async function render(text: string, options?: RenderOptions): Promise<string>

• text（字符串）：要显示的文本
• options.palette（PaletteName | string[]）：调色板名称或自定义颜色
• options.font（字符串）：Figlet 字体名称（默认：'Standard'）
• options.direction（'vertical' | 'horizontal' | 'diagonal'）：渐变方向

返回值：Promise<string> - 彩色的 ASCII 图形

renderFilled(text, options?)

渲染带有渐变的填充方块字符。

async function renderFilled(text: string, options?: RenderInkOptions): Promise<void>

• text（字符串）：要显示的文本
• options.palette（PaletteName | string[]）：调色板名称或自定义颜色
• options.font（BlockFont）：阴影风格（'block' | 'chrome' | 'shade' | 'simpleBlock' | '3d'）
• options.letterSpacing（数字）：字符之间的空格数（0 或以上，默认：1）

返回值：Promise<void> - 直接渲染到标准输出

调色板相关函数

• PALETTES：包含所有内置调色板的对象
• resolvePalette(name)：根据名称获取调色板颜色
• getPaletteNames()：获取所有调色板名称的数组
• getDefaultPalette()：获取默认调色板的颜色
• getPalettePreview(name)：获取调色板颜色的预览字符串

类型定义

type PaletteName = 'grad-blue' | 'sunset' | 'dawn' | 'nebula' | 'ocean' | 
                   'fire' | 'forest' | 'gold' | 'purple' | 'mint' | 
                   'coral' | 'matrix' | 'mono';

interface RenderOptions {
  palette?: PaletteName | string[];
  font?: string;
  direction?: 'vertical' | 'horizontal' | 'diagonal';
}

type BlockFont = '3d' | 'block' | 'chrome' | 'console' | 'grid' | 
                 'huge' | 'pallet' | 'shade' | 'simple' | 'simple3d' | 
                 'simpleBlock' | 'slick' | 'tiny';

interface RenderInkOptions {
  palette?: PaletteName | string[];
  font?: BlockFont;
  letterSpacing?: number;
}

🛠️ 开发

想贡献代码或进行自定义吗？

git clone https://github.com/yourusername/oh-my-logo.git
cd oh-my-logo
npm install

# 开发模式
npm run dev -- "TEST" sunset --filled

# 构建
npm run build

# 测试构建后的版本
node dist/index.js "HELLO" matrix --filled

🧪 测试

使用 Vitest 运行测试套件：

# 在监听模式下运行所有测试
npm run test

# 单次运行测试（CI 模式）
npm run test:coverage

# 带 UI 的测试
npm run test:ui

# 运行特定测试文件
npm test -- src/__tests__/cli.test.ts

测试套件包括：

• 所有库函数的单元测试
• CLI 集成测试
• 颜色调色板验证
• 错误处理场景
• TTY/颜色检测逻辑

测试文件位于 src/__tests__/，结构如下：

• cli.test.ts - CLI 命令行行为
• lib.test.ts - 库 API 函数
• palettes.test.ts - 颜色调色板系统
• renderer.test.ts - ASCII 艺术渲染
• utils/ - 工具函数测试

终端稳定性测试

提供了一个测试脚本，用于验证 --filled 模式是否能正确清理终端状态：

# 运行终端稳定性压力测试
./scripts/test-filled-mode.sh

该脚本：

• 连续运行 55 次渲染（5 次迭代 × 11 种字体）
• 使用随机颜色调色板测试所有可用字体
• 验证在大量使用后终端显示仍保持完整
• 帮助检测任何终端损坏问题

这尤其适用于：

• 对 Ink 渲染器进行修改后测试
• 验证不同环境下的终端兼容性
• 对 --filled 模式的实现进行压力测试

添加新调色板

编辑 src/palettes.ts 来添加您自己的颜色组合：

export const PALETTES = {
  // ... 现有的调色板
  'my-palette': ['#ff0000', '#00ff00', '#0000ff'],
} as const;

🤝 贡献

欢迎贡献！请随时提交 Pull Request。无论是：

• 🎨 新的颜色调色板
• 🔧 Bug 修复
• ✨ 新功能
• 📖 文档改进

📄 许可证

MIT 和 CC0-1.0

---

为终端爱好者用心打造

将枯燥的文字转化为惊艳的视觉 Logo！

oh-my-logo 快速上手指南

oh-my-logo 是一个强大的命令行工具，用于在终端中生成带有精美渐变色彩的 ASCII 艺术 Logo。它无需复杂配置，支持多种渲染模式（轮廓或填充块）、13 种内置配色方案以及自定义字体，非常适合用于项目横幅、启动画面或 CLI 工具的品牌展示。

环境准备

• 操作系统：Windows, macOS, Linux
• 前置依赖：
  • 已安装 Node.js (建议版本 14.x 或更高)
  • 已安装 npm (随 Node.js 自动安装)
• 网络提示：由于 npx 需要从 npm 官方仓库拉取包，国内用户若遇到下载缓慢或超时问题，建议临时切换至淘宝镜像源：

  npm config set registry https://registry.npmmirror.com
  

安装步骤

你可以选择免安装直接使用（推荐尝试）或全局安装。

方式一：免安装直接使用 (npx)

无需任何安装步骤，直接运行以下命令即可体验：

npx oh-my-logo "HELLO WORLD"

方式二：全局安装 (CLI)

如果你需要频繁使用该命令，建议全局安装：

npm install -g oh-my-logo

安装完成后，可直接在任何目录运行 oh-my-logo 命令。

方式三：作为库安装 (开发集成)

若需在 Node.js 项目中通过代码调用：

npm install oh-my-logo

基本使用

1. 生成基础 Logo

最简单的用法是直接传入文本，默认使用蓝色渐变和标准字体：

npx oh-my-logo "STARTUP"

2. 指定配色方案

在文本后添加内置配色名称（如 sunset, fire, matrix 等）：

npx oh-my-logo "MY LOGO" sunset

3. 使用填充块模式 (--filled)

生成更具视觉冲击力的实心块状 Logo：

npx oh-my-logo "AWESOME" fire --filled

4. 多行文本支持

使用 \n 换行符创建多行 Logo：

npx oh-my-logo "LINE1\nLINE2" ocean

5. 预览所有配色

查看支持的 13 种配色方案及其效果：

npx oh-my-logo "" --list-palettes

提示：生成的 ASCII 艺术图遵循 CC0 协议（公共领域），可自由用于任何商业或个人项目。