---
url: 'https://bot.mcjpg.dev/guide/image-rendering.md'
description: UniBot 图片渲染指南：开启 image 模式后，指令输出渲染为精美图片卡片；了解渲染引擎、模板与资源三类扩展的组合与自定义方法。
---
# 图片渲染

在 `Config.toml` 中将 `[image] mode` 设为 `true` 后，机器人的指令输出将以 **图片** 形式发送，列表、运势、状态等指令会渲染成精美的图片卡片。

## 渲染体系

图片渲染能力由 **渲染引擎、模板、资源** 三类扩展协作提供，均以**扩展**形式从**扩展市场**分发，可按需安装、自由组合替换：

::: table title="渲染体系组成" copy="all"
| 组成 | 扩展类型 | 作用 |
|------|---------|------|
| **渲染引擎** | `renderer` 扩展 | 把页面渲染为图片，决定渲染的实现方式（如 Html2Pic） |
| **模板** | `template` 扩展 | 决定图片的版式与风格，一套模板即一种图片风格，可随时切换 |
| **资源** | `resources` 扩展 | 提供图片、字体等静态素材，随模板一并生效 |
:::

官方在扩展市场提供了开箱即用的组合：

::: table title="官方渲染相关扩展" copy="all"
| 扩展 | 类型 | 特点 |
|------|------|------|
| `Html2Pic` | 渲染引擎 | ==轻量、占用小、渲染速度快== |
| `Playwright` | 渲染引擎 | 基于浏览器渲染，==质量好==，但==速度较慢、占用较大== |
| `Default` | 模板 & 资源 | 默认指令的图片模板与资源包 |
:::

渲染引擎按需选择：追求速度与低占用选 `Html2Pic`，追求渲染质量选 `Playwright`。引擎切换需==重启==机器人；不同引擎可搭配同一套模板与资源。

## 启用图片模式

::: steps

1. **安装渲染相关扩展**

   在 WebUI 扩展市场中安装渲染引擎（`Html2Pic` 或 `Playwright`，按需选择）与 `Default`（默认模板 & 资源）。开启图片模式时若缺失，WebUI 也会弹窗引导自动下载。

2. **启用并选择渲染配置**

   在 `Config.toml` 的 `[image]` 节设置 `mode = true`，并指定要使用的渲染引擎与模板：

   ```toml
   [image]
   mode = true
   renderer = "html2pic" # 渲染引擎：html2pic 或 playwright（对应已安装的渲染引擎扩展）
   template = "Default"  # 模板包（对应已安装的模板扩展）
   # font = ""           # 可选：自定义字体路径，留空自动从资源扩展查找 Font.ttf
   ```

3. **重启机器人**

   `mode` 与 `renderer` 修改后需==**重启**==生效；`template` 切换==**即时生效**==，无需重启。

:::

渲染引擎与模板也可在 **WebUI → 扩展管理** 中直接切换。

* \==模板自动回退==：当前模板包缺失或不可用时，自动回退到默认模板（`Default` 或首个可用模板）。
* \==渲染引擎需显式选择==：图片模式必须安装并选择一个可用的渲染引擎扩展；引擎未选择或不可用时，渲染会报错提示。

## 调整图片外观

图片的背景、配色、字体等外观由**模板扩展**提供，不在核心 `Config.toml` 中配置：

* 模板扩展可在其清单中声明外观配置项（如主色、字体、布局等）。
* 在 **WebUI → 扩展管理** 中选中对应模板扩展，通过表单修改并保存后**立即生效**；也可直接编辑 `Config/Extensions/<模板ID>.toml`。
* 更换模板包即可整体切换图片风格。

*注意：图片模式会略微增加指令响应时间。*

## 支持图片渲染的指令

::: table title="支持图片渲染的指令" copy="all"
| 指令 | 渲染内容 |
|------|----------|
| `/list` | 在线玩家列表（含玩家头像） |
| `/server` | 服务器连接状态 |
| `/luck` / `/luck rank` | 每日运势卡片 / 运势排行 |
| `/bound` | 白名单绑定信息 |
| `/help` | 帮助信息 |
| `/bot about` | 关于页面 |
| `/bot check` | 版本检查结果 |
:::