一、反斜線 \ 轉義規則

預設變數：#set($dog = "woof woof")

1. Velocity變數名必須以字母開頭，$10.0不會被識別為變數，直接原樣輸出；所以文字寫微軟$10.0美元不需要額外轉義；
2. 連續反斜線兩兩抵消；只有\$可以轉義錢幣符號；
3. 頁面要直接顯示$變數名，標準寫法：\$dog。

二、#if 分支條件語法

#set($ages = 22)
#if ($ages <13)
    <h1>你是兒童</h1>
#elseif ($ages <18)
    <h1>你是少年</h1>
#elseif ($ages <35)
    <h1>你是青年</h1>
#elseif ($ages <60)
    <h1>你是中年</h1>
#else
    <h1>你是老年</h1>
#end

執行結果

$ages=22，符合 22 < 35 → 輸出：<h1>你是青年</h1>

注意事項

1. 結尾一定要寫#end關閉判斷區塊，缺少會報錯；
2. 關鍵字：#elseif（千萬不要拆成 #else if，這是錯誤寫法）；
3. 條件可使用：< > <= >= == != && ||這類運算子；
4. 比對規則：由上往下判斷，匹配第一個成立條件後，後續分支不再執行。

轉義與if判斷

一、後端 Person 實體程式碼（C#）

public class Person
{
    private string name;
    public string Name
    {
        get { return name; }
        set { name = value; }
    }
    private int age;
    public int Age
    {
        get { return age; }
        set { age = value; }
    }

    //無參數建構子
    public Person(){}
    //帶參數建構子
    public Person(string name, int age)
    {
        this.name = name;
        this.age = age;
    }

    //無參數實例方法
    public string getMyName()
    {
        return this.name;
    }

    //多參數實例方法
    public string JoinStr(string str1, string str2)
    {
        return str1 + str2;
    }
}

cs後端程式碼設定物件變數

Person pTest = new Person("Tom", 22);
context.Put("pTest", pTest);

二、VTL 樣板程式碼 & 渲染說明

方法的呼叫<br />
$pTest.getMyName();

#set($a = "hello")
#set($b = "foxdevelop")

$pTest.JoinStr($a, $b);

1. $pTest.getMyName()

• 呼叫物件無參數方法 getMyName()
• 回傳 Tom

Velocity 呼叫無參方法：括號()可以省略，$pTest.getMyName 等同 $pTest.getMyName()

2. $pTest.JoinStr($a, $b)

• 呼叫帶兩個字串參數的方法
• VTL 會先解析 $a、$b，傳入實際參數 "hello"、"foxdevelop"
• 回傳拼接結果：hellofoxdevelop

總結

1. 方法名稱大小寫必須完全相符
   C# getMyName() ≠ GetMyName()，樣板寫法要和程式碼保持一致。
2. 直接傳入變數
   不需要額外加引號，$pTest.JoinStr($a,$b) 寫法正確；不要寫成 $pTest.JoinStr("$a","$b")（會傳入字串字面”$a”）
3. 屬性與方法的區別

• $pTest.Name → 存取屬性（getter）
• $pTest.getMyName() → 呼叫方法

1. 回傳值自動輸出
   樣板內直接寫 $物件.方法()，Velocity會自動輸出方法回傳值；不想輸出時使用 #set 接收結果：

#set($result = $pTest.JoinStr($a,$b))

三、頁面最終渲染結果

方法的呼叫
Tom;

hellofoxdevelop;

擴充方法

變數預設：#set ($valok = "hello foxdevelop")

變數邊界 ${} 與 . 存取差異解析

${valok}.cn 變數 + 後綴拼接
${valok.cn} 存取物件 valok 底下的 cn 屬性

單引號 / 雙引號 & 變數黏連

程式碼	渲染結果	原理說明
what$valok	whathello foxdevelop	直接拼接，Velocity 自動辨識變數邊界
what$"valok"	what$”valok”	語法錯誤，$ 後面不能緊接引號，無法解析變數
what"$valok"	what”hello foxdevelop“	引號僅為普通文字，模板內引號不會觸發字串解析，變數正常渲染
what'$valok'	what’hello foxdevelop‘	同上，單引號屬於一般文字字元
$valokwhat	$valokwhat	無法辨識變數！Velocity 將 valokwhat 視為完整變數名稱，找不到就直接輸出原始文字
${valok}what	hello foxdevelopwhat	大括號鎖定邊界，解決變數與文字黏連問題

總結

1. 變數與文字黏連務必使用 ${變數名}
   錯誤：$valokwhat；正確：${valok}what
