# 模板語法

## 概述

本篇文章將介紹模板語法，透過使用變數和表達式，您可以輕鬆地構建所需的內容並進行置換。

而模板語法目前可套用於以下功能：

* 對話腳本中部分訊息操作。
* Webhook 腳本中的參數 Params 與回呼 (Callback)。

## 變數命名規則

如同多數的程式語言，如 python、JavaScript ..等，交談變數必須遵從以下規則：

1. 變數名稱必須以字母（a-z、A-Z）或下底線（\_）開頭。
2. 後續的字元可以是字母、數字（0-9）或下底線（\_）。
3. 變數的命名是區分大小寫的，大寫字母（A-Z）和小寫字母（a-z）被視為不同的字元。

以下是一些符合命名規則的變數名稱的範例：

* myVariable
* count
* first\_name
* age123

## 符號與運算子

### 分隔符

模板語法採用 `{{ ... }}`  與  `{% ... %}` 兩種符號表達，前者分隔符號將替換為實際字串輸出於內容中，如下面語法顯示，將實際輸出為「王小明，您好！」。

```javascript
{{ name }}，您好！
```

而也可以透過一個點.(dot)符號來顯示變數更深層的內容，例如

```php
{{ contact.first_name }}

{# 也能透過方括號存取內容 #}
{{ contact['first_name'] }}
```

而後者  `{% ... %}` 分隔符號，則用於執行邏輯操作，如 for、if ...等。

```php
{# 設定變數 name 為王小明 #}
{% set name = '王小明' %}

{# 這邊會顯示 0,1,2,3 依序到 10 #}
{% for i in range(0, 10) %}
    {{ i }}
{% endfor %}
```

### 算術運算子

模板提供簡易的運算符號，其他包括以下

| 運算子  | 語法範例           | 結果    | 說明                 |
| ---- | -------------- | ----- | ------------------ |
| `+`  | `{{ 1 + 2 }}`  | `3`   | 加法，只適用於數值，不可用來串接字串 |
| `-`  | `{{ 5 - 3 }}`  | `2`   | 減法                 |
| `*`  | `{{ 4 * 2 }}`  | `8`   | 乘法                 |
| `/`  | `{{ 5 / 2 }}`  | `2.5` | 除法                 |
| `//` | `{{ 7 // 2 }}` | `3`   | 整數除法（取商）           |
| `%`  | `{{ 11 % 7 }}` | `4`   | 取餘數                |

### 比較運算子

能直接透過 `==` 、`!=`、 `<`、 `>`、 `>=`  和 `<=`，並基於比較的結果回傳邏輯值。

* `==`：等於。&#x20;
* `-!`：不等於。
* `<`：小於。
* `>`：大於。
* `>=`：大於或等於。
* `<=`：小於或等於。

針對更為複雜的比較，則可使用 `matches`匹配操作符透過正則表達式比較。

```php
{% if phone_number matches '/^[\\d\\.]+$/' %}
{% endif %}
```

### 條件(三元)運算子

這個運算子能接受兩個運算元作為值並且一個運算元作為條件判斷。而 語法是：`條件 ? 數值1 : 數值2` ，下方為一些簡單範例。

```php
{{ name ? 'yes' : 'no' }}

{{ age >= 18 ? '成人' : '小孩' }}
```

### 邏輯運算子

能透過 ?? 判斷 OR 邏輯，假如 `運算式1` 可以為是的話，回傳 `運算式1`; 否則，反之回傳 `運算式2`。&#x20;

```php
{# 如果 age 已被不是空值，则顯示 name 的值，反之則顯示 unknown #}
{{ name ?? 'unknown' }}
```

## 流程控制

流程控制是指控製流程的條件語句，如`if`、`elseif`、`else`、`for`等。控制語法應放置在 `{% ... %}` 分隔符內容中。

### if...else

當條件成立的時候會執行 if 陳述式裡的語法，而不成立時則執行另外一個陳述式。

```php
{% if age >= 18 %}
    成年
{% else %}
    未成年
{% endif %}

{# 判斷數值是否存在 #}
{% if users is defined %}
  {{ user.username }}
{% endif %}
```

### for

不斷重複直到一個指定的條件式判斷為 false，直到條件不符合才停止執行，其中 for 的區塊內，你能使用內建的特殊變數。\
\
特殊變數如下：

| 變數名         | 描述                    |
| ----------- | --------------------- |
| loop.index  | 顯示當前 index（索引），由 1 開始 |
| loop.index0 | 顯示當前 index（索引），由 0 開始 |
| loop.length | 陣列的長度                 |
| loop.first  | 返回 true，若為陣列最初項目      |
| loop.last   | 返回 true，若為陣列最後項目      |

```php
{% for user in users %}
    {{ user.name }}
{% endfor %}

{# 你也可以搭配 else 判斷陣列是否空值時，如 #}
{% for user in users %}
    {{ loop.index }} - {{ user.name }}
{% else %}
    No users have been found.
{% endfor %}
```

以下是根據你提供的語氣與格式，為 `split` 用法撰寫的一段說明，可直接接續於原本的教學內容中使用：

***

## 文字過濾器

### 運算子

<table><thead><tr><th width="103.56640625">運算子 / 方法</th><th>語法範例</th><th>結果 / 功能</th><th>說明</th></tr></thead><tbody><tr><td><code>~</code></td><td><code>{{ 'Hello, ' ~ name }}</code></td><td><code>Hello, Eason</code></td><td><strong>字串拼接運算子</strong>，會自動將變數轉成字串，即使為 <code>null</code></td></tr></tbody></table>

### 字串分割

當需要將一段文字依照某個符號拆解為多個部分時，可使用 `split` 功能。例如將一段姓名依照每個字元拆分為清單資料，便能逐一取用各字：

```php
{{ name|split('') }}

{# 若 name 為「王小明」，執行後將得到： #}
['王', '小', '明']
```

也可以指定特定符號作為切割依據，例如以逗號分隔的顏色標籤：

```php
{{ 'red,blue,green'|split(',') }}

{# 結果為： #}
[['red', 'blue', 'green']
```

分割後的資料可透過 `for` 語法進行逐一處理，常用於顯示標籤、分解文字內容等需求。

## 日期過濾器

日期語法可接受字串、DateTime 物件。例如，要顯示當前日期，請將單字 “now” 作為語法的參數。

### 顯示當前時間

```php
// 輸出為 2022-05-12 22:21:10
{{ 'now' | date('Y-m-d H:i:s') }
```

### 指定時區

預設情況下，日期會套用 FIRST LINE 伺服器的時區顯示，但您可以透過明確指定時區來覆寫它：

```php
// 指定特殊時區換算
{{ 'now' | date('Y-m-d H:i:s', 'Asia/Tokyo') }}
```

如果日期已經是 DateTime 物件，且您想要保持其當前時區，請將時區值傳遞為 false。

```php
{{ product.created_at | date('Y-m-d H:i:s', false) }}
```


---

# Agent Instructions: Querying This Documentation

If you need additional information that is not directly available in this page, you can query the documentation dynamically by asking a question.

Perform an HTTP GET request on the current page URL with the `ask` query parameter:

```
GET https://help.firstline.cc/feature/other/template-syntax.md?ask=<question>
```

The question should be specific, self-contained, and written in natural language.
The response will contain a direct answer to the question and relevant excerpts and sources from the documentation.

Use this mechanism when the answer is not explicitly present in the current page, you need clarification or additional context, or you want to retrieve related documentation sections.