如何在AnQiCMS模板中为可能为空的变量设置一个默认的友好显示值？

在构建网站模板时，我们经常会遇到这样的情况：某个变量可能因为数据未录入、可选字段留空或特定业务逻辑而导致在模板中为空值。如果不对这些空变量进行处理，网站前端页面可能会出现空白区域、显示不友好的占位符甚至导致布局错乱，从而影响用户体验和网站的专业性。

幸运的是，AnQiCMS 为此提供了两种优雅且实用的方法，帮助我们在模板中为可能为空的变量设置一个默认的友好显示值，确保网站内容的完整性和美观性。

1. 使用 default 过滤器：简洁高效的首选方案

当您希望在变量为空时直接显示一个预设的文本或图片路径，default 过滤器是最直接、最简洁的选择。它能够检测变量是否为空（包括 nil、空字符串、false 等“假值”），如果为空，则输出您指定的默认值。

例如，您网站的联系方式信息，如果“联系电话”字段没有填写，前台可能就会显示一片空白。通过 default 过滤器，我们可以这样处理：

假设您已经通过 {% contact cellphone with name="Cellphone" %} 获取了联系电话并赋值给 cellphone 变量。

<span>联系电话：{{ cellphone|default:"暂无联系电话" }}</span>

如果 cellphone 变量有值（例如 “13888888888”），页面会显示 “联系电话：13888888888”。如果 cellphone 变量为空，页面则会显示 “联系电话：暂无联系电话”，避免了空白或不完整的信息。

再比如，文档通常会有缩略图，但如果某些文档没有上传缩略图，我们不希望页面出现图片缺失的图标。我们可以设置一个默认的图片路径：

<img src="{{ archiveThumb|default:"/public/static/images/default-thumb.png" }}" alt="文档缩略图"/>

这里 archiveThumb 变量可能来自于 {% archiveDetail archiveThumb with name="Thumb" %}。如果 archiveThumb 有效，则使用它；否则，就会加载 default-thumb.png 这张默认图片。

AnQiCMS 还提供了一个 default_if_none 过滤器。它与 default 类似，但只针对值为 nil 的情况生效，而不会处理空字符串或 false。在大多数需要提供友好默认值的情况下，default 过滤器足以满足需求。

2. 结合 if 标签进行条件判断：灵活定制的进阶方案

在某些场景下，仅仅替换一个默认文本可能不够，您可能需要根据变量是否存在，来渲染完全不同的 HTML 结构或执行更复杂的逻辑。这时，if 标签就派上用场了。

if 标签允许您在变量存在（非空）时执行一段代码块，而在变量不存在时执行另一段代码块，或者不执行任何操作。

例如，一个分类页面可能有一个 Banner 图，但并非所有分类都有。如果存在 Banner 图，我们希望显示一个 <img> 标签，如果不存在，则显示一段介绍文字或者一个默认的背景色块。

首先，获取分类 Banner 图的变量：

{% categoryDetail categoryBanner with name="Logo" %}

然后，在模板中使用 if 标签进行判断：

{% if categoryBanner %}
    <div class="category-banner">
        <img src="{{ categoryBanner }}" alt="分类Banner"/>
    </div>
{% else %}
    <div class="category-info">
        <h3>欢迎来到 {{ categoryTitle }} 页面</h3>
        <p>这里是分类的简介内容...</p>
    </div>
{% endif %}

通过这种方式，您可以根据实际情况，为变量的“有”与“无”设计出不同的展现形式，使页面更具动态性和友好性。

3. 进阶应用：处理包含 HTML 的内容

当您设置的默认值或变量本身可能包含 HTML 代码时，为了确保这些 HTML 代码能够被浏览器正确解析而不是作为纯文本显示，您需要使用 |safe 过滤器。AnQiCMS 模板引擎为了安全起见，默认会对所有输出内容进行 HTML 转义，以防止跨站脚本（XSS）攻击。|safe 过滤器明确告诉模板引擎，您确定这段内容是安全的，不需要进行转义。

例如，网站底部的版权信息可能包含 &copy; 等 HTML 实体或 <p> 标签。如果版权内容可能为空，并且您想提供一个包含 HTML 标签的默认值：

{% system siteCopyright with name="SiteCopyright" %}
<div class="footer-copyright">
    {{ siteCopyright|default:"&copy; AnQiCMS 版权所有. 保留所有权利."|safe }}
</div>

在这里，|safe 确保了 &copy; 等能被正确解析为版权符号，而不是原样输出。同理，如果 siteCopyright 变量本身包含了 <a> 链接或其他 HTML 结构，|safe 也是必不可少的。

通过灵活运用 default 过滤器和 if 标签，结合 |safe 过滤器处理 HTML 内容，您可以在 AnQiCMS 模板中轻松应对变量为空的情况，从而构建出更加健壮、用户体验更佳的网站。

常见问题 (FAQ)

Q1: default 和 default_if_none 过滤器有什么区别？

A1: default 过滤器在变量为 nil、空字符串 ""、布尔值 false 或数字 0 等任何“假值”时都会应用默认值。而 default_if_none 过滤器则更为严格，它只会在变量的值为 nil（即未定义或数据库中为 NULL）时才应用默认值，而不会对空字符串或 false 等其他假值进行处理。在大多数情况下，使用 default 过滤器会更通用和方便。

Q2: 为什么有时候我需要在默认值后面加上 |safe？

A2: AnQiCMS 模板引擎为了网站安全，默认会对所有输出的变量内容进行 HTML 转义，将 < 转换为 &lt;，> 转换为 &gt; 等，以防止恶意脚本注入（XSS攻击）。如果您设置的默认值或变量本身包含合法的 HTML 代码（例如 <p>这是一个段落</p>），并且希望这些 HTML 代码能够被浏览器解析并呈现，而不是作为纯文本显示，那么就需要使用 |safe 过滤器来告诉模板引擎这段内容是安全的，无需转义。

Q3: 我可以为列表或数组类型的变量设置默认值吗？例如，当一个图片列表为空时显示一个默认图片？

A3: 可以的。default 过滤器同样适用于列表或数组。如果一个列表或数组变量为空（即长度为0），default 过滤器会直接输出您为其设置的默认值。不过需要注意的是，如果默认值您仍希望是一个列表或数组结构，您可能需要结合 if 标签进行判断，或者将默认值设置为一个包含默认元素的数组字符串并配合 |list 过滤器处理。但对于显示单一默认图片这样的场景，直接使用 {{ item.Images|first|default:"/public/static/images/placeholder.png" }} 或在 if item.Images 逻辑中处理会更常见。