2. 拼接後綴文字：${valok}.cn 不要寫成 ${valok.cn}
3. $!變數 靜默引用：變數不存在時輸出空白，不會印出 $xxx
4. 模板 HTML 裡的單/雙引號只是普通字元；只有 #set 賦值內部才會區分單引號（不解析變數）、雙引號（解析變數）

#set($a = "$valok") // 雙引號：解析變數，a=hello bamn
#set($a = '$valok') // 單引號：不解析變數，a=$valok

變數邊界補充說明

一、遍歷字串 List

C#後端程式碼

List<string> strList = new List<string>() {"dsd","sdfsd","asdfsd","asdfsdfsd"};
context.Put("strList", strList);

Velocity範本程式碼

#foreach($str in $strList)
    $str <br/>
#end

執行效果：迴圈取出清單每一個字串，換行輸出。

語法說明

#foreach(迴圈變數 in 集合) 開啟迴圈，#end 結束迴圈。

二、遍歷自訂實體類別 List

1. Person實體（C#）

public class Person
{
    private string name;
    public string Name
    {
        get { return name; }
        set { name = value; }
    }
    private int age;
    public int Age
    {
        get { return age; }
        set { age = value; }
    }
    public Person(){}
    public Person(string name,int age)
    {
        this.name = name;
        this.age = age;
    }
}

2. 後端封裝List

List<Person> pList = new List<Person>();
pList.Add(new Person("Jack", 1));
pList.Add(new Person("Ben", 11));
pList.Add(new Person("Kevin", 100));
pList.Add(new Person("Simon", 500));
pList.Add(new Person("Lulu", 20));
context.Put("pList", pList);

3.範本存取屬性寫法

範本程式碼：

#foreach($per in $pList)
<tr>
    <td>$per.name</td>
    <td>$per.age</td>
</tr>
#end

會讀取不到資料！報錯或是空白

根本原理

Velocity 存取物件屬性規則：
$per.xxx 會自動尋找 公開Get方法 GetXxx()

• $per.name → 嘗試呼叫 per.getName()
• $per.age → 嘗試呼叫 per.getAge()

你的實體：

• 私有欄位：name、age
• 公開屬性開頭大寫：Name、Age，對應方法 GetName()、GetAge()

正確範本寫法：

#foreach($per in $pList)
<tr>
    <td>$per.Name</td>
    <td>$per.Age</td>
</tr>
#end

補充：C#規範屬性首字母大寫；Java實體屬性通常小寫，這是新手很容易踩的大小寫陷阱。

三、#foreach內建常用變數

迴圈內部自帶變數，可以直接使用：

範例：

#foreach($per in $pList)
    $foreach.count 、姓名：$per.Name
#end

四、表格顯示

<table border="0" cellpadding="0" cellspacing="0">
#foreach($per in $pList)
    <tr>
        <td>$per.Name</td>
        <td>$per.Age</td>
    </tr>
#end
</table>

總結

1. #foreach(變數 in 集合) + #end 是Velocity標準迴圈；
2. 遍歷普通List，直接輸出$變數；
3. 遍歷實體物件：$物件.屬性名 要匹配屬性大小寫，不要存取私有欄位；
4. C#實體屬性建議統一開頭大寫，範本寫法保持一致；
5. 如果出現資料空白，優先檢查屬性大小寫、get存取器是否存在。

遍歷集合

一、模板註釋區分

開發建議：業務說明程式註釋優先使用## / #* *#，避免網頁原始碼外洩註釋內容。

二、變數命名規則

官方基礎命名規則

1. 變數第一個字元必須為英文字母（a‑z / A‑Z）
2. 後續可使用字元：字母、數字0‑9、底線_、減號-

減號 - 會產生運算子歧義

#set($name-d = "test")

執行會出現錯誤：Encountered "name" ... Was expecting one of:
原因：Velocity將 - 解讀為減法運算子！
引擎解析邏輯：$name - d，誤以為是變數$name減去變數d，造成語法衝突。

兩種解決方案：

1. 建議：改用底線命名（無歧義，通用規範）

#set($name_d = "hello world")

2. 使用大括號限定變數邊界（相容包含減號的變數名）

#set(${name-d} = "hello world")
${name-d}

合法／非法範例對照

# 合法
#set($name_d = "底線")
#set($name12d = "字母開頭加上數字")
#set(${name-1_2d} = "包含減號必須加大括號")

# 直接寫減號，沒有大括號 → 解析錯誤
#set($name-d = "發生錯誤！")
#set($name-1_2d = "發生錯誤！")

三、#set 語法書寫規範

標準寫法（括號前後空格可彈性調整，建議維持統一風格）

#set($變數名稱 = "值")

