工作原理

imgrender 采用 声明式图片生成 的方式：你使用熟悉的 HTML 和 CSS 描述模板内容，发布后通过 API 传入变量，imgrender 负责将其渲染为高质量的图片。

<div
  style="
    width: 400px;
    height: 200px;
    background: linear-gradient(135deg, #667eea 0%, #764ba2 100%);
    display: flex;
    align-items: center;
    justify-content: center;
  "
>
  <h1 style="color: white; font-size: 32px">Hello imgrender</h1>
</div>

上述代码将生成一张 400×200 像素的渐变背景图片，居中显示白色文字。

模板编辑器

模板编辑器是 imgrender 提供的在线编辑环境，适合在编写文档或调用 API 之前快速验证模板效果。

你可以在模板编辑器中：

编辑 HTML，实时预览渲染结果
配置图片尺寸、格式等输出参数
管理并预览所用字体
从内置模板起步，快速改造成自己的样式
使用变量将模板内容参数化，同一模板生成不同图片
一键打开 API 调试面板，基于当前已保存模板生成可调用的渲染请求
通过 URL 分享当前编辑状态，方便协作与复现

推荐用法

开发模板时，建议先在模板编辑器中完成布局与样式调试，确认效果后再接入基于模板生成图片 API。

核心概念

imgrender 的图片生成过程可以理解为：

结构描述 - 使用 HTML 定义元素的层级结构
样式控制 - 通过 CSS 属性或 Tailwind CSS 控制外观
变量替换 - 使用 {$ name $} 占位符将内容参数化，渲染时替换为实际值
渲染输出 - imgrender 渲染并导出为指定格式的图片

与传统图片生成的对比

方式	优点	缺点
imgrender	代码即图片，易于维护、调用简单、版本控制、动态生成	需要学习成本
设计工具导出	所见即所得，无需编码	难以批量生成，不易修改
Canvas API	灵活度高	代码复杂，维护成本高，依赖 JS 运行环境

HTML 与 CSS 支持度

imgrender 的渲染引擎，并非完全遵循浏览器标准，只支持 HTML 和 CSS 的一个子集。

渲染差异

imgrender 不保证渲染结果与浏览器 100% 一致，建议在模板编辑器中进行测试验证。

HTML 元素限制

imgrender 仅接受静态 HTML 片段，不执行 JavaScript。动态内容请使用模板变量、条件与循环语法。

仅支持有限的静态、可见元素：

✅ 支持：div、span、p、img 等基础元素
❌ 不支持：<input>、<style>、<link>、<script> 等。也不要传入完整的 HTML 文档，只能传核心的片段。

CSS 属性限制

imgrender 支持的 CSS 属性，请参考支持的样式

下一步

根据你的需求，查阅以下文档了解更多细节：

模板编辑器 - 在线编辑模板并实时预览渲染效果
变量 - 学习如何使用模板变量、过滤器、条件与循环，让模板可复用
样式 - 学习如何使用内联样式和 Tailwind CSS 控制元素外观
布局 - 掌握 Flexbox、Grid 布局和 Box Model
文字排版与字体 - 了解字体使用、空白控制、换行等文本处理
加载图片 - 学习如何在图片中嵌入外部图片资源

准备好了吗？

如果你已经了解基础知识，可以先在模板编辑器中动手试一试，或直接查看基于模板生成图片 API 开始使用。

概览