438 lines
10 KiB
Markdown
438 lines
10 KiB
Markdown
# FreezeLib - 美观代码截图的 Go 库
|
||
|
||
**Language / 语言**: [English](README.md) | [中文](README_CN.md)
|
||
|
||
**Documentation / 文档**: [Usage Guide (English)](USAGE_EN.md) | [使用指南 (中文)](USAGE.md)
|
||
|
||
FreezeLib 是一个用于生成美观代码和终端输出截图的 Go 库。它基于 Charm 团队广受欢迎的 [freeze](https://github.com/charmbracelet/freeze) CLI 工具，但重新设计为可在 Go 应用程序中重复使用的库。
|
||
|
||
## 特性
|
||
|
||
- 🎨 **语法高亮**: 支持 270+ 种编程语言
|
||
- 🔍 **自动语言检测**: 智能检测代码内容和文件名的语言
|
||
- 📋 **简单列表**: 轻松访问所有可用的语言、主题和预设
|
||
- 🖼️ **多种输出格式**: 生成 SVG 和 PNG 图像
|
||
- 🎭 **丰富主题**: 67+ 内置主题，包括 GitHub、Dracula、Monokai 等
|
||
- 🪟 **窗口控件**: macOS 风格的窗口装饰
|
||
- 📏 **行号**: 可选的行号显示
|
||
- 🌈 **ANSI 支持**: 渲染彩色终端输出
|
||
- ⚡ **简易 API**: 简单且可链式调用的 API 设计
|
||
- 🎯 **预设配置**: 10 种预配置样式，适用于常见用例
|
||
- 🔧 **高度可定制**: 精细调整输出的每个方面
|
||
|
||
## 安装
|
||
|
||
```bash
|
||
go get github.com/landaiqing/freezelib
|
||
```
|
||
|
||
## 快速开始
|
||
|
||
### 基本用法
|
||
|
||
```go
|
||
package main
|
||
|
||
import (
|
||
"os"
|
||
"github.com/landaiqing/freezelib"
|
||
)
|
||
|
||
func main() {
|
||
// 创建新的 freeze 实例
|
||
freeze := freezelib.New()
|
||
|
||
// 要截图的 Go 代码
|
||
code := `package main
|
||
|
||
import "fmt"
|
||
|
||
func main() {
|
||
fmt.Println("Hello, World!")
|
||
}`
|
||
|
||
// 生成 SVG
|
||
svgData, err := freeze.GenerateFromCode(code, "go")
|
||
if err != nil {
|
||
panic(err)
|
||
}
|
||
|
||
// 保存到文件
|
||
os.WriteFile("hello.svg", svgData, 0644)
|
||
}
|
||
```
|
||
|
||
### 自动语言检测
|
||
|
||
FreezeLib 可以自动检测编程语言：
|
||
|
||
```go
|
||
freeze := freezelib.New()
|
||
|
||
// 从代码内容自动检测语言
|
||
svgData, err := freeze.GenerateFromCodeAuto(code)
|
||
|
||
// 手动检测语言
|
||
language := freeze.DetectLanguage(code)
|
||
fmt.Printf("检测到的语言: %s", language)
|
||
|
||
// 从文件名检测语言
|
||
language = freeze.DetectLanguageFromFilename("script.py")
|
||
|
||
// 组合检测（文件名 + 内容）
|
||
language = freeze.DetectLanguageFromFile("script.py", code)
|
||
```
|
||
|
||
### 可用选项
|
||
|
||
获取所有可用选项的列表：
|
||
|
||
```go
|
||
freeze := freezelib.New()
|
||
|
||
// 获取所有可用选项（排序列表）
|
||
languages := freeze.GetSupportedLanguages() // 270+ 种语言
|
||
themes := freeze.GetSupportedThemes() // 67+ 种主题
|
||
presets := freeze.GetAvailablePresets() // 10 种预设
|
||
|
||
// 测试支持
|
||
isSupported := freeze.IsLanguageSupported("go")
|
||
isSupported = freeze.IsThemeSupported("github")
|
||
isValid := freezelib.IsValidPreset("dark")
|
||
|
||
// 全局函数也可用
|
||
languages = freezelib.GetSupportedLanguages()
|
||
themes = freezelib.GetSupportedThemes()
|
||
presets = freezelib.GetAvailablePresets()
|
||
```
|
||
|
||
### QuickFreeze API
|
||
|
||
为了更流畅的体验，使用 QuickFreeze API：
|
||
|
||
```go
|
||
qf := freezelib.NewQuickFreeze()
|
||
|
||
svgData, err := qf.WithTheme("dracula").
|
||
WithFont("Fira Code", 14).
|
||
WithWindow().
|
||
WithShadow().
|
||
WithLineNumbers().
|
||
CodeToSVGAuto(code) // 自动检测语言
|
||
```
|
||
|
||
## API 参考
|
||
|
||
### 核心类型
|
||
|
||
#### Freeze
|
||
|
||
生成截图的主要接口：
|
||
|
||
```go
|
||
freeze := freezelib.New() // 默认配置
|
||
freeze := freezelib.NewWithConfig(config) // 自定义配置
|
||
freeze := freezelib.NewWithPreset("dark") // 预设配置
|
||
```
|
||
|
||
#### QuickFreeze
|
||
|
||
简化的链式 API：
|
||
|
||
```go
|
||
qf := freezelib.NewQuickFreeze()
|
||
qf := freezelib.NewQuickFreezeWithPreset("terminal")
|
||
```
|
||
|
||
### 生成方法
|
||
|
||
#### 从代码字符串
|
||
```go
|
||
svgData, err := freeze.GenerateFromCode(code, "python")
|
||
pngData, err := freeze.GeneratePNGFromCode(code, "python")
|
||
|
||
// 使用自动语言检测
|
||
svgData, err := freeze.GenerateFromCodeAuto(code)
|
||
pngData, err := freeze.GeneratePNGFromCodeAuto(code)
|
||
```
|
||
|
||
#### 从文件
|
||
```go
|
||
svgData, err := freeze.GenerateFromFile("main.go")
|
||
pngData, err := freeze.GeneratePNGFromFile("main.go")
|
||
```
|
||
|
||
#### 从 ANSI 终端输出
|
||
```go
|
||
terminalOutput := "\033[32mSUCCESS\033[0m: Build completed"
|
||
svgData, err := freeze.GenerateFromANSI(terminalOutput)
|
||
pngData, err := freeze.GeneratePNGFromANSI(terminalOutput)
|
||
```
|
||
|
||
#### 从 Reader
|
||
```go
|
||
svgData, err := freeze.GenerateFromReader(reader, "javascript")
|
||
```
|
||
|
||
### 配置
|
||
|
||
#### 基本配置
|
||
```go
|
||
config := freezelib.DefaultConfig()
|
||
config.SetTheme("github-dark")
|
||
config.SetFont("JetBrains Mono", 14)
|
||
config.SetBackground("#1e1e1e")
|
||
config.SetWindow(true)
|
||
config.SetLineNumbers(true)
|
||
```
|
||
|
||
#### 高级配置
|
||
```go
|
||
config.SetPadding(20) // 所有边
|
||
config.SetPadding(20, 40) // 垂直，水平
|
||
config.SetPadding(20, 40, 20, 40) // 上，右，下，左
|
||
|
||
config.SetShadow(20, 0, 10) // 模糊，X 偏移，Y 偏移
|
||
config.SetBorder(1, 8, "#333") // 宽度，圆角，颜色
|
||
config.SetDimensions(800, 600) // 宽度，高度
|
||
config.SetLines(10, 20) // 行范围（1-indexed）
|
||
```
|
||
|
||
### 预设
|
||
|
||
FreezeLib 提供了几个内置预设：
|
||
|
||
```go
|
||
// 可用预设（10 种）
|
||
presets := []string{
|
||
"base", // 基础配置
|
||
"full", // 完整功能配置
|
||
"terminal", // 终端风格
|
||
"dark", // 深色主题
|
||
"light", // 浅色主题
|
||
"minimal", // 极简风格
|
||
"professional", // 专业风格
|
||
"vibrant", // 鲜艳配色
|
||
"retro", // 复古风格
|
||
"neon", // 霓虹风格
|
||
}
|
||
|
||
freeze := freezelib.NewWithPreset("dark")
|
||
```
|
||
|
||
### 链式方法
|
||
|
||
`Freeze` 和 `QuickFreeze` 都支持方法链：
|
||
|
||
```go
|
||
freeze := freezelib.New().
|
||
WithTheme("monokai").
|
||
WithFont("Cascadia Code", 15).
|
||
WithWindow(true).
|
||
WithShadow(20, 0, 10).
|
||
WithLineNumbers(true)
|
||
|
||
svgData, err := freeze.GenerateFromCode(code, "rust")
|
||
```
|
||
|
||
## 示例
|
||
|
||
查看 `examples/` 目录获取完整示例：
|
||
|
||
- `01-basic/` - 基础用法示例
|
||
- `02-formats/` - 输出格式示例
|
||
- `03-themes/` - 主题展示
|
||
- `04-languages/` - 语言支持示例
|
||
- `05-terminal/` - 终端输出示例
|
||
- `06-advanced/` - 高级配置
|
||
- `07-batch/` - 批量处理
|
||
- `08-auto-language-detection/` - 自动语言检测
|
||
- `09-supported-options/` - 支持选项列表
|
||
|
||
### 终端输出截图
|
||
|
||
```go
|
||
freeze := freezelib.NewWithPreset("terminal")
|
||
|
||
ansiOutput := "\033[32m✓ Tests passed\033[0m\n" +
|
||
"\033[31m✗ Build failed\033[0m\n" +
|
||
"\033[33m⚠ Warning: deprecated API\033[0m"
|
||
|
||
svgData, err := freeze.GenerateFromANSI(ansiOutput)
|
||
```
|
||
|
||
### 自定义样式
|
||
|
||
```go
|
||
config := freezelib.DefaultConfig()
|
||
config.Theme = "github"
|
||
config.Background = "#f6f8fa"
|
||
config.Font.Family = "SF Mono"
|
||
config.Font.Size = 16
|
||
config.SetPadding(30)
|
||
config.SetMargin(20)
|
||
config.Window = true
|
||
config.ShowLineNumbers = true
|
||
config.Border.Radius = 12
|
||
config.Shadow.Blur = 25
|
||
|
||
freeze := freezelib.NewWithConfig(config)
|
||
```
|
||
|
||
### 批量处理
|
||
|
||
```go
|
||
files := []string{"main.go", "config.go", "utils.go"}
|
||
|
||
for _, file := range files {
|
||
svgData, err := freeze.GenerateFromFile(file)
|
||
if err != nil {
|
||
continue
|
||
}
|
||
|
||
outputFile := strings.TrimSuffix(file, ".go") + ".svg"
|
||
os.WriteFile(outputFile, svgData, 0644)
|
||
}
|
||
```
|
||
|
||
## 支持的语言
|
||
|
||
FreezeLib 支持 270+ 种编程语言的语法高亮：
|
||
|
||
### 热门语言
|
||
- **系统级**: Go, Rust, C, C++, Zig, D, Nim, V
|
||
- **Web**: JavaScript, TypeScript, HTML, CSS, SCSS, PHP
|
||
- **企业级**: Java, C#, Kotlin, Scala, Swift
|
||
- **脚本**: Python, Ruby, Perl, Lua, Bash, PowerShell
|
||
- **数据**: JSON, YAML, TOML, XML, SQL, GraphQL
|
||
|
||
### 分类
|
||
- **热门** (30): 最常用的语言
|
||
- **Web** (15): 前端和后端 Web 技术
|
||
- **系统** (13): 底层和系统编程
|
||
- **脚本** (12): 自动化和脚本语言
|
||
- **数据** (11): 配置和数据格式
|
||
- **更多**: 总共支持 270+ 种语言
|
||
|
||
## 支持的主题
|
||
|
||
FreezeLib 包含 67+ 种语法高亮主题：
|
||
|
||
### 热门主题
|
||
- **GitHub**: `github`, `github-dark`
|
||
- **现代**: `dracula`, `monokai`, `nord`, `one-dark`
|
||
- **经典**: `solarized-dark`, `solarized-light`, `material`, `vim`
|
||
- **多彩**: `colorful`, `friendly`, `fruity`, `rainbow_dash`
|
||
|
||
### 分类
|
||
- **热门** (30): 最常用的主题
|
||
- **深色** (10): 适合低光环境的深色配色方案
|
||
- **浅色** (14): 适合明亮环境的浅色配色方案
|
||
- **更多**: 总共 67+ 种主题可用
|
||
|
||
### 简单高效
|
||
所有列表都按字母顺序排序，便于浏览和选择。
|
||
|
||
## 语言检测功能
|
||
|
||
### 自动检测方法
|
||
```go
|
||
freeze := freezelib.New()
|
||
|
||
// 从代码内容检测语言
|
||
language := freeze.DetectLanguage(code)
|
||
|
||
// 从文件名检测
|
||
language = freeze.DetectLanguageFromFilename("script.py")
|
||
|
||
// 组合检测（文件名 + 内容）
|
||
language = freeze.DetectLanguageFromFile("script.py", code)
|
||
|
||
// 检查语言支持
|
||
supported := freeze.IsLanguageSupported("go")
|
||
|
||
// 获取所有支持的语言
|
||
languages := freeze.GetSupportedLanguages()
|
||
```
|
||
|
||
### 自定义语言检测器
|
||
```go
|
||
detector := freeze.GetLanguageDetector()
|
||
|
||
// 添加自定义文件扩展名映射
|
||
detector.AddCustomMapping(".myext", "python")
|
||
detector.AddCustomMapping(".config", "json")
|
||
|
||
// 配置检测策略
|
||
detector.EnableContentAnalysis = true
|
||
detector.EnableFilenameAnalysis = true
|
||
detector.FallbackLanguage = "text"
|
||
```
|
||
|
||
## 支持选项
|
||
|
||
### 获取所有可用选项
|
||
```go
|
||
freeze := freezelib.New()
|
||
|
||
// 获取所有可用选项（排序列表）
|
||
languages := freeze.GetSupportedLanguages() // 270+ 种语言
|
||
themes := freeze.GetSupportedThemes() // 67+ 种主题
|
||
presets := freeze.GetAvailablePresets() // 10 种预设
|
||
|
||
// 测试支持
|
||
isSupported := freeze.IsLanguageSupported("go")
|
||
isSupported = freeze.IsThemeSupported("github")
|
||
isValid := freezelib.IsValidPreset("dark")
|
||
|
||
// 全局函数也可用
|
||
languages = freezelib.GetSupportedLanguages()
|
||
themes = freezelib.GetSupportedThemes()
|
||
presets = freezelib.GetAvailablePresets()
|
||
```
|
||
|
||
### 验证支持
|
||
```go
|
||
// 检查支持
|
||
if freeze.IsLanguageSupported("go") {
|
||
// 生成 Go 代码截图
|
||
}
|
||
|
||
if freeze.IsThemeSupported("dracula") {
|
||
// 使用 Dracula 主题
|
||
}
|
||
|
||
if freezelib.IsValidPreset("dark") {
|
||
// 使用深色预设
|
||
}
|
||
```
|
||
|
||
## 错误处理
|
||
|
||
```go
|
||
svgData, err := freeze.GenerateFromCode(code, "go")
|
||
if err != nil {
|
||
// 处理特定错误
|
||
switch {
|
||
case strings.Contains(err.Error(), "language"):
|
||
// 语言检测失败
|
||
case strings.Contains(err.Error(), "config"):
|
||
// 配置错误
|
||
default:
|
||
// 其他错误
|
||
}
|
||
}
|
||
```
|
||
|
||
## 贡献
|
||
|
||
欢迎贡献！请随时提交 Pull Request。
|
||
|
||
## 许可证
|
||
|
||
MIT 许可证 - 详见 [LICENSE](./LICENSE) 文件。
|
||
|
||
## 致谢
|
||
|
||
本库基于 [Charm](https://charm.sh) 团队出色的 [freeze](https://github.com/charmbracelet/freeze) CLI 工具。特别感谢 Charm 团队创造了如此美观的工具。
|