变量让 imgrender 模板从「固定内容」变成「可复用模板」。你可以在 HTML 或 CSS 中插入变量占位符，渲染时再替换为指定内容。

<div style="background-color: {$ theme_color $}">
  <h1>{$ title $}</h1>
  <p>{$ description | default("暂无描述") $}</p>
</div>

这段模板用三个变量把颜色和文案参数化，渲染时替换为实际值即可生成不同图片：

{$ theme_color $} 写在 HTML 的 style 属性中，替换后成为背景色（例如 #1677FF）
{$ title $} 作为子节点直接输出标题文本
{$ description | default("暂无描述") $} 在变量后用 | 接过滤器：未传入或为空时输出「暂无描述」

变量占位符使用 {$ 变量名 $}，可以直接写在 HTML 文本或属性值中。

变量语法

imgrender 使用 { 和 $ 包裹的占位符标记变量，格式为：

{$ 变量名 $}

在 HTML 和 CSS 中都可以使用：

<div style="color: {$ brand_color $}; font-size: 32px">{$ title $}</div>

.banner {
  background-image: url({$ cover_url $});
  color: {$ brand_color $};
}

变量名规则

变量名必须是合法标识符：

以字母或下划线开头
只能包含字母、数字和下划线
不支持中文、连字符、空格或以数字开头

✅ title      _id       brand_color2
❌ 标题       pod-title  2title      pod title

需要访问对象字段时，使用点号路径：

{$ user.name $}
{$ product.price $}

数据类型

每个变量都有明确的数据类型，模板编辑器会根据类型渲染对应的输入控件，API 也会按类型做基础校验。

类型	说明	示例值
`string`	文本	`重磅发布`
`number`	数字	`42`
`boolean`	布尔	`true` / `false`
`color`	颜色，建议 hex 格式	`#1677FF`
`image_url`	图片 URL	`https://example.com/cover.jpg`
`date`	日期字符串	`2026-08-23`
`array`	数组	`["a", "b", "c"]`
`object`	对象	`{ "name": "imgrender" }`

类型对应的使用场景

string / number：文字内容、价格、数量等
boolean：配合 {% if %} 控制元素是否显示
color：背景色、文字色、边框色等 CSS 值
image_url：<img> 的 src 或 CSS background-image
date：需要格式化后展示的日期
array / object：配合 {% for %} 循环或对象属性访问

默认值与必填

每个变量可以配置：

必填：开启后，API 调用时该变量必须提供有效值，否则接口校验失败
默认值：变量未传入或为空时的回退值
示例值：模板编辑器中用于实时预览的值

<h1>{$ title $}</h1>
<p>{$ description | default("暂无描述") $}</p>

如果 description 为空字符串或不存在，过滤器 default 会输出「暂无描述」。

示例值 vs 默认值

示例值仅影响模板编辑器预览和生成的 API 示例请求
默认值在服务端渲染时生效，当请求未传该变量或变量为空时使用

文本过滤器

变量后可以通过 | 连接过滤器，对输出进行简单处理。支持以下过滤器：

upper — 转为大写
- {$ title | upper $} → HELLO
lower — 转为小写
- {$ title | lower $} → hello
capitalize — 首字母大写
- {$ title | capitalize $} → Hello
trim — 去除首尾空白
- {$ title | trim $} → hello
truncate(n) — 截断为 n 个字符
- {$ title | truncate(5) $} → hello…
replace(a, b) — 替换文本
- {$ title | replace("o", "a") $} → hella
default(v) — 为空时返回默认值
- {$ title | default("未命名") $} → 未命名

过滤器可以链式使用：

<p>{$ title | trim | upper | truncate(10) $}</p>

条件渲染

使用 {% if %} 控制一段内容是否输出：

{% if show_badge %}
  <span style="background: red; color: white">NEW</span>
{% endif %}

也支持 {% else %} 和 {% elif %}：

{% if is_vip %}
  <span>VIP 会员</span>
{% elif is_paid %}
  <span>付费会员</span>
{% else %}
  <span>免费用户</span>
{% endif %}

条件表达式支持 not 前缀：

{% if not hide_footer %}
  <footer>{$ footer_text $}</footer>
{% endif %}

条件判断规则

imgrender 的条件判断采用「真值」语义：空字符串、0、false、null、undefined 都会被当作假值。布尔变量、非空字符串、非零数字都会被当作真值。

循环渲染

数组变量可以配合 {% for %} 循环输出：

<ul>
  {% for tag in tags %}
    <li>{$ tag $}</li>
  {% endfor %}
</ul>

传入变量值：

{
  "tags": ["React", "Vue", "Svelte"]
}

会渲染为：

<ul>
  <li>React</li>
  <li>Vue</li>
  <li>Svelte</li>
</ul>

循环内的临时变量名需要是合法标识符，数组变量本身也支持对象数组和点号访问：

{% for member in team %}
  <div>{$ member.name $} - {$ member.role $}</div>
{% endfor %}

在模板编辑器中管理变量

模板编辑器的「变量」面板会自动从 HTML/CSS 中提取变量名。

你可以：

点击变量卡片展开，修改类型、默认值、示例值和描述
设置变量是否为必填
从代码中删除变量引用后，该变量会显示为「未使用」，可选择保留配置或移除

自动提取

变量名由编辑器从 { $ ... $ } 和 {% %} 代码中自动提取，因此你不需要手动创建变量，只需在模板中书写占位符即可。

通过 API 传入变量

保存为模板后，调用基于模板生成图片 API 时，在请求体的 variables 字段中传入变量值：

curl -X POST https://api.imgrender.net/open/v1/images/templates/:template_id/render \
  -H "Content-Type: application/json" \
  -H "X-API-Key: YOUR_API_KEY" \
  -d '{
    "variables": {
      "title": "周末抽奖活动",
      "theme_color": "#FF6B35",
      "show_badge": true,
      "tags": ["福利", "限时"]
    }
  }'

API 会按模板中定义的变量类型校验请求，校验失败会返回 400 和具体错误信息。

完整示例

<div
  style="width: 100%; height: 100%; display: flex; flex-direction: column; justify-content: center; padding: 48px; background-color: {$ background_color $}"
>
  <h1 style="font-size: 48px; color: #1a1a1a; margin: 0">
    {$ title $}
  </h1>
  <p style="font-size: 22px; color: #555555; margin-top: 16px">
    {$ description | default("暂无描述") $}
  </p>

  {% if show_tags %}
    <div style="display: flex; gap: 8px; margin-top: 24px">
      {% for tag in tags %}
        <span
          style="padding: 6px 12px; border-radius: 999px; background-color: #ffffff; color: {$ background_color $}"
        >
          {$ tag $}
        </span>
      {% endfor %}
    </div>
  {% endif %}
</div>

对应变量配置示例：

[
  {
    "name": "title",
    "type": "string",
    "required": true,
    "sampleValue": "重磅发布"
  },
  {
    "name": "description",
    "type": "string",
    "required": false,
    "defaultValue": ""
  },
  {
    "name": "background_color",
    "type": "color",
    "required": false,
    "defaultValue": "#1677FF"
  },
  {
    "name": "show_tags",
    "type": "boolean",
    "required": false,
    "defaultValue": true
  },
  {
    "name": "tags",
    "type": "array",
    "required": false,
    "defaultValue": []
  }
]

下一步

在模板编辑器中打开默认模板，修改变量值观察实时效果
查看基于模板生成图片 API 将模板接入业务系统
了解布局和样式进一步控制模板外观

变量

On this page