字串內容必須使用雙引號包覆；等號兩側建議保留空格，提升可讀性。

註釋

一、核心作用

Velocity 模板引擎透過 #include / #parse 實現模板複用。
網頁通用區塊，例如頁面頂部導航_head.htm、頁尾版權資訊_footer.htm，可以抽離成獨立子模板，在頁面內引入，避免多處重複撰寫 HTML。

二、兩者核心差異

1. #include("檔案路徑")

直接輸出檔案原始內容，不會解析子模板當中的 Velocity 變數（$!{xxx}）

• 子模板裡的 $!{testinclude} 不會被解析渲染，直接輸出原始字串$!{testinclude}
• 支援一次匯入多個檔案：#include("a.htm","b.htm")
• 適用場景：純靜態 HTML、完全不含 VTL 變數的靜態片段

2. #parse("檔案路徑")

載入子模板並完整解析 Velocity 語法，父模板傳入的變數可以在子模板正常渲染

• 子模板內的 $!{testinclude} 會讀取上下文變數，替換成後端傳入的實際值
• 僅接受單一檔案路徑，不支援同時匯入多個檔案
• 適用場景：頁首、頁尾這類帶有變數的公共模板（頁面標題、動態版權文字等）

對應筆記截圖原文：
#include只是單純把子模板程式碼貼入主模板，不會做解析；#parse則會執行解析動作

三、範例演示

1. 後端程式碼（.cs）

context.Put("testinclude", "子模板的文字：");

2. 子模板 _footer.htm 內容

版權資訊 $!{testinclude}

場景① 使用 #include("./themes/default/_footer.htm")

頁面輸出結果：

版權資訊 $!{testinclude}

變數沒有解析，直接印出佔位符。

場景② 使用 #parse("./themes/default/_footer.htm")

頁面輸出結果：

版權資訊 子模板的文字：

變數正常渲染，這也就是專案中頁首、頁尾公共模板優先選用#parse的原因。

四、場景建議

開發規範：
頁面導航、頁尾版權這類很可能需要動態變數的公共元件，統一使用#parse；純靜態文字與樣式片段使用#include。

模板複用

一、變數定義 #set()

兩種定義變數的方式：
方式1：後台 C#/Java 程式預先定義變數，模板頁面讀取；
方式2：直接在模板內使用 #set() 定義變數（本課重點）

#set($name = "hello foxdevelop.com")
#set($okay = "common baby")
#set($nameokay = "$name|$okay")

• #set(變數 = 值)，支援字串、數字、陣列、物件屬性、其他變數指派
• 弱型別，不用宣告變數型別

二、變數渲染兩種寫法與規範

1. 基礎形式

• $name：變數不存在時，直接輸出原文 $name
• $!name：靜默渲染，變數不存在輸出空白（建議使用，避免頁面出現 $xxx 亂碼文字）
• 建議標準寫法：${name}（大括號明確區隔變數邊界）

2. 邊界問題範例

#set($name = "hello")
$namehello     × 引擎會把它當成變數 $namehello，找不到就直接輸出
${name}hello   √ 正確，解析 $name，再接上 hello 純文字

三、單行註解 ##

## 這裡是註解，最終不會輸出到頁面
#set($name = "test") ## 行尾也可以寫註解

1. 註解內容不會輸出到最終渲染網頁；
2. 瀏覽器檢視網頁原始碼，也看不到註解內容（模板引擎處理階段直接捨棄註解）。

四、#set 支援的各種指派型別

## 字串指派
#set($name = "hello world")

## 把變數指派給另一個變數
#set($obj= $name)

## 物件屬性指派
#set($obj.Friend = "monica")
#set($obj.Blame = $whitehouse.Leak)

## 呼叫方法，把回傳值指派過來
#set($obj.Plan = $spindoctor.weave($web))

## 數值指派
#set($obj.Number = 123)

## 陣列指派
#set($obj.Say = ["Not", $my, "fault"])

五、變數不存在時的特殊規則

$sadfsdfsd

當模板引擎找不到該變數時：

• 一般寫法 $sadfsdfsd：直接輸出文字 $sadfsdfsd
• 寫成 $!sadfsdfsd：變數不存在，輸出空字串

在模板內設定變數

1. PageInfo實體類別

過去我們只傳入單一字串，不僅效率差，後續維護也很麻煩。透過封裝實體物件，可以讓程式碼更直觀好讀。

public class PageInfo
{
    private bool IsShowImage;
    public bool IsShowImage1
    {
        get { return IsShowImage; }
        set { IsShowImage = value; }
    }
}

