問卷樣板語法完整指南

本指南詳細說明 LitoForm 系統支援的所有語法、題型及進階參數。

樣板主體架構

一個完整的問卷樣板包含：全域設定、歡迎訊息、題目等三大區塊。三大區塊在樣板內需依序呈現，不可任意調動。

📋 題型快速索引

題型	用途	快速連結
`[Single]`	單選題，支援跳題邏輯	→ 詳細說明
`[Multi]`	複選題，可限制選項數量	→ 詳細說明
`[MatrixSingle]`	單選矩陣，多項目同時評價	→ 詳細說明
`[MatrixMulti]`	複選矩陣，每項目可選多個	→ 詳細說明
`[Rating]`	星級/愛心評分	→ 詳細說明
`[Slider]`	滑桿選擇數值	→ 詳細說明
`[Text]`	單行文字輸入	→ 詳細說明
`[Textarea]`	多行文字輸入	→ 詳細說明
`[Number]`	數字輸入	→ 詳細說明
`[Sort]`	拖曳排序	→ 詳細說明
`[Date]`	日期選擇器	→ 詳細說明
`[Check]`	單一核選框（同意/確認）	→ 詳細說明
`[Heading]`	章節分段標題	→ 詳細說明
`[Divider]`	視覺分隔線	→ 詳細說明
`[Intro]`	引言說明 (⚠️ 即將棄用，請改用 OpenText)	→ 詳細說明
`[OpenText]`	補充說明區塊（推薦，支援 >>> 語法）	→ 詳細說明
`[File]`	檔案上傳（需搭配 Google Drive 整合）	→ 詳細說明
`[Hidden]`	隱藏欄位（URL 參數自動帶入）	→ 詳細說明

1. 全域設定 (YAML Frontmatter)

必須位於檔案最上方，使用 --- 包裹。這些設定會影響整份問卷的行為與外觀。

基本配置（最小必要）

---
title: "問卷標題"
---

完整配置範例

---
title: "2026 年度使用者大調查"
hero_image: "https://example.com/banner.jpg"
layout: "one-per-page"
expiry_date: "2026-12-31"
quota_limit: 500
ga_id: "G-XXXXXXXXXX"
bot_protection: "cloudflare"
pages:
  thank_you:
    content: "<h1>感謝參與!</h1><p>您的意見對我們很重要。</p>"
    cta_button:
      text: "返回首頁"
      url: "https://mysite.com"
  closed:
    content: "問卷已截止，感謝您的關注。"
  terminated:
    content: "根據您的回答，問卷已提前結束。"
terms:
  label: "我已閱讀並同意個人資料保護聲明"
  content: "詳細條款內容..."
---

全域參數說明

參數	必填	說明	範例值
`title`	✅	問卷標題，顯示於瀏覽器標籤與問卷頂端	`"滿意度調查"`
`hero_image`	❌	問卷頂端的橫幅圖片 URL	`"https://..."`
`layout`	❌	顯示模式：`"one-per-page"` (逐題) 或 `"scroll"` (捲動)	`"scroll"`
`expiry_date`	❌	問卷截止日期，ISO8601 格式	`"2026-12-31"`
`quota_limit`	❌	回覆數量上限，達到後自動關閉	`500`
`ga_id`	❌	Google Analytics 追蹤 ID (詳細說明)	`"G-XXXXXXXXXX"`
`fb_pixel_id`	❌	Facebook Pixel ID (詳細說明)	`"1234567890"`
`fb_test_event_code`	❌	Facebook 測試事件代碼，僅測試用，上線前移除 (詳細說明)	`"TEST12345"`
`bot_protection`	❌	機器人防護：`"cloudflare"`, `"none"`	`"cloudflare"`
`pages.thank_you`	❌	完成頁面：`content` (HTML 內容)、`cta_button.text`、`cta_button.url`	見上方範例
`pages.closed`	❌	問卷已截止時顯示的訊息	`"問卷已截止"`
`pages.terminated`	❌	填答者被篩除時顯示的訊息	`"感謝您的參與"`
`terms.label`	❌	條款同意勾選框的標籤文字	`"我同意..."`
`terms.content`	❌	條款詳細內容（點擊可展開）	條款全文

2. 歡迎區塊 (Welcome Section)

位於 YAML 之後、第一個題目之前。支援 Markdown 語法，結尾必須用 --- 與第一題分隔。

---
title: "滿意度調查"
---

歡迎參與我們的調查

