/README.md

<!-- WEHUB_ZH_README -->
> [!NOTE]
> 本文档由 WeHub 基于上游 README 翻译整理，属于社区翻译，非官方中文文档。  
> [English](./README.en.md) · [原始项目](https://github.com/charmbracelet/freeze) · [上游 README](https://github.com/charmbracelet/freeze/blob/HEAD/README.md)  
> 原作者、版权与许可证归属以原始项目及本仓库 LICENSE 文件为准。

# Freeze

<p>
  <a href="https://stuff.charm.sh/freeze/freeze-4k.png"><img src="https://github.com/charmbracelet/freeze/assets/25087/de76b799-fa67-4b5b-8da2-d990ca5b4e06" width="500" /></a><br>
  <a href="https://github.com/charmbracelet/freeze/releases"><img src="https://img.shields.io/github/release/charmbracelet/freeze.svg" alt="Latest Release"></a>
  <a href="https://github.com/charmbracelet/freeze/actions"><img src="https://github.com/charmbracelet/freeze/workflows/build/badge.svg" alt="Build Status"></a>
</p>

生成代码和终端输出的图片。

<p align="left">
  <a><img width="600" src="https://vhs.charm.sh/vhs-1C6z5SUKlTdqdj4KL1ADlH.gif" alt="Freeze code screenshot"></a>
</p>

## 示例

Freeze 可以同样生成代码和终端输出的 PNG、SVG 和 WebP 图片。

### 生成代码图片

```sh
freeze artichoke.hs -o artichoke.png
```

<p align="center">
  <a href="https://github.com/charmbracelet/freeze/assets/42545625/f15efdda-8e9b-4cb1-9e87-3d32b692eb7c">
    <img alt="output of freeze command, Haskell code block" src="./test/golden/svg/shadow.svg" width="800" />
  </a>
</p>

### 生成终端输出图片

你可以使用 `freeze` 配合 `--execute` 标志捕获终端命令的 ANSI 输出。

```bash
freeze --execute "eza -lah"
```

<p align="center">
  <a href="https://github.com/charmbracelet/freeze/assets/42545625/aa5447ed-999a-4809-909d-67093d758f5a">
    <img alt="output of freeze command, ANSI" src="./test/golden/svg/eza.svg" width="800" />
  </a>
</p>

Freeze 还[高度可定制](#customization)，并提供[交互式 TUI](#interactive-mode)。

## 安装

```sh
# macOS or Linux
brew install charmbracelet/tap/freeze

# Arch Linux (btw)
yay -S freeze

# Nix
nix-env -iA nixpkgs.charm-freeze
```

或者，直接下载：

- [软件包][releases] 提供 Debian 和 RPM 格式
- [二进制文件][releases] 适用于 Linux、macOS 和 Windows

或者，使用 `go` 安装：

```sh
go install github.com/charmbracelet/freeze@latest
```

[releases]: https://github.com/charmbracelet/freeze/releases

## 定制

### 交互模式

Freeze 提供完整的交互模式，便于轻松定制。

```bash
freeze --interactive
```

<img alt="freeze interactive mode" src="https://vhs.charm.sh/vhs-1AGhIlc2Mtn9Ltc8vPtaAP.gif" width="400" />

设置会写入 `$XDG_CONFIG/freeze/user.json`，可通过 `freeze --config user` 访问。

### 标志

可使用 `--flags` 或[配置文件](#configuration)自定义截图。

> [!NOTE]
> 可使用 `freeze --help` 查看所有 freeze 定制选项。

- [`-b`](#background)、[`--background`](#background)：应用背景填充。
- [`-c`](#configuration)、[`--config`](#configuration)：基础配置文件或模板。
- [`-l`](#language)、[`--language`](#language)：应用于代码的语言
- [`-m`](#margin)、[`--margin`](#margin)：为窗口应用外边距。
- [`-o`](#output)、[`--output`](#output)：.svg、.png、.jpg 的输出位置。
- [`-p`](#padding)、[`--padding`](#padding)：为代码应用内边距。
- [`-r`](#border-radius)、[`--border.radius`](#border-radius)：窗口圆角半径。
- [`-t`](#theme)、[`--theme`](#theme)：用于语法高亮的主题。
- [`-w`](#window)、[`--window`](#window)：显示窗口控件。
- [`-H`](#height)、[`--height`](#height)：终端窗口高度。
- [`--border.width`](#border-width)：边框宽度。
- [`--border.color`](#border-width)：边框颜色。
- [`--shadow.blur`](#shadow)：阴影高斯模糊。
- [`--shadow.x`](#shadow)：阴影 x 轴偏移量。
- [`--shadow.y`](#shadow)：阴影 y 轴偏移量。
- [`--font.family`](#font)：代码所用字体族。
- [`--font.ligatures`](#font)：在字体中使用连字（ligatures）。
- [`--font.size`](#font)：代码所用字号。
- [`--font.file`](#font)：所用字体文件路径（嵌入 SVG）。
- [`--line-height`](#font)：相对于字号的行高。
- [`--show-line-numbers`](#line-numbers)：显示行号。
- [`--lines`](#line-numbers)：要捕获的行（起始,结束）。

### 语言

在可能的情况下，`freeze` 会根据文件名或分析文件内容自动检测语言。使用 `--language` 标志可覆盖此推断。

```bash
cat artichoke.hs | freeze --language haskell
```

<br />

<a href="https://github.com/charmbracelet/freeze/assets/42545625/d746f028-3d51-4bfd-ba81-94bbc47b3587">
  <img alt="output of freeze command, Haskell code block" src="./test/golden/svg/haskell.svg" width="600" />
</a>

### 主题

更改颜色主题。

```bash
freeze artichoke.hs --theme dracula
```

<br />

<a href="https://github.com/charmbracelet/freeze/assets/42545625/c693dc80-89b8-43c6-a34e-2d49a332d0c7">
  <img alt="output of freeze command, Haskell code block with dracula theme" src="./test/golden/svg/dracula.svg" width="600" />
</a>

### 输出

更改输出文件位置，默认为 `out.svg`；若通过管道传输则默认为 stdout。该值支持 `.svg`、`.png`、`.webp`。

```bash
freeze main.go --output out.svg
freeze main.go --output out.png
freeze main.go --output out.webp

# or all of the above
freeze main.go --output out.{svg,png,webp}
```

### 字体

指定输出图片的字体族、字号和行高。默认为 `JetBrains Mono`、`14`(px)、`1.2`(em)。

```bash
freeze artichoke.hs \
  --font.family "SF Mono" \
  --font.size 16 \
  --line-height 1.4
```

也可使用 `--font.file` 标志嵌入字体文件（TTF、WOFF 或 WOFF2 格式）。

若要在字体中使用连字，可应用 `--font.ligatures` 标志。

### 行号

使用 `--show-line-numbers` 标志在终端窗口中显示行号。

```bash
freeze artichoke.hs --show-line-numbers
```

若只捕获特定范围的行号，可使用 `--lines` 标志。

```bash
freeze artichoke.hs --show-line-numbers --lines 2,3
```

### 圆角半径

为终端添加圆角。

```bash
freeze artichoke.hs --border.radius 8
```

<br />

<a href="https://github.com/charmbracelet/freeze/assets/42545625/50932b10-56fd-4312-adbd-f64b36a15441">
  <img alt="code screenshot with corner radius of 8px" src="./test/golden/svg/border-radius.svg" width="600" />
</a>

### 窗口

为终端添加 macOS 风格的窗口控件。

```bash
freeze artichoke.hs --window
```

<a href="https://github.com/charmbracelet/freeze/assets/42545625/ba46bc4a-fb36-4718-88d4-f63b93343615">
  <img alt="output of freeze command, Haskell code block with window controls applied" src="./test/golden/svg/window.svg" width="600" />
</a>

### 背景

设置终端窗口的背景颜色。

```bash
freeze artichoke.hs --background "#08163f"
```

### 高度

设置终端窗口的高度。

```bash
freeze artichoke.hs --height 400
```

### 边框宽度

为终端窗口添加边框轮廓。

```bash
freeze artichoke.hs --border.width 1 --border.color "#515151" --border.radius 8
```

<br />

<a href="https://github.com/charmbracelet/freeze/assets/42545625/b9207976-50fe-479b-974b-e1bf2ad1684c">
  <img alt="output of freeze command, Haskell code block with border applied" src="./test/golden/svg/border-width.svg" width="600" />
</a>

### 内边距

为终端窗口添加内边距。可提供 1、2 或 4 个值。

```bash
freeze main.go --padding 20          # all sides
freeze main.go --padding 20,40       # vertical, horizontal
freeze main.go --padding 20,60,20,40 # top, right, bottom, left
```

<br />

<a href="https://github.com/charmbracelet/freeze/assets/42545625/41da80bb-a6d8-402b-9f14-c73050720c0f">
  <img alt="output of freeze command, Haskell code block with padding applied" src="./test/golden/svg/padding.svg" width="600" />
</a>

### 外边距

为终端窗口添加外边距。可提供 1、2 或 4 个值。

```bash
freeze main.go --margin 20          # all sides
freeze main.go --margin 20,40       # vertical, horizontal
freeze main.go --margin 20,60,20,40 # top, right, bottom, left
```

<br />

<a href="https://github.com/charmbracelet/freeze/assets/42545625/eca78a8e-2dbc-4cfa-81da-6c2194925238">
  <img alt="freeze 命令的输出，已应用边距的 Haskell 代码块" src="./test/golden/svg/margin.svg" width="720" />
</a>

### Shadow

在终端窗口下方添加阴影。

```bash
freeze artichoke.hs --shadow.blur 20 --shadow.x 0 --shadow.y 10
```

<br />

<a href="https://github.com/charmbracelet/freeze/assets/42545625/b9a8cc17-5ec6-4004-941b-5ae1b65d2b18">
  <img alt="freeze 命令的输出，带阴影的 Haskell 代码块" src="./test/golden/svg/shadow.svg" width="720" />
</a>

## Screenshot TUIs

使用 `tmux capture-pane` 为 TUI（Terminal User Interface，终端用户界面）生成截图。

在 `tmux` 中运行你的 TUI，并将其调整到你想捕获的状态。
接下来，使用 `capture-pane` 捕获该窗格，并将其管道输出到 freeze。

```bash
hx # in a separate pane
tmux capture-pane -pet 1 | freeze -c full
```

<img width="650px" src="./test/golden/svg/helix.svg" alt="使用 freeze 捕获的 helix">

## Configuration

Freeze 还支持通过 JSON 文件进行配置，可使用
`--config` / `-c` 标志传入。一般而言，所有 `--flag` 选项都会直接映射到配置文件中的键和值。

`freeze` 中还内置了一些默认配置，可按名称传入。

- `base`：简单的代码截图。
- `full`：类似 macOS 的截图。
- `user`：使用 `~/.config/freeze/user.json`。

如果你使用 `--interactive` 模式，系统会在
`~/.config/freeze/user.json` 为你创建一份配置文件。这将是你的截图默认使用的配置文件。

```bash
freeze -c base main.go
freeze -c full main.go
freeze -c user main.go # alias for ~/.config/freeze/user.json
freeze -c ./custom.json main.go
```

下面是一个配置示例：

```json
{
  "window": false,
  "border": {
    "radius": 0,
    "width": 0,
    "color": "#515151"
  },
  "shadow": false,
  "padding": [20, 40, 20, 20],
  "margin": "0",
  "font": {
    "family": "JetBrains Mono",
    "size": 14
  },
  "line_height": 1.2
}
```

## Contributing

请参阅 [contributing][contribute]。

[contribute]: https://github.com/charmbracelet/freeze/contribute

## Feedback

我们非常乐意听取你对本项目的想法。欢迎随时给我们留言！

- [Twitter](https://twitter.com/charmcli)
- [The Fediverse](https://mastodon.social/@charmcli)
- [Discord](https://charm.sh/chat)

## License

[MIT](https://github.com/charmbracelet/freeze/raw/main/LICENSE)

---

Part of [Charm](https://charm.sh).

<a href="https://charm.sh/">
  <img
    alt="The Charm logo"
    width="400"
    src="https://stuff.charm.sh/charm-badge.jpg"
  />
</a>

Charm热爱开源 • Charm loves open source