Ръководство за Nunjucks

Какво ще изградите

Малка форма за контакт, рендирана на сървъра — поле с етикет, бутон за изпращане, нула 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 го добавете към пътя за include) и импортирайте каквото ви трябва.

Стъпка 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

Следващи стъпки

Теми — включително модела с бисквитки на Eleventy за SSR превключване на тема без трептене.
Помощници за предпочитания — език и размер на текста.
Каталог на компонентите — свойства, ARIA и клавиатура за всеки компонент.

Въпроси по пътя? Страницата за помощ е пълна с отговори — а ако някоя стъпка може да е по-ясна, кажете ни и с радост ще подобрим ръководството.