在 AnQiCMS 模板中，如何让多行文本的换行符自动显示为 HTML <br/> 标签？

在网站内容运营中，我们经常会遇到需要展示多行文本的情况，比如文章简介、产品描述或者用户留言等。这些文本内容在后台编辑时，通常通过按下回车键来创建换行。然而，当这些包含换行符（通常是 \n）的文本直接输出到 HTML 页面时，浏览器并不会将其解析为视觉上的换行。相反，HTML 默认会将多个空格和换行符折叠成一个空格，导致原本分行的内容显示成一长串文字。

为了解决这个问题，我们需要将文本中不可见的换行符 \n 转换成浏览器能够识别的 HTML 换行标签 <br/>。AnQiCMS 强大的模板引擎提供了简单而高效的“过滤器”功能，可以帮助我们轻松实现这一转换。

认识 AnQiCMS 模板中的文本处理过滤器

AnQiCMS 的模板引擎借鉴了 Django 模板语法，提供了多种内置过滤器来处理和格式化输出内容。对于多行文本的换行需求，主要有两个非常实用的过滤器：linebreaksbr 和 linebreaks。

  1. linebreaksbr 过滤器 这个过滤器就像它的名字一样直观，它会把文本中的每个换行符 \n 直接替换成 <br/> 标签。这非常适合那些只需要简单地将每一行文本分行显示，而不需要额外的段落格式的场景。它的效果类似于 PHP 中的 nl2br 函数。

  2. linebreaks 过滤器 linebreaks 过滤器则提供了更智能的段落处理方式。它会将单个换行符 \n 转换为 <br/>，但如果遇到连续的两个换行符 \n\n（通常表示一个空行），它会将其转换为 <p>...</p> 段落标签，并用 <br/> 来处理段落内的单行换行。这更适合需要将多行文本内容格式化成 HTML 段落的场景。

如何在 AnQiCMS 模板中应用这些过滤器？

使用这些过滤器非常简单，只需要在需要处理的变量后面加上 |过滤器名称 即可。

假设我们有一个从后台获取的文档描述字段 archive.Description，它包含了多行文本：

后台输入的内容示例：

这是第一行文本。
这是第二行文本。

这是第三行文本，前面有一个空行。
第四行。

1. 使用 linebreaksbr 过滤器实现简单换行

如果你希望内容简单地按行显示，每行一个 <br/> 标签，就可以使用 linebreaksbr：

<div class="description-content">
    {{ archive.Description|linebreaksbr|safe }}
</div>

输出的 HTML 结果会是：

<div class="description-content">
    这是第一行文本。<br/>
    这是第二行文本。<br/>
    <br/>
    这是第三行文本，前面有一个空行。<br/>
    第四行。
</div>

2. 使用 linebreaks 过滤器实现段落格式化

如果你希望内容按照段落形式组织，空行分隔的文本变成独立的 <p> 标签，段落内的换行变成 <br/>，那么 linebreaks 过滤器是更好的选择：

<div class="description-content">
    {{ archive.Description|linebreaks|safe }}
</div>

输出的 HTML 结果会是：

<div class="description-content">
    <p>这是第一行文本。<br/>
    这是第二行文本。</p>
    <p>这是第三行文本，前面有一个空行。<br/>
    第四行。</p>
</div>

3. 重要的 |safe 过滤器：避免 HTML 标签被转义

在使用 linebreaksbr 或 linebreaks 过滤器之后，它们会生成 HTML 标签（如 <br/> 或 <p>）。AnQiCMS 的模板引擎为了防止跨站脚本攻击（XSS），默认会对所有输出内容进行 HTML 实体编码。这意味着你可能会看到页面上直接显示 <br/> 这样的字符串，而不是实际的换行。

为了确保生成的 HTML 标签能够被浏览器正确解析，我们需要在 linebreaksbr 或 linebreaks 过滤器之后，再追加一个 |safe 过滤器。safe 过滤器会告诉模板引擎，这部分内容是安全的，不需要进行 HTML 实体编码，可以直接输出。

正确的用法始终是：{{ 变量|过滤器|safe }}。

错误示例（不使用 |safe）：

{{ archive.Description|linebreaksbr }}

可能输出的页面内容（注意 <br/> 会被当成普通文本显示）：

这是第一行文本。&lt;br/&gt;
这是第二行文本。&lt;br/&gt;

正确示例：

{{ archive.Description|linebreaksbr|safe }}

实际在浏览器中会看到的：

这是第一行文本。
这是第二行文本。

总结

无论是需要简单的行内换行，还是希望将文本智能地格式化为 HTML 段落，AnQiCMS 提供的 linebreaksbr 和 linebreaks 过滤器都能满足你的需求。记住，在使用这些过滤器将纯文本转换为 HTML 标签后，务必添加 |safe 过滤器，以确保浏览器能够正确解析并渲染这些标签，从而让你的多行文本内容在前端页面上美观、清晰地呈现出来。

常见问题 (FAQ)

1. 为什么我使用了 linebreaksbr 过滤器，但页面上显示的是 <br/> 文本而不是实际的换行？

这很可能是因为你忘记在过滤器链的最后添加 |safe 过滤器。AnQiCMS 模板引擎默认会对所有输出内容进行 HTML 实体编码，以防止安全问题。当你使用 linebreaksbr 或 linebreaks 过滤器生成了 <br/> 或 <p> 等 HTML 标签后，如果不安 |safe 标记为“安全内容”，这些标签就会被编码成 &lt;br/&gt; 或 &lt;p&gt;，然后在页面上以普通文本的形式显示出来。确保你的代码是 {{ 变量|linebreaksbr|safe }}。

2. linebreaks 和 linebreaksbr 过滤器有什么区别？我该如何选择？

它们的主要区别在于对空行的处理方式。

  • linebreaksbr：将每个单独的换行符 \n 直接转换为 <br/> 标签。它不会自动创建段落 <p> 标签。如果你只是想简单地让每一行文本都独立显示，没有段落的概念，或者你的文本已经包裹在其他块级元素中（如 <li>），那么 linebreaksbr 是更合适的选择。
  • linebreaks：将单个换行符 \n 转换为 <br/> 标签，但会将连续的两个换行符 \n\n（表示一个空行）转换为 HTML 的段落标签 <p>...</p>。这使得文本看起来更像结构化的段落。如果你希望文本能自动形成段落，并且段落内部的换行也能被保留，那么 linebreaks 更为适用。

选择哪个过滤器取决于你希望内容最终呈现的结构和样式。

3. 这个方法适用于所有多行文本字段吗？比如自定义字段？

是的，这个方法适用于 AnQiCMS 中的任何存储了多行文本内容的变量，无论是系统内置的 archive.Description、category.Content，还是你在内容模型中自定义的文本域（textarea）字段。只要该变量的值是包含 \n 换行符的纯文本，你就可以使用 linebreaksbr|safe 或 linebreaks|safe 过滤器来将其转换为 HTML 换行。