ErisPulse-Takumi

ErisPulse-Takumi 是由 ccd2s 維護的 第三方圖片渲染模塊，基於 takumi-py，讓 Bot 能夠將 HTML、節點樹、Jinja 模板、SVG、動畫渲染為圖片。模塊 內置中英文字體（Noto Sans SC / Roboto / Source Code Pro），無需額外配置。

epsdk install Takumi

適用場景：

• 將數據/統計渲染為卡片圖片
• 將 Markdown / 長文本渲染為排版穩定的圖片，避免平台樣式差異
• 生成 SVG / 動畫，實現動態視覺效果
• 中英混排圖文（內置字體開箱即用）

安裝與啟用

epsdk install Takumi

安裝後模組會自動載入，在設定檔中確認已啟用：

[Takumi]
enabled = true

快速上手

模組自動載入後，可透過模組管理器取得，或使用 sdk 快捷方式：

from ErisPulse import sdk

takumi = sdk.module.get("Takumi")
# 等價寫法：takumi = sdk.Takumi

渲染 HTML

png = takumi.render_html(
    """
    <div class="card">
      <h1>你好，ErisPulse</h1>
      <p>由 Takumi 渲染</p>
    </div>
    """,
    stylesheets=["""
    .card {
      width: 800px;
      padding: 48px;
      color: white;
      background: #111827;
      font-family: "Noto Sans SC";
    }
    """],
    width=800,
    height=None,   # 按內容自動撐高
    lang="zh-CN",
)

渲染節點樹

png = takumi.render_node(
    {
        "type": "text",
        "text": "中文和 English 都可直接渲染",
        "style": {"fontSize": 48, "color": "#111827"},
    },
    width=800,
    height=None,
    lang="zh-CN",
)

png 是 bytes，可透過 event.reply(png, method="Image") 發送（詳見 發送渲染結果）。

渲染 API

sdk.Takumi 代理了底層 takumi_py.Renderer 的全部能力：所有渲染、測量、SVG、動畫、模板方法都可直接在 sdk.Takumi 上調用。對這些方法，模組會在調用時自動注入內置字體回退棧（takumi.families），無需手動傳 font_families；若顯式傳入則尊重調用方設定。

方法總覽

CompiledNode 暴露 resource_urls() 方法，可預先發現待加載的 HTTP(S) 圖片引用，便於提前準備資源。

通用參數

以下參數適用於靜態渲染與 SVG 方法（動畫方法另有 fps 等，見對應示例）：

完整字段定義見 takumi_py.RenderOptions。

節點樹示例

png = takumi.render_node(
    {
        "type": "container",
        "style": {"padding": "32px", "backgroundColor": "#111827"},
        "children": [
            {"type": "text", "text": "標題", "style": {"fontSize": 32, "color": "white"}},
            {"type": "text", "text": "正文", "style": {"fontSize": 18, "color": "#9ca3af"}},
        ],
    },
    width=800,
    height=None,
    lang="zh-CN",
)

Jinja 模板示例

png = takumi.render_template(
    "card.html.jinja",
    {"title": "Takumi", "subtitle": "Jinja to image"},
    stylesheets=["""
    .card {
      width: 800px;
      padding: 48px;
      color: white;
      background: #111827;
    }
    """],
    width=800,
    height=None,
    lang="zh-CN",
)

可通過 filters={...} 注入自定義 Jinja 過濾器，或 environment=... 傳入完整 jinja2.Environment。模板目錄與環境配置詳見 takumi-py 模板文件。

SVG 輸出示例

svg = takumi.render_svg_html(
    '<div class="card">Hello</div>',
    stylesheets=[".card { width: 800px; color: black; }"],
    width=800,
    height=None,
)

動畫示例

from takumi_py import AnimationScene

webp = takumi.render_animation(
    [
        AnimationScene(
            {"type": "container", "style": {"width": "100%", "height": "100%", "backgroundColor": "black"}},
            duration_ms=100,
        ),
        AnimationScene(
            {"type": "container", "style": {"width": "100%", "height": "100%", "backgroundColor": "white"}},
            duration_ms=100,
        ),
    ],
    width=64,
    height=64,
    fps=20,
    format="webp",
)

每幀由 AnimationScene(node, duration_ms=...) 构成，duration_ms 必須為正數。

視口與輸出格式

輸出格式

format="raw" 返回行主序 RGBA 位元組流，用於自訂像素級處理。

關於 width 與 height

width 與 height 的角色不對稱：

• width 是視口寬度，文字與佈局會根據它換行、重新佈局。應固定為具體數值（如 800），否則畫布會根據內容自然寬度拉伸、文字不換行，尺寸不可控。
• height 是畫布高度，會隨著內容增長。height 的預設值為 630；傳入 height=None 時，Takumi 會根據內容自動撐高畫布（auto viewport）。

字體

內置字體

模組屬性：

自動注入

sdk.Takumi 上的全部渲染、測量、SVG、動畫、模板方法會自動注入 takumi.families 作為字體回退堆疊。若直接調用 takumi.renderer（原生實例）或透過 create_renderer() 創建的獨立實例，則需手動傳 font_families=takumi.families。

自定義字體

from takumi_py import FontResource

families = takumi.renderer.register_font(
    FontResource(
        font_bytes,
        name="MyFont",
        weight=400,
        style="normal",
        generic_family="sans-serif",
    )
)

register_font 返回註冊的 family 名稱列表，可在後續渲染時作為 font_families 傳入。

渲染器實例

原生 Renderer

takumi.renderer 是原始的 takumi_py.Renderer 實例。直接調用時需手動傳遞 font_families：

png = takumi.renderer.render_html(
    "<div>你好</div>",
    font_families=takumi.families,
    lang="zh-CN",
)

獨立 Renderer

需要隔離字體 / 圖片 / 資源緩存時（長生命週期進程、多租戶場景），可創建獨立的 Renderer，內建字體會自動註冊：

renderer = takumi.create_renderer(cache_max_bytes=64 * 1024 * 1024)

png = renderer.render_html(
    "<div>獨立 Renderer</div>",
    font_families=takumi.families,
    width=800,
    height=None,
    lang="zh-CN",
)

create_renderer() 接受 takumi_py.Renderer 的構造參數：

獨立實例不經過模組代理，因此若要保留統一的內建字體回退堆疊，需顯式傳入 font_families=takumi.families。若顯式傳入 font_families，模組會尊重呼叫方設定，不再注入預設回退堆疊；RenderOptions(font_families=...) 同樣有效。

發送渲染結果

渲染得到的圖片為 bytes，可透過事件回覆直接發送：

from ErisPulse import sdk

takumi = sdk.Takumi
png = takumi.render_html("<div>hello</div>", lang="zh-CN")

# 方式一：以 Image 方法回覆
await event.reply(png, method="Image")

# 方式二：透過 OneBot12 消息段回覆
from ErisPulse.Core.Event import MessageBuilder
await event.reply_ob12(
    MessageBuilder().image(png).build()
)

不同平台對圖片的封裝由適配器統一處理。詳見 MessageBuilder 詳解 與 發送方法規範。

配置

[Takumi]
啟用 = true

相關連結

• PyPI：https://pypi.org/project/ErisPulse-Takumi/
• 倉儲：https://github.com/ccd2s/ErisPulse-Takumi（作者 @ccd2s）
• 底層引擎：https://github.com/BalconyJH/takumi-py
• takumi-py 文件：https://github.com/BalconyJH/takumi-py/blob/main/docs/index.md