---
title: 模板系统 - 动态通知内容
sidebarTitle: 模板
description: 掌握 Echobell 的模板系统以创建动态、信息丰富的通知。包含变量替换、表达式、运算符、系统变量和通知模板最佳实践的完整指南。
---

# Echobell 模板

模板允许您通过在通知标题和正文中加入变量来创建动态、包含丰富上下文的通知。这个强大的功能使个性化和信息性告警能够根据触发数据进行调整，将泛泛的通知转化为可操作的情报。

Echobell 中的模板允许您通过在通知标题和内容中整合变量来创建动态通知。此功能可根据触发数据生成个性化和信息丰富的提醒。

## 基本模板语法

在 Echobell 模板中，您可以通过将变量包裹在双大括号中来使用它们：

```
{{变量名}}
```

当频道被触发时，这些变量将被通过触发器传递的实际值所替代。例如，如果您的标题模板是 `您已收到 ${{amount}}`，并且您用 `amount` 值为 100 触发了频道，结果通知将显示为 `您已收到 $100`。

## 高级模板表达式

Echobell 模板支持多种表达式，适用于更复杂的场景：

- 访问对象属性

```
{{user.name}}
{{user["name"]}}
```

- 访问数组元素

```
{{list[0]}}
```

- 使用比较运算符

```
{{status == "active"}}
{{age > 18}}
```

- 逻辑运算符

```
{{isSubscribed && !isPaused}}
{{isUrgent || isPriory}}
```

支持所有标准运算符：`==`、`!=`、`<`、`>`、`<=`、`>=`、`&&`、`||` 和 `!`。

## 来自不同触发器的模板变量

### Webhook 触发器

通过 webhook 触发时，您可以通过以下方式提供变量：

1. **查询字符串参数**：

   ```http
   GET https://hook.echobell.one/t/<channel-token>?amount=100&status=active
   ```

2. **JSON 主体**（用于 POST 请求）：

   ```http
   POST https://hook.echobell.one/t/<channel-token>
   Content-Type: application/json

   {
     "amount": 100,
     "status": "active",
     "user": {
       "name": "张三",
       "id": 12345
     }
   }
   ```

3. **特殊变量**：

   - `externalLink`：在通知记录中提供可点击链接
   - `bodyAsText`: 如果 `Content-Type` 是 `text/plain`，则为请求正文的纯文本内容
   - `header`：提供对 HTTP 请求头的访问（例如，`{{header["content-type"]}}`)

### 电子邮件触发器

当频道通过电子邮件触发时，以下变量将自动可用：

- `from`：发件人电子邮件地址
- `to`：收件人电子邮件地址
- `subject`：电子邮件主题行
- `text`：电子邮件的纯文本内容
- `html`：电子邮件的 HTML 内容

## 模板使用案例

### 比较与布尔值

使用比较或逻辑运算符的表达式会将其布尔结果渲染为文本 `true` 或 `false`：

```
支付超过 $1000：{{amount > 1000}}
高优先级：{{isUrgent || isImportant}}
```

Echobell 模板**不**支持内联的 if/else（三元）逻辑。要在不同情况下发送不同内容，请使用频道[条件](/docs/conditions)来路由触发，或直接插入原始值。

### 频道条件

除了在通知内容中使用模板外，您还可以在频道高级设置中设置**条件**，确定是否应发送通知。这些条件使用相同的表达式语法（不含大括号）。

例如，仅对超过阈值的金额发送通知：

```
金额 > 100
```

## 链接模板

在频道高级设置中配置自定义链接模板，以在通知记录中创建可点击链接：

```
https://dashboard.example.com/orders/{{orderId}}
```

如果未设置链接模板，将默认使用 `externalLink` 变量的值。

## 系统时间变量（UTC）

这些变量在模板（以及条件）中始终可用，且以 UTC 计算。

以下值直接（扁平）注入，可按名称使用：

- `year`、`month`（1–12）
- `dayOfMonth`、`dayOfWeek`（0–6，周日 = 0）
- `hour`（0–23）、`minute`、`second`
- `date`（`YYYY-MM-DD`）、`time`（`HH:mm:ss`）
- `iso`：ISO‑8601 时间戳（如 `2025-05-06T12:34:56.789Z`）

其他值**仅**在 `sys.` 命名空间下可用（它们不会作为扁平名称注入）：

- `sys.timezone`：恒为 `"UTC"`
- `sys.now`：ISO‑8601 时间戳（与 `iso` 相同的值）
- `sys.epochMs`、`sys.epochSeconds`：自 Unix 纪元以来的当前时间（数字）
- `sys.monthName`：月份名称（`January`–`December`）
- `sys.dayOfWeekName`：星期名称（`Sunday`–`Saturday`）

`sys.` 命名空间也镜像了所有扁平值（例如 `sys.year`、`sys.hour`）。

示例：

```
发送时间 {{date}} {{time}} {{sys.timezone}}
今天是 {{sys.dayOfWeekName}}，{{sys.monthName}} {{dayOfMonth}}，{{year}}
Epoch：{{sys.epochSeconds}}
```

## 最佳实践

1. **处理缺失变量**：Echobell **没有默认值运算符**。`||` 运算符纯粹是逻辑运算——它将两侧作为布尔值求值并渲染 `true` 或 `false`。因此 `{{username || "匿名用户"}}` 会渲染字面文本 `true` 或 `false`，而绝不会是用户名或回退字符串。当变量缺失时，`{{variable}}` 只会渲染为空字符串。如果需要保证有值，请在触发负载中显式发送该值，而不要依赖模板回退：

   ```
   用户：{{username}}
   服务器：{{serverName}}
   检测到的错误：{{errorCount}}
   ```

2. **信息丰富的模板**：在模板中包含关键信息，使通知具有可操作性：

   ```
   {{service}}：{{status}} - {{message}}
   ```

3. **保持模板简洁**：当标题和内容清晰简洁时，通知效果最佳。

4. **测试**：使用不同的变量组合测试您的模板，确保它们按预期显示。

模板是创建动态、信息丰富的通知的强大方式，能在用户需要时给他们提供恰到好处的信息。