• 私用欄位IsShowImage，對外開放屬性IsShowImage1
• 模板存取寫法：$info.IsShowImage1

2. 填入上下文資料

//模板上下文容器
IContext context = new VelocityContext();

PageInfo pi = new PageInfo();
pi.IsShowImage1 = true;

//將物件pi以鍵名info存入上下文
context.Put("info",pi);

//字串變數範例
context.Put("infotitle","你好");

context.Put("鍵名",資料)：把資料交給模板，模板透過$鍵名讀取資料。

二、Velocity模板核心語法

1. 指令符號 #

開頭帶#即為模板指令，常用：
#if、#else、#end、#foreach、#set、#include

條件渲染範例：

準備兩張圖片，放到網站根目錄的Contents/Images資料夾，透過設定IsShowImage1切換要顯示的圖片

#if($info.IsShowImage1)
    <img src="./Contents/Images/a.gif" />
#else
    <img src="./Contents/Images/b.gif" />
#end

邏輯：當IsShowImage1=true顯示a.gif，反之顯示b.gif

2. 變數符號 $

• $變數名稱：輸出變數內容
• ${變數名稱}：界定變數邊界（重點！）

場景：變數後緊接文字，引擎無法分辨變數名結束位置

錯誤寫法：$infotitlefoxdevelop.com
引擎會把整串視為變數 infotitlefoxdevelop，該變數不存在！

正確寫法：${infotitle}foxdevelop.com
引擎讀取infotitle變數，再接上字串foxdevelop.com

3. 靜默輸出符號 ! → $!變數名稱

預設行為：變數不存在時，頁面直接輸出原始$變數名稱文字
$!變數名稱：變數不存在或是null時，輸出空白，不會印出$符號

對照範例：

完整測試程式碼：

${infotitle}foxdevelop.com <br/>
$!infotitlefoxdevelop.com <br/>
$infotitle <br/>
$!infotitle <br/>

總結

1. 變數後面要拼接文字，務必使用 ${變數}包裹
2. 正式環境建議優先使用 $!{變數名稱}，避免變數空值時印出原始$xxx打亂頁面排版
3. #if判斷布林屬性，直接寫#if($info.IsShowImage1)，不需要額外加上==true

基礎模板語法

介紹

廣泛運用於 ASP.NET 專案；
ASP.NET MVC 內建 Razor 模板引擎；

若傳統 .aspx 頁面專案想要導入 MVC 架構，不少開發者會選擇 NVelocity。

NVelocity 早已停止維護，僅適合舊版 .NET Framework 歷史專案使用；新專案建議優先採用 Razor、Handlebars.NET 等現代模板引擎。

版本與 .NET Framework 對照表

Velocity 是資深 Java 模板引擎，語法簡潔，使用 #、$ 做為模板標記；NVelocity 完整移植這套語法；

下載

官方最後更新時間為2018年，最新版本為1.2.0

讀者可以透過下方連結取得原始碼

此專案為開源專案，存放於 GitHub castleproject/NVelocity: Castle’s NVelocity

官方提供的套件不含預編譯 DLL，讀者下載原始碼後可自行編譯，或是直接將專案匯入方案中使用。

使用 Visual Studio 開啟 sln 方案檔

最後釋出版本是以 .NET Core 2.1 建置，建議開發者將其升級至 .NET 4.8

編譯完成後，輸出目錄即可取得 DLL 檔案

接著將 NVelocity.dll 匯入其他 ASP.NET Web 專案即可。

匯入專案

專案參考組件：NVelocity.dll
核心優勢：透過此模板引擎，能輕鬆實現網站多模板切換（換膚）功能

在網站根目錄建立資料夾 Themes，做為所有模板的根目錄
在 Themes 底下建立多個主題資料夾，範例如下：

於網站根目錄建立 Themes 資料夾，做為主題存放目錄

主題目錄

新增 default 資料夾做為預設模板
後續可依需求新增 Themes/blue、Themes/dark 等多套模板

網站根目錄
└── Themes
    ├── default      # 預設主題模板檔
    ├── dark         # 深色主題模板檔
    └── blue         # 藍色主題模板檔

程式執行時讀取設定檔取得目前啟用的主題名稱，NVelocity 便會載入對應主題目錄內的模板；
切換模板的原理：修改設定指向不同主題資料夾，無需異動商業邏輯程式；
適合舊式 ASP.NET WebForm（aspx）專案實作前台頁面換膚功能。

aspx

在網站根目錄建立新的 Register.aspx 頁面，做為示範頁面。

在 Themes/default 目錄新增模板檔 register.htm，此檔為 NVelocity 模板，放置 HTML 與 Velocity 語法。

