✨ added support for language, topic, and preset acquisition and detection functions
This commit is contained in:
350
USAGE.md
350
USAGE.md
@@ -2,13 +2,17 @@
|
||||
|
||||
**Language / 语言**: [English](USAGE_EN.md) | [中文](USAGE.md)
|
||||
|
||||
**Main Documentation / 主要文档**: [README (English)](README.md) | [README (中文)](README_CN.md)
|
||||
FreezeLib 是一个 Go 库，用于生成美观的代码截图。
|
||||
|
||||
FreezeLib 是一个基于 Charm 的 freeze CLI 工具重构的 Go 公共库，用于生成美观的代码截图。
|
||||
## 安装
|
||||
|
||||
## 🚀 快速开始
|
||||
```bash
|
||||
go get github.com/landaiqing/freezelib
|
||||
```
|
||||
|
||||
### 基本用法
|
||||
## 基本使用
|
||||
|
||||
### 1. 最简单的例子
|
||||
|
||||
```go
|
||||
package main
|
||||
@@ -19,10 +23,10 @@ import (
|
||||
)
|
||||
|
||||
func main() {
|
||||
// 创建 freeze 实例
|
||||
// 创建实例
|
||||
freeze := freezelib.New()
|
||||
|
||||
// 要截图的代码
|
||||
// 代码内容
|
||||
code := `package main
|
||||
|
||||
import "fmt"
|
||||
@@ -37,228 +41,194 @@ func main() {
|
||||
panic(err)
|
||||
}
|
||||
|
||||
// 保存到文件
|
||||
// 保存文件
|
||||
os.WriteFile("hello.svg", svgData, 0644)
|
||||
}
|
||||
```
|
||||
|
||||
### 链式调用 API
|
||||
### 2. 从文件生成
|
||||
|
||||
```go
|
||||
// 使用 QuickFreeze 进行链式调用
|
||||
qf := freezelib.NewQuickFreeze()
|
||||
|
||||
svgData, err := qf.WithTheme("dracula").
|
||||
WithFont("Fira Code", 14).
|
||||
WithWindow().
|
||||
WithShadow().
|
||||
WithLineNumbers().
|
||||
WithLanguage("javascript").
|
||||
CodeToSVG(code)
|
||||
```
|
||||
|
||||
## 📋 主要功能
|
||||
|
||||
### 1. 多种输入方式
|
||||
|
||||
```go
|
||||
// 从代码字符串生成
|
||||
svgData, err := freeze.GenerateFromCode(code, "python")
|
||||
|
||||
// 从文件生成
|
||||
// 直接从文件生成
|
||||
svgData, err := freeze.GenerateFromFile("main.go")
|
||||
|
||||
// 从 ANSI 终端输出生成
|
||||
ansiOutput := "\033[32m✓ SUCCESS\033[0m: Build completed"
|
||||
svgData, err := freeze.GenerateFromANSI(ansiOutput)
|
||||
|
||||
// 从 Reader 生成
|
||||
svgData, err := freeze.GenerateFromReader(reader, "javascript")
|
||||
if err != nil {
|
||||
panic(err)
|
||||
}
|
||||
os.WriteFile("main.svg", svgData, 0644)
|
||||
```
|
||||
|
||||
### 2. 多种输出格式
|
||||
### 3. 生成 PNG 格式
|
||||
|
||||
```go
|
||||
// 生成 SVG
|
||||
svgData, err := freeze.GenerateFromCode(code, "go")
|
||||
|
||||
// 生成 PNG
|
||||
// 生成 PNG 而不是 SVG
|
||||
pngData, err := freeze.GeneratePNGFromCode(code, "go")
|
||||
|
||||
// 直接保存到文件
|
||||
err := freeze.SaveCodeToFile(code, "go", "output.svg")
|
||||
err := freeze.SaveCodeToFile(code, "go", "output.png") // 自动检测格式
|
||||
if err != nil {
|
||||
panic(err)
|
||||
}
|
||||
os.WriteFile("hello.png", pngData, 0644)
|
||||
```
|
||||
|
||||
### 3. 预设配置
|
||||
### 4. 直接保存到文件
|
||||
|
||||
```go
|
||||
// 使用预设配置
|
||||
// 一步完成：生成并保存
|
||||
err := freeze.SaveCodeToFile(code, "go", "output.svg")
|
||||
if err != nil {
|
||||
panic(err)
|
||||
}
|
||||
|
||||
// 自动检测格式（根据文件扩展名）
|
||||
err = freeze.SaveCodeToFile(code, "go", "output.png")
|
||||
```
|
||||
|
||||
## 使用预设样式
|
||||
|
||||
```go
|
||||
// 使用预设配置，快速开始
|
||||
freeze := freezelib.NewWithPreset("dark") // 深色主题
|
||||
freeze := freezelib.NewWithPreset("terminal") // 终端风格
|
||||
freeze := freezelib.NewWithPreset("presentation") // 演示风格
|
||||
|
||||
// 可用预设
|
||||
presets := []string{
|
||||
"base", // 基础样式
|
||||
"full", // macOS 风格
|
||||
"terminal", // 终端优化
|
||||
"presentation", // 演示优化
|
||||
"minimal", // 极简风格
|
||||
"dark", // 深色主题
|
||||
"light", // 浅色主题
|
||||
"retro", // 复古风格
|
||||
"neon", // 霓虹风格
|
||||
"compact", // 紧凑风格
|
||||
}
|
||||
// 查看所有可用预设
|
||||
presets := freeze.GetAvailablePresets()
|
||||
// 返回: ["base", "compact", "dark", "full", "light", "minimal", "neon", "presentation", "retro", "terminal"]
|
||||
```
|
||||
|
||||
### 4. 自定义配置
|
||||
## 自定义样式
|
||||
|
||||
```go
|
||||
config := freezelib.DefaultConfig()
|
||||
|
||||
// 基本设置
|
||||
config.SetTheme("github-dark")
|
||||
config.SetFont("JetBrains Mono", 14)
|
||||
config.SetBackground("#1e1e1e")
|
||||
config.SetLanguage("python")
|
||||
|
||||
// 布局设置
|
||||
config.SetPadding(20) // 所有边
|
||||
config.SetPadding(20, 40) // 垂直，水平
|
||||
config.SetPadding(20, 40, 20, 40) // 上，右，下，左
|
||||
config.SetMargin(15)
|
||||
config.SetDimensions(800, 600)
|
||||
|
||||
// 装饰效果
|
||||
config.SetWindow(true) // 窗口控件
|
||||
config.SetLineNumbers(true) // 行号
|
||||
config.SetShadow(20, 0, 10) // 阴影：模糊，X偏移，Y偏移
|
||||
config.SetBorder(1, 8, "#333") // 边框：宽度，圆角，颜色
|
||||
|
||||
// 行范围（1-indexed）
|
||||
config.SetLines(10, 20) // 只截取第10-20行
|
||||
|
||||
freeze := freezelib.NewWithConfig(config)
|
||||
```
|
||||
|
||||
## 🎨 支持的主题
|
||||
|
||||
- `github` / `github-dark`
|
||||
- `dracula`
|
||||
- `monokai`
|
||||
- `solarized-dark` / `solarized-light`
|
||||
- `nord`
|
||||
- `one-dark`
|
||||
- `material`
|
||||
- `vim`
|
||||
- 等等...
|
||||
|
||||
## 💻 支持的语言
|
||||
|
||||
支持 100+ 种编程语言，包括：
|
||||
- Go, Rust, Python, JavaScript, TypeScript
|
||||
- C, C++, C#, Java, Kotlin, Swift
|
||||
- HTML, CSS, SCSS, JSON, YAML, XML
|
||||
- Shell, PowerShell, Dockerfile
|
||||
- SQL, GraphQL, Markdown
|
||||
- 等等...
|
||||
|
||||
## 🔧 高级用法
|
||||
|
||||
### 批量处理
|
||||
|
||||
```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)
|
||||
}
|
||||
```
|
||||
|
||||
### 终端输出截图
|
||||
|
||||
```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
|
||||
freeze := freezelib.New().
|
||||
WithTheme("monokai").
|
||||
WithFont("Cascadia Code", 15).
|
||||
WithWindow(true).
|
||||
WithShadow(20, 0, 10).
|
||||
WithLineNumbers(true)
|
||||
WithTheme("github-dark"). // 设置主题
|
||||
WithFont("JetBrains Mono", 14). // 设置字体和大小
|
||||
WithBackground("#1e1e1e"). // 设置背景色
|
||||
WithPadding(20) // 设置内边距
|
||||
|
||||
svgData, err := freeze.GenerateFromCode(code, "rust")
|
||||
svgData, err := freeze.GenerateFromCode(code, "go")
|
||||
```
|
||||
|
||||
## 📊 性能优化建议
|
||||
### 添加装饰效果
|
||||
|
||||
1. **重用实例**：创建一个 `Freeze` 实例并重复使用
|
||||
2. **选择合适格式**：网页用 SVG，演示用 PNG
|
||||
3. **设置具体尺寸**：指定尺寸可提高性能
|
||||
4. **批量操作**：在单个会话中处理多个文件
|
||||
```go
|
||||
freeze := freezelib.New().
|
||||
WithTheme("dracula").
|
||||
WithWindow(true). // 添加窗口控件
|
||||
WithLineNumbers(true). // 显示行号
|
||||
WithShadow(20, 0, 10) // 添加阴影
|
||||
|
||||
## 🐛 错误处理
|
||||
svgData, err := freeze.GenerateFromCode(code, "python")
|
||||
```
|
||||
|
||||
## 查看支持的选项
|
||||
|
||||
```go
|
||||
freeze := freezelib.New()
|
||||
|
||||
// 查看所有支持的语言（270+ 种）
|
||||
languages := freeze.GetSupportedLanguages()
|
||||
fmt.Printf("支持 %d 种语言\n", len(languages))
|
||||
|
||||
// 查看所有支持的主题（67+ 种）
|
||||
themes := freeze.GetSupportedThemes()
|
||||
fmt.Printf("支持 %d 种主题\n", len(themes))
|
||||
|
||||
// 查看所有可用预设（10 种）
|
||||
presets := freeze.GetAvailablePresets()
|
||||
fmt.Printf("可用预设: %v\n", presets)
|
||||
```
|
||||
|
||||
## 终端输出截图
|
||||
|
||||
```go
|
||||
// 截图终端输出（支持 ANSI 颜色）
|
||||
freeze := freezelib.NewWithPreset("terminal")
|
||||
|
||||
ansiOutput := "\033[32m✓ 测试通过\033[0m\n" +
|
||||
"\033[31m✗ 构建失败\033[0m\n" +
|
||||
"\033[33m⚠ 警告: API 已废弃\033[0m"
|
||||
|
||||
svgData, err := freeze.GenerateFromANSI(ansiOutput)
|
||||
if err != nil {
|
||||
panic(err)
|
||||
}
|
||||
os.WriteFile("terminal.svg", svgData, 0644)
|
||||
```
|
||||
|
||||
## 批量处理文件
|
||||
|
||||
```go
|
||||
freeze := freezelib.NewWithPreset("dark")
|
||||
files := []string{"main.go", "config.go", "utils.go"}
|
||||
|
||||
for _, file := range files {
|
||||
err := freeze.SaveFileToFile(file, file+".svg")
|
||||
if err != nil {
|
||||
fmt.Printf("处理 %s 失败: %v\n", file, err)
|
||||
continue
|
||||
}
|
||||
fmt.Printf("已生成: %s.svg\n", file)
|
||||
}
|
||||
```
|
||||
|
||||
## 自动语言检测
|
||||
|
||||
```go
|
||||
freeze := freezelib.New()
|
||||
|
||||
// 不指定语言，自动检测
|
||||
code := `function hello() {
|
||||
console.log("Hello, World!");
|
||||
}`
|
||||
|
||||
// 自动检测为 JavaScript
|
||||
svgData, err := freeze.GenerateFromCodeAuto(code)
|
||||
if err != nil {
|
||||
panic(err)
|
||||
}
|
||||
os.WriteFile("auto.svg", svgData, 0644)
|
||||
```
|
||||
|
||||
## 错误处理
|
||||
|
||||
```go
|
||||
svgData, err := freeze.GenerateFromCode(code, "go")
|
||||
if err != nil {
|
||||
switch {
|
||||
case strings.Contains(err.Error(), "language"):
|
||||
// 语言检测失败
|
||||
case strings.Contains(err.Error(), "config"):
|
||||
// 配置错误
|
||||
default:
|
||||
// 其他错误
|
||||
}
|
||||
fmt.Printf("生成失败: %v\n", err)
|
||||
return
|
||||
}
|
||||
|
||||
// 保存文件
|
||||
err = os.WriteFile("output.svg", svgData, 0644)
|
||||
if err != nil {
|
||||
fmt.Printf("保存失败: %v\n", err)
|
||||
return
|
||||
}
|
||||
|
||||
fmt.Println("生成成功!")
|
||||
```
|
||||
|
||||
## 📁 项目结构
|
||||
## 常用主题
|
||||
|
||||
```
|
||||
freezelib/
|
||||
├── freeze.go # 主要 API 接口
|
||||
├── config.go # 配置结构体
|
||||
├── generator.go # 核心生成逻辑
|
||||
├── quickfreeze.go # 简化 API
|
||||
├── presets.go # 预设配置
|
||||
├── ansi.go # ANSI 处理
|
||||
├── svg/ # SVG 处理
|
||||
├── font/ # 字体处理
|
||||
├── example/ # 使用示例
|
||||
└── README.md # 详细文档
|
||||
```
|
||||
- `github` - GitHub 浅色主题
|
||||
- `github-dark` - GitHub 深色主题
|
||||
- `dracula` - Dracula 主题
|
||||
- `monokai` - Monokai 主题
|
||||
- `nord` - Nord 主题
|
||||
|
||||
## 🤝 与原版 freeze 的区别
|
||||
## 常用语言
|
||||
|
||||
| 特性 | 原版 freeze | FreezeLib |
|
||||
|------|-------------|-----------|
|
||||
| 使用方式 | CLI 工具 | Go 库 |
|
||||
| 集成方式 | 命令行调用 | 直接导入 |
|
||||
| 配置方式 | 命令行参数/配置文件 | Go 结构体 |
|
||||
| 扩展性 | 有限 | 高度可扩展 |
|
||||
| 性能 | 进程启动开销 | 内存中处理 |
|
||||
|
||||
## 📝 示例代码
|
||||
|
||||
查看 `examples` 目录中的完整示例：
|
||||
|
||||
这将生成多个示例 SVG 文件，展示库的各种功能。
|
||||
- `go` - Go 语言
|
||||
- `python` - Python
|
||||
- `javascript` - JavaScript
|
||||
- `typescript` - TypeScript
|
||||
- `java` - Java
|
||||
- `rust` - Rust
|
||||
- `c` - C 语言
|
||||
- `cpp` - C++
|
||||
- `html` - HTML
|
||||
- `css` - CSS
|
||||
- `json` - JSON
|
||||
- `yaml` - YAML
|
||||
- `markdown` - Markdown
|
||||
- `bash` - Shell 脚本
|
||||
|
||||
Reference in New Issue
Block a user