Nunjucks 教學
為 Eleventy、Express 或者任何 Node 範本流程而設嘅伺服器端渲染巨集 — GOV.UK 風格嘅做法,配合 Lily 嘅目錄同類別掛鉤。
你會建立啲乜
一個細細個嘅伺服器渲染聯絡表單 — 有標籤嘅輸入欄、提交按鈕、零 JavaScript 負載 — 先裸奔,再加樣式,大約 10 分鐘。
開始之前
你需要 git、Node 22 或以上,同 pnpm 10 或以上。任何 Nunjucks 流程都得 — Eleventy、Express 或者純 Nunjucks。
步驟 1 — 攞到程式碼
git clone https://github.com/LilyDesignSystem/lily-design-system
cd lily-design-system/lily-design-system-nunjucks-headless
pnpm install
pnpm test # vitest rendering every macro
每個元件都係一個目錄,位於 components/ 附有
macro.njk、佢嘅測試同文件 — 例如
components/button/macro.njk。將你嘅 Nunjucks 載入器指向
components/ (喺 Eleventy 入面,加入 includes 路徑),然後匯入你需要嘅。
步驟 2 — 你第一個元件
{% from "components/button/macro.njk" import button %}
{{ button({ text: "Save", type: "submit" }) }}
渲染成 <button class="button" type="submit">Save</button>。巨集接受單一 params 物件: text (已跳脫)或者
html (原始), type, label 用於
aria-label,同一個類別掛鉤附加器。
步驟 3 — 組合一個細表單
{% from "components/form/macro.njk" import form %}
{% from "components/label/macro.njk" import label %}
{% from "components/text-input/macro.njk" import textInput %}
{% from "components/button/macro.njk" import button %}
<form class="form" method="post">
<div class="field">
{{ label({ for: "name", text: "Full name" }) }}
{{ textInput({ id: "name", name: "name", required: true }) }}
</div>
{{ button({ text: "Save", type: "submit" }) }}
</form>因為所有嘢都喺伺服器渲染,瀏覽器收到嘅係帶類別掛鉤嘅純語義化 HTML — 零位元組嘅 JavaScript 負載。
檢查你嘅成果: 載入頁面,表單睇落好簡單 — 正如預期:樣式仲喺前面。按 Tab:焦點會移過每個控制項,標籤會被讀出,提交都運作。行為已經完成;外觀屬於你,而且係下一步。
步驟 4 — 加樣式
為掛鉤加樣式 — .button, .text-input,
.label, .field — 喺你嘅樣式表,或者喺你嘅基礎版面連結現成主題:
<link rel="stylesheet" href="/themes/united-kingdom-government-digital-service.css" />步驟 5 — 睇晒佢運作
Nunjucks + Eleventy 範例應用程式 將完整目錄建置成靜態網站,每個元件都有示範頁面:
git clone https://github.com/LilyDesignSystem/lily-design-system
cd lily-design-system/lily-design-system-nunjucks-eleventy-examples
pnpm install && pnpm run dev