感謝您撥冗填寫這份問卷，本問卷約需 **5 分鐘**。

您的意見將幫助我們改進服務品質！

---
### Q1. [Single] 您的年齡層?
...

⚠️ 注意:

歡迎區塊裡的內容不能用 "###" 開頭，會與下方題目的開頭衝突，但可以用 "##" 或 "####"

歡迎區塊結尾的 --- 是唯一需要手動加入的分隔線，題目之間不需要加分隔線。

3. 題目標題格式

基本格式

### {ID}. [{Type}] {Title}

{ID}: 題目識別碼，如 Q1, Q2, Q_AGE
{Type}: 題型名稱（區分大小寫）
{Title}: 題目文字

### Q1. [Single] 您的職業?

標題旗標 (Flags)

旗標	功能	範例
`/H`	標題支援 HTML 標籤	`### Q1. [Single] <b>重要</b>提醒 /H`
`/P`	題目附帶圖片	`### Q1. [Single] 請選擇 /P`
`/HP`	同時支援 HTML 與圖片	`### Q1. [Single] <em>選擇</em>您的最愛 /HP`

4. 題型詳細說明

⚠️ 重要: 所有題型名稱區分大小寫，如 OpenText 不是 Opentext、Single 不是 single。

4.1 單選題 [Single]

用途: 讓填答者從多個選項中選擇一個答案。這是唯一支援跳題邏輯的題型。

語法結構:

### {ID}. [Single] {題目文字}
{{ 參數設定 }}
- ( ) 選項文字
- ( ) 選項文字 -> 跳題目標

可用參數:

參數	說明	範例
`required`	必填	`{{ required: true }}`
`display`	顯示方式：`"radio"` 或 `"select"`	`{{ display: "select" }}`
`random`	選項隨機排序	`{{ random: true }}`

選項層級設定:

設定	說明	範例
`-> {QID}`	跳至指定題目	`- ( ) 是 -> Q5`
`-> TERMINATE`	結束問卷	`- ( ) 否 -> TERMINATE`
`{{ open: true }}`	「其他」自填欄位	`- ( ) 其他 {{ open: true }}`
`![alt](url)`	選項圖片	`- ( ) ![圖](url) 文字`

範例:

### Q1. [Single] 您是否年滿 18 歲?
- ( ) 是
- ( ) 否 -> TERMINATE

