跳转到主要内容
Liquid 是 OneSignal 支持的模板语言，用于跨渠道个性化消息，包括邮件、推送、短信、应用内和 Live Activities。它使用标签、过滤器和条件语句来动态自定义消息内容。 要了解更多 Liquid 语法信息，请参阅官方 Liquid 文档。

​
Liquid 语法支持的字段

  • 邮件
  • 推送
  • 短信
  • 应用内消息
  • 实时活动
  • 主题、回复和预览文本
  • 消息正文
  • HTML 块中的图片替换。示例：<img src="{{image_url}}"/>
  • 按钮块操作，如 URL、邮件发送和其他字段。

​
基本语法

Liquid 使用两种主要的语法结构：
  1. 输出标签：{{ ... }} - 显示变量或对象中的数据。
  2. 逻辑标签：{% ... %} - 执行条件语句或循环。

​
数据源

来源示例设置方式
标签{{ first_name }}OneSignal SDK 或 API（tags）
属性{{ subscription.email }}系统管理（email、external_id、language）
自定义数据{{ message.custom_data.key }}在创建消息的 API 调用中传递
有关数据源的更多信息，请参见消息个性化。

​
条件语句

​
运算符

  • ==, !=, >, <, >=, <=
  • and, or
  • contains (string or array)
运算从右到左执行。不支持括号。
liquid
{% if true or false and false %}
  这是真的。
{% endif %}

​
if、elsif、else

liquid
{%- assign userLang = subscription.language -%}
{% if userLang == "es" -%}
Hola {{ first_name }}!
{%- elsif userLang == "fr" -%}
Bonjour {{ first_name }}!
{%- else -%}
Hello {{ first_name }}!
{%- endif %}

​
unless

liquid
{% unless level == "1" %}
  恭喜你通过了第一关！
{% endunless %}

​
过滤器

使用 {{ variable | filter }} 应用过滤器来调整数据显示方式。

​
default

如果属性为空或不存在，则分配默认值。
liquid
Hello {{ first_name | default: "there" }}.

​
date

date 过滤器将时间戳转换为另一种日期格式。此语法的格式与 strftime 相同。输入使用与 Ruby 的 Time.parse 相同的格式。 使用标签将日期设置为以秒为单位的 unix 时间戳。这允许同时使用 liquid 语法个性化和时间运算符进行细分。例如，标签可能是：bill_due : 1687968776
liquid
{{ bill_due | date: "%a, %b %d, %y" }}
{{ "now" | date: "%Y-%m-%d %H:%M" }}
Result
Wed, Jun 28, 23
liquid
{{ bill_due | date: "%Y" }}
Result
2023
如果字符串包含格式良好的日期，日期格式化可以处理字符串。
liquid
{{ "March 14, 2016" | date: "%b %d, %y" }}
Result
Mar 14, 16
要获取当前时间，请将特殊单词 now（或 today）与日期过滤器一起传递。
liquid
此消息发送于 {{ "now" | date: "%Y-%m-%d %H:%M" }}。
Result
此消息发送于 2022-11-02 14:39。
当前时间将根据消息发送给接收者的时间在消息中呈现。如果您正在测试消息， 您将看到当前时间为测试消息发送的时间。

​
capitalize

此过滤器将字符串的第一个字符大写，并将其余字符转换为小写。
liquid
{{ "my GREAT title" | capitalize }}
Result
My great title

​
round

此过滤器将数字四舍五入到最接近的整数，或者如果传递了一个数字作为参数，则四舍五入到指定的小数位数。
liquid
{{ 1.2 | round }}
  {{ 2.7 | round }}
{{ 183.357 | round: 2 }}
Result
1
3
183.36

​
pluralize

此过滤器根据给定的数字返回字符串的单数或复数形式。数字必须是整数，可以作为字符串提供。必须同时提供字符串的单数和复数形式。
liquid
{{ 1 | pluralize: "singular", "plural" }}
{{ 2 | pluralize: "singular", "plural" }}
1 {{ 1 | pluralize: "person", "people" }}
2 {{ 2 | pluralize: "person", "people" }}
2 {{ "2" | pluralize: "person", "people" }}
Result
singular
plural
1 person
2 people
2 people

​
迭代

​
for 循环

重复执行代码块。有关 for 循环中可用属性的完整列表，请参阅 for 循环对象。
liquid
{% for product in message.custom_data.products %}
  - {{ product.name }}
  {% else %}
    抱歉，我们的所有产品都已售完。
  {% endfor %}