打開 Register.aspx，僅保留頁面指令，刪除所有其他 HTML 內容：

<%@ Page Language="C#" AutoEventWireup="true" CodeBehind="Register.aspx.cs" Inherits="NVelocityStudy.Web.Register" %>

aspx 不再負責頁面渲染，只做為進入點，由後端程式呼叫 NVelocity 載入 register.htm 模板並輸出內容。

網站根目錄
├─ Register.aspx          # 存取入口
├─ Register.aspx.cs       # 後端邏輯
└─ Themes
    └─ default
        └─ register.htm   # NVelocity模板頁面

接下來在 Register.aspx.cs 撰寫程式，指定載入目前主題底下的 register.htm、傳入資料模型，最後輸出 HTML。

切換主題時，只需要修改主題目錄指向，引擎就會載入對應資料夾內的 register.htm

aspx.cs

開啟後端程式檔 Register.aspx.cs，在 Page_Load 方法撰寫 NVelocity 渲染邏輯，頁面載入時執行模板解析與輸出。

using System;
using System.Collections.Generic;
using System.Web;
using System.Web.UI;
using System.Web.UI.WebControls;

namespace NVelocityStudy.Web
{
    public partial class Register : System.Web.UI.Page
    {
        protected void Page_Load(object sender, EventArgs e)
        {
            // 在此撰寫NVelocity載入模板、渲染頁面的程式碼
        }
    }
}

在Page_Load加入以下程式

protected void Page_Load(object sender, EventArgs e)
{
    //第一步 建立Velocity引擎實體 VelocityEngine
    VelocityEngine ve = new VelocityEngine();

    //第二步 初始化引擎設定
    ExtendedProperties pros = new ExtendedProperties();
    pros.AddProperty(RuntimeConstants.RESOURCE_LOADER, "file"); // 使用檔案模式載入模板
    pros.AddProperty(RuntimeConstants.FILE_RESOURCE_LOADER_PATH, Server.MapPath(@"")); // 模板根目錄
    ve.Init(pros); // 使用設定初始化引擎

    //第三步 讀取模板檔案
    Template template = ve.GetTemplate("themes/default/register.htm");

    //第四步 建立內容環境，傳入變數至模板
    IContext context = new VelocityContext();
    context.Put("websiteName", "FoxDevelop");
    context.Put("domainName", "foxdevelop.com");

    //第五步 合併模板與資料，產生HTML
    StringWriter writer = new StringWriter();
    template.Merge(context, writer); //渲染結果存入writer

    //第六步 輸出頁面
    Response.Write(writer.ToString().Replace("\r\n", "<br/>"));
}

這段程式會讀取HTML模板檔、建立變數，用來置換模板內的佔位符

1. 實體化 VelocityEngine 獨立引擎物件，與全域靜態 Velocity.Init() 不同，支援多組獨立設定。
2. 引擎初始化與設定

• RESOURCE_LOADER=file：指定使用本機檔案載入模板；
• FILE_RESOURCE_LOADER_PATH：設定模板搜尋根路徑；
• ve.Init(pros)：載入設定完成初始化。

3. 載入模板 GetTemplate() 依據設定的根路徑，讀取 themes/default/register.htm 模板檔。
4. VelocityContext 資料環境context.Put(鍵, 值)：將 C# 變數傳入模板，在htm內使用$websiteName、$domainName取值。
5. 模板 Merge 渲染template.Merge(環境, 輸出串流)，把變數填入模板，產生完整HTML字串；使用StringWriter接收渲染後文字。
6. Response 輸出 將最終HTML傳送給瀏覽器；Replace("\r\n","<br/>")：把原始換行符轉換為HTML換行標籤。

htm模板

修改主題目錄內的register.htm

<!DOCTYPE html PUBLIC "-//W3C//DTD XHTML 1.0 Transitional//EN" "http://www.w3.org/TR/xhtml1/DTD/xhtml1-transitional.dtd">
<html xmlns="http://www.w3.org/1999/xhtml">
<head>
    <title></title>
</head>
<body>
    網站：$websiteName <br />
    網域名稱：$domainName
</body>
</html>

上方兩個$xxxxxxx 就是Page_Load建立變數的佔位符，渲染過程會自動替換成對應內容。

1. 變數標記 $變數名稱 $websiteName、$domainName 屬於 NVelocity (VTL) 變數語法。程式內透過 context.Put("websiteName", "FoxDevelop") 指定值，渲染時引擎自動置換：

• $websiteName → FoxDevelop
• $domainName → foxdevelop.com

執行結果

網站：FoxDevelop
網域名稱：foxdevelop.com

NVelocity介紹