### Q2. [Single] 您最常使用的交通工具?
{{ display: "select", random: true }}
- ( ) ![捷運](https://example.com/mrt.jpg) 捷運 -> Q_METRO
- ( ) ![公車](https://example.com/bus.jpg) 公車 -> Q_BUS
- ( ) 其他 {{ open: true }}

補充說明:

未設定 display 時，系統會以 radio 顯示
display 只改變呈現方式，不改變跳題、終止邏輯或答案值

4.2 複選題 [Multi]

用途: 讓填答者從多個選項中選擇一個或多個答案。

可用參數:

參數	說明	範例
`required`	必填	`{{ required: true }}`
`min`	最少選擇數量	`{{ min: 2 }}`
`max`	最多選擇數量	`{{ max: 3 }}`
`columns`	每列顯示的選項數，允許 `1` 到 `3`	`{{ columns: 3 }}`
`random`	選項隨機排序	`{{ random: true }}`

選項層級設定:

設定	說明	範例
`{{ exclusive: true }}`	排他選項（選此則取消其他）	`- [ ] 以上皆非 {{ exclusive: true }}`
`{{ open: true }}`	「其他」自填欄位	`- [ ] 其他 {{ open: true }}`

範例:

### Q1. [Multi] 請選擇 2-3 項您最看重的因素
{{ min: 2, max: 3, columns: 3, random: true }}
- [ ] 價格
- [ ] 品質
- [ ] 服務
- [ ] 品牌
- [ ] 以上皆非 {{ exclusive: true }}

補充說明:

未設定 columns 時，系統會以單欄顯示
columns 主要影響桌機版配置；在窄螢幕上，系統可能自動改為較少欄數

4.3 矩陣題 [MatrixSingle] & [MatrixMulti]

用途: 用表格形式同時評價多個項目。MatrixSingle 每列選一個，MatrixMulti 每列可選多個。

可用參數:

參數	適用	說明	範例
`required`	兩者	必填	`{{ required: true }}`
`max_per_row`	MatrixMulti	每列最多選擇數	`{{ max_per_row: 2 }}`

範例:

### Q1. [MatrixSingle] 請評價以下服務項目
- Row: 客服態度
- Row: 處理速度
- Row: 問題解決能力
- Options: 非常滿意, 滿意, 普通, 不滿意

### Q2. [MatrixMulti] 您在各時段可參加的活動? (每天最多選 2 個)
{{ max_per_row: 2 }}
- Row: 星期一
- Row: 星期二
- Row: 星期三
- Options: 早上, 中午, 下午, 晚上

4.4 評分題 [Rating]

用途: 使用星星、愛心等圖示進行評分。

可用參數:

參數	說明	預設	範例
`max`	最高分數	`5`	`{{ max: 10 }}`
`icon`	圖示類型：`"star"`, `"heart"`	`"star"`	`{{ icon: "heart" }}`
`labels`	兩端文字標籤	無	`{{ labels: ["不推薦", "強力推薦"] }}`

範例:

### Q1. [Rating] 整體滿意度?
{{ max: 5 }}

### Q2. [Rating] 您有多喜歡這個產品?
{{ icon: "heart", max: 10, labels: ["超討厭", "超喜歡"] }}

4.5 滑桿題 [Slider]

用途: 讓填答者拖曳滑桿選擇數值，適合價格、分數等連續數值。

可用參數:

參數	說明	預設	範例
`required`	必填	`false`	`{{ required: true }}`
`min`	最小值	`0`	`{{ min: 1000 }}`
`max`	最大值	`100`	`{{ max: 50000 }}`
`step`	間距	`1`	`{{ step: 1000 }}`
`show_value`	顯示即時數值	`false`	`{{ show_value: true }}`

範例:

### Q1. [Slider] 您願意支付的價格?
{{ min: 1000, max: 50000, step: 1000, show_value: true }}

### Q2. [Slider] NPS 推薦分數
{{ min: 0, max: 10, step: 1, show_value: true }}

4.6 單行文字輸入 [Text]

用途: 收集單行文字資料，如姓名、Email、電話。

可用參數:

參數	說明	範例
`required`	必填	`{{ required: true }}`
`placeholder`	輸入框提示文字	`{{ placeholder: "請輸入..." }}`
`format`	格式驗證（見下表）	`{{ format: "email" }}`
`min_length`	最少字元數	`{{ min_length: 8 }}`
`max_length`	最多字元數	`{{ max_length: 12 }}`

format 格式驗證選項:

值	驗證內容
`"email"`	電子郵件格式
`"mobile"`	手機號碼
`"id_card"`	身分證字號（台灣）
`"url"`	網址格式

範例:

### Q1. [Text] 您的姓名?
{{ required: true }}

### Q2. [Text] 電子郵件
> 我們將透過此信箱發送抽獎通知
{{ format: "email", placeholder: "[email protected]" }}

4.7 多行文字輸入 [Textarea]

用途: 收集較長的文字回應。

可用參數:

參數	說明	預設	範例
`required`	必填	`false`	`{{ required: true }}`
`placeholder`	輸入框提示文字	無	`{{ placeholder: "請輸入..." }}`
`rows`	顯示行數（高度）	`3`	`{{ rows: 8 }}`
`min_length`	最少字元數	無	`{{ min_length: 20 }}`
`max_length`	最多字元數	無	`{{ max_length: 500 }}`

範例:

### Q1. [Textarea] 您的建議
{{ rows: 5, placeholder: "請輸入您的想法..." }}

### Q2. [Textarea] 請詳述您的問題 (至少 20 字)
{{ required: true, min_length: 20, max_length: 500, rows: 8 }}

4.8 數字輸入 [Number]

用途: 收集數值資料，如年齡、數量、金額。

可用參數:

參數	說明	範例
`required`	必填	`{{ required: true }}`
`min`	最小值	`{{ min: 0 }}`
`max`	最大值	`{{ max: 120 }}`
`step`	間距	`{{ step: 1000 }}`
`unit`	單位文字	`{{ unit: "元" }}`

範例:

### Q1. [Number] 您的年齡?
{{ min: 0, max: 120 }}

### Q2. [Number] 每月預算
{{ min: 0, max: 100000, step: 1000, unit: "元" }}

4.9 排序題 [Sort]

用途: 讓填答者拖曳排列選項順序。

可用參數:

參數	說明	範例
`required`	必填	`{{ required: true }}`
`limit_top`	只需排序前 N 項	`{{ limit_top: 3 }}`

範例:

### Q1. [Sort] 請依重要性排序以下因素
- [ ] 價格
- [ ] 品質
- [ ] 服務
- [ ] 速度

### Q2. [Sort] 請選出並排序您最重視的 3 項
{{ limit_top: 3 }}
- [ ] 設計美觀
- [ ] 功能完整
- [ ] 操作簡易

4.10 日期選擇 [Date]

用途: 讓填答者選擇日期。

可用參數:

參數	說明	範例
`required`	必填	`{{ required: true }}`
`range`	可選範圍：`"all"`, `"past"`, `"future"`	`{{ range: "past" }}`

range 選項說明:

值	說明
`"all"`	不限制，可選任何日期
`"past"`	僅能選擇今天（含）以前的日期
`"future"`	僅能選擇今天（含）以後的日期

範例:

### Q1. [Date] 您的生日?
{{ range: "all" }}

### Q2. [Date] 您的入職日期
{{ range: "past" }}

### Q3. [Date] 您希望的到貨日期
{{ range: "future" }}

4.11 單一核選框 [Check]

用途: 用於同意條款、訂閱確認等。

可用參數:

參數	說明	範例
`required`	必須勾選才能繼續	`{{ required: true }}`

範例:

### Q1. [Check] 我同意訂閱電子報
{{ required: false }}

### Q2. [Check] 我已閱讀並同意服務條款
{{ required: true }}

4.13 檔案上傳 [File]

用途: 讓填答者上傳一個或多個檔案，檔案將儲存至 Google Drive。需事先在問卷設定中連結 Google Drive 並建立資料夾。

可用參數:

參數	說明	預設	範例
`required`	必填	`false`	`{{ required: true }}`
`ext`	允許的副檔名列表	不限	`{{ ext: ["pdf", "jpg", "png"] }}`
`max_size_mb`	單檔最大容量（MB）	`10`	`{{ max_size_mb: 5 }}`
`max_count`	最多上傳檔案數量	`5`	`{{ max_count: 3 }}`

範例:

### Q1. [File] 請上傳您的履歷
{{ required: true, ext: ["pdf", "docx"], max_size_mb: 10 }}

### Q2. [File] 請上傳作品圖片（最多 3 張）
{{ ext: ["jpg", "jpeg", "png"], max_size_mb: 5, max_count: 3 }}

⚠️ 注意: [File] 題型需要問卷擁有者在問卷設定中事先連結 Google Drive，否則上傳功能將無法使用。

4.14 隱藏欄位 [Hidden]

用途: 隱藏欄位不會顯示給填答者，用來透過 URL 參數自動帶入特定值（如來源管道、推薦人 ID 等），方便後續資料分析。

填答者看不見此欄位，頁面上不會渲染任何輸入框
欄位值透過 URL 查詢參數自動填入，參數名稱即為題目 ID
預覽模式下可見（以半透明虛線框顯示）

語法:

### {ID}. [Hidden] {欄位說明}

若題目 ID 為 UTM_SOURCE，則問卷連結加上 ?UTM_SOURCE=facebook 即可自動填入值。

範例:

### UTM_SOURCE. [Hidden] 來源管道
### REF_CODE. [Hidden] 推薦人代碼
### CAMPAIGN. [Hidden] 活動名稱

4.15 視覺與輔助題型

分段標題 [Heading]

用途: 將問卷分成多個章節。

### SEC1. [Heading] 第一部分：基本資料

分隔線 [Divider]

用途: 在題目之間插入視覺分隔線。內容應為 ---。

### DIV1. [Divider] ---

引言說明 [Intro] (⚠️ 即將棄用)

重要通知: [Intro] 題型將在未來版本中移除，請改用功能完全相同的 [OpenText]。

用途: 在問卷開頭或章節開始處顯示引言、說明。與 OpenText 功能完全相同。

### INFO1. [Intro] 歡迎參與本次調查
>>>
本問卷約需 5 分鐘，所有資料僅供研究使用。

感謝您的協助！
>>>

### INFO2. [Intro] 問卷須知
>>>
本問卷分為三個部分：
1. 基本資料
2. 使用體驗

請依您的真實感受填寫。
>>>

補充說明 [OpenText] (推薦)

用途: 在問卷中任意位置顯示補充說明、提示。推薦使用 >>> 區塊語法。

### NOTE1. [OpenText] 填寫說明
>>>
以下問題將詢問您對各項功能的滿意度。

請依據您的 **實際使用經驗** 作答，您的意見將幫助我們改進服務。
>>>

### NOTE2. [OpenText] 評分標準
>>>
接下來的評分題中：
- 1 分代表非常不滿意
- 5 分代表非常滿意

請根據您的真實感受評分。
>>>

5. 題目說明語法

在題目標題下方可加入說明文字：

單行/多行引言: 以 > 開頭。
區塊描述: 用 >>> 包覆，保留格式與換行。

6. 跳題邏輯

僅 [Single] 支援。使用 -> {QID} 或 -> TERMINATE。跳跳目標 ID 必須存在。

7. 格式規範與驗證

項目	正確限制
題型大小寫	必須精確與列表一致
開頭標記	題目必須以 `###` 開頭
選項格式 (單選)	`- ( ) 選項`
選項格式 (複選)	`- [ ] 選項`
ID 唯一性	全份問卷 ID 不可重複
數值檢查	`min` 不可大於 `max`
`display` 檢查	`[Single]` 只允許 `radio`、`select`
`columns` 檢查	`[Multi]` 只允許整數 `1`、`2`、`3`
矩陣結構	必須包含 `Row:` 與 `Options:`

8. 常見問題解答 (FAQ)

Q1: 為什麼我的問卷內容沒有顯示出來？

A: 請檢查以下幾點：

YAML 區塊結尾：YAML 設定區塊（--- 段落）與第一題之間必須使用 --- 分隔線。
題目開頭：每個題目的標題必須以 ### 開頭。
語法錯誤：檢查參數是否使用了正確的雙分號 {{ ... }} 且格式正確。

Q2: 只有單選題可以設定跳題邏輯嗎？

A: 是的，目前系統僅支持 [Single]（單選題）題型進行邏輯跳轉。在選項後方使用 -> {ID} 或 -> TERMINATE 來指定跳轉目標。

Q3: 如何在題目或選項中加入圖片？

題目圖片：在標題末尾加上 /P 旗標，並在下一行使用 Markdown 語法 ![描述](圖片網址)。
選項圖片：在選項括號後直接加入 ![描述](圖片網址)，例如 - ( ) ![圖片](url) 選項文字。

Q4: 為什麼我的矩陣題（Matrix）顯示異常？

A: 矩陣題必須同時包含 - Row:（定義評價項目）與 - Options:（定義評分等級）兩種標籤。缺少任何一個都會導致解析失敗。

Q5: 如何自定義提交後的「感謝頁面」？

A: 您可以在問卷最上方的「設定區塊」（兩個 --- 之間）加入 pages 設定：

pages:
  thank_you:
    content: "<h1>感謝您的填寫！</h1><p>我們已收到您的回應。</p>"
    cta_button:
      text: "返回首頁"
      url: "https://your-site.com"

Q6: 為什麼我修改了「設定區塊」卻沒有生效？

A: 請檢查以下幾個容易被忽視的小細節：

多餘的空白：請確保每一行前面是用「空白鍵」縮進，而不是 Tab 鍵。
冒號後面要加空格：例如 title: "我的問卷"，在冒號 : 後面一定要有一個空格。
引號要成對：如果您使用了雙引號 "，請確認開頭和結尾都有加。

Q7: 儲存時出現「ID 重複 (Duplicate ID)」警告？

A: 這代表您的問卷中有兩個題目使用了同樣的編號（例如兩個題目都叫 ### Q1）。即使是在不同的章節，每個題目的編號也必須是唯一的。請像檢查座號一樣，確保每個人（題目）都有自己專屬的編號喔！

Q8: 跳題邏輯顯示「找不到目標」？

A: 當您設定「選 A 就跳到 Q5」時，系統會去尋找編號叫 Q5 的題目。

請檢查編號的英文大小寫是否完全一樣（例如 q5 與 Q5 是不同的）。
確保您要跳過去的那個題目確實存在，沒有被刪除。

Q9: 為什麼畫面上出現了像 `{{ required: true }}` 這樣的奇怪符號？

A: 這代表系統沒能讀懂這條指令。通常是因為：

使用了全形標點：請檢查括號或冒號是否誤用了全形（中文格式）的符號。
拼寫錯誤：請對照本指南，確認英文單字沒有拼錯。

Q10: 為什麼我的多行說明（使用 `>>>`）顯示變得很亂？

確保開頭的 >>> 與結尾的 >>> 都是各佔一行，前後不要放任何文字。
開頭的 >>> 要緊貼在題目標題下方，不要留空行。

欲了解更多詳情，請參閱各題型之獨立文件或範例問卷。

問卷樣板語法完整指南

On this page