# 🎓 Nunjucks 模板引擎完全指南

# 📚 目录

什么是 Nunjucks？
基础语法
控制结构
过滤器
宏
包含和继承
实战示例
常见问题

# 🎯 什么是 Nunjucks？

Nunjucks 是一个强大的 JavaScript 模板引擎，它基于 Jinja2 的语法。它允许你使用简单的模板语法来生成 HTML、CSS、JavaScript 等文件。

# 💡 基础语法

# 1. 变量输出

{{ 变量名 }}

示例：

<h1>{{ title }}</h1>
<p>作者：{{ author }}</p>

# 2. 注释

{# 这是注释 #}

# 3. 转义

{{ 变量 | safe }}  {# 不转义 #}
{{ 变量 | escape }}  {# 转义（默认） #}

# 🎮 控制结构

# 1. if 条件

{% if 条件 %}
    内容
{% elif 其他条件 %}
    其他内容
{% else %}
    默认内容
{% endif %}

示例：

{% if user.isAdmin %}
    <div class="admin-panel">管理员面板</div>
{% elif user.isEditor %}
    <div class="editor-panel">编辑面板</div>
{% else %}
    <div class="user-panel">用户面板</div>
{% endif %}

# 2. for 循环

{% for 项目 in 列表 %}
    内容
{% endfor %}

示例：

<ul>
{% for post in posts %}
    <li>{{ post.title }}</li>
{% endfor %}
</ul>

# 🎨 过滤器

# 1. 常用过滤器

{{ 变量 | 过滤器 }}

常用过滤器：

length : 获取长度
default : 设置默认值
lower : 转小写
upper : 转大写
trim : 去除空格
striptags : 去除 HTML 标签

示例：

<p>文章数量：{{ posts | length }}</p>
<p>用户名：{{ user.name | default('匿名用户') }}</p>
<p>标题：{{ title | upper }}</p>

# 🎭 宏

# 1. 定义宏

{% macro 宏名称(参数1, 参数2) %}
    宏的内容
{% endmacro %}

# 2. 使用宏

{% import "宏文件.njk" as 宏名称 %}
{{ 宏名称.宏名称(参数1, 参数2) }}

示例：

{# 定义宏 #}
{% macro card(title, content) %}
    <div class="card">
        <h3>{{ title }}</h3>
        <p>{{ content }}</p>
    </div>
{% endmacro %}

{# 使用宏 #}
{{ card("标题", "内容") }}

# 🎪 包含和继承

# 1. 包含

{% include "文件路径.njk" %}

# 2. 继承

{# 基础模板 base.njk #}
<!DOCTYPE html>
<html>
<head>
    <title>`{% block title %}{% endblock %}`</title>
</head>
<body>
    `{% block content %}{% endblock %}`
</body>
</html>
`{# 子模板 page.njk #}`
`{% extends "base.njk" %}`

`{% block title %}页面标题{% endblock %}`

`{% block content %}`
    <h1>页面内容</h1>
`{% endblock %}`

# 🎯 实战示例

# 1. 文章列表页面

{% extends "base.njk" %}

{% block title %}文章列表{% endblock %}

{% block content %}
    <div class="posts">
        {% for post in posts %}
            <article class="post">
                <h2>{{ post.title }}</h2>
                <div class="meta">
                    <span>作者：{{ post.author }}</span>
                    <span>日期：{{ post.date | date("YYYY-MM-DD") }}</span>
                </div>
                <div class="content">
                    {{ post.content | safe }}
                </div>
                {% if post.tags %}
                    <div class="tags">
                        {% for tag in post.tags %}
                            <span class="tag">{{ tag }}</span>
                        {% endfor %}
                    </div>
                {% endif %}
            </article>
        {% endfor %}
    </div>
{% endblock %}

# 2. 导航栏组件

{% macro navigation(items) %}
    <nav class="main-nav">
        <ul>
            {% for item in items %}
                <li>
                    <a href="{{ item.url }}" {% if item.active %}class="active"{% endif %}>
                        `{{ item.title }}`
                    </a>
                </li>
            {% endfor %}
        </ul>
    </nav>
{% endmacro %}

# ❓ 常见问题

# 1. 变量未定义

{# 使用 default 过滤器设置默认值 #}
{{ user.name | default('匿名用户') }}

# 2. 条件判断

{# 检查变量是否存在 #}
{% if variable is defined %}
    {{ variable }}
{% endif %}

# 3. 循环索引

{% for item in items %}
    {{ loop.index }} {# 当前索引 #}
    {{ loop.first }} {# 是否第一个 #}
    {{ loop.last }} {# 是否最后一个 #}
{% endfor %}

# 🎉 小贴士

使用 和 可以输出原始 Nunjucks 语法
使用 {% set %} 可以设置变量
使用 {% do %} 可以执行 JavaScript 代码
使用 {% filter %} 可以应用多个过滤器

# 📝 总结

Nunjucks 是一个功能强大的模板引擎，通过以上教程，你应该能够：

理解基本的模板语法
使用控制结构
应用过滤器
创建和使用宏
实现模板继承
处理常见问题

记住，实践是最好的学习方式，建议你多写多练，逐步掌握这些语法！

nunjucks