Request Body
{
  "app_id": "5eb5a37e-b458-11e3-ac11-000c2940e62c",
    "template_id": "be4a8044-bbd6-11e4-a581-000c2940e62c",
    "custom_data": {
      "products": [
        { "name": "Sweater" },
        { "name": "Hat" },
        { "name": "Shirt" }
      ]
    }
  }
Results
  - Sweater
  - Hat
  - Shirt

  // if message.custom_data.products is empty
  抱歉，我们所有产品都已售完
虽然功能强大且灵活，但在某些罕见情况下，在 Liquid 语法中使用 for 循环可能 导致通知传递性能不佳。请注意您对 for 循环的使用。另请注意，我们禁止在 几个推送频道字段中使用 for 循环：contents、headings、subtitle、 apns_alert 和 url

​
limit 和 offset

将循环限制为指定的迭代次数。例如，如果您只想在消息中显示 4 个产品，您可以使用限制和偏移量来指定显示的产品数量。
Data
great_numbers = [1,2,3,4,5,5]
liquid
{% for number in great_numbers limit:2 %}
  {{ number }}
{% endfor %}
Result
1 2
要在指定索引开始循环，请添加偏移值：
Data
great_numbers = [1,2,3,4,5,5]
liquid
{% for number in great_numbers limit: 3 %}
  {{ number }}
{% endfor %}

{% for number in great_numbers limit: 3 offset: 3 %}
  {{ number }}
{% endfor %}
```text Result
1 2 3
4 5 6

​
where

创建一个数组，仅包含具有给定属性值的对象，或默认情况下任何真值。 在此示例中，假设您有一个产品列表，并且想要单独显示您的厨房产品。使用 where，您可以创建一个仅包含 type 为 kitchen 的产品的数组。
Data
products = [
  {name:"Vacuum", type:"electronics"},
  {name:"Spatula", type:"kitchen"},
  {name:"Television", type:"electronics"},
  {name:"Garlic press", type:"kitchen"}
]
liquid
所有产品：
{% for product in products %}
- {{ product.name }}
{% endfor %}

{% assign kitchen_products = products | where: "type", "kitchen" %}

厨房产品：
{% for product in kitchen_products %}
- {{ product.name }}
{% endfor %}
Result
所有产品：
  - Vacuum
  - Spatula
  - Television
  - Garlic press

厨房产品：
- Spatula
- Garlic press

​
字符串操作

有时您可能有包含字符串的数据标签，其格式不适合直接向用户显示，您可能需要操作字符串来调整格式。下面是可用于调整字符串的 liquid 语法命令表。您可以在标签和直接写入消息的字符串上使用字符串操作。
命令描述示例示例输出
replace用另一个字符串替换子字符串。{{ 'hello world' | replace: 'world', 'there' }}hello there
capitalize将字符串的第一个字母大写。{{ 'hello' | capitalize }}Hello
upcase将字符串转换为大写。{{ 'hello' | upcase }}HELLO
downcase将字符串转换为小写。{{ 'HELLO' | downcase }}hello
strip从字符串中删除前导和尾随空白。{{ ' hello ' | strip }}hello
strip_html从字符串中删除所有 HTML 标签。{{ '<p>hello</p>' | strip_html }}hello
truncate将字符串缩短到指定长度，如果需要则添加省略号（…）。{{ 'This is a long sentence' | truncate: 10 }}This is a…
truncatewords在一定数量的单词后截断字符串。{{ 'This is a long sentence' | truncatewords: 2 }}This is…
replace_first替换子字符串的第一次出现。{{ 'hello world' | replace_first: 'world', 'there' }}hello there
prepend在另一个字符串的开头添加字符串。{{ 'world' | prepend: 'hello ' }}hello world
append在另一个字符串的末尾添加字符串。{{ 'hello' | append: ' world' }}hello world
lstrip从字符串中删除前导空白。{{ ' hello' | lstrip }}hello
rstrip从字符串中删除尾随空白。{{ 'hello ' | rstrip }}hello

​
常见问题

​
为什么替换不起作用？

  • 应用内消息不支持属性替换。
  • 使用”发送测试消息”时标签替换不起作用。
  • 标签键必须是字母数字，或使用 _ 和 -（不能有句点或空格）。
  • 替换不会在预览模式中显示 — 发送真实消息进行测试。

​
如何控制空白和换行？

使用连字符：{{- ... -}}、{%- ... -%} 来修剪周围的空白。 更多详情请参阅空白控制。

​
如何处理用户生成的内容？

将用户生成的文本包装在 {% raw %} 和 {% endraw %} 中以防止 Liquid 解析。参见 “raw” 语法。
json
{
  "contents": {
    "en": "{% raw %} Your user-generated content with invalid characters like {{ {% endraw %}"
  }
}
⌘I