`linebreaks`过滤器在`{% filter %}{% endfilter %}`块中如何正确使用？

在安企CMS的模板开发中，我们常常需要将后台录入的纯文本内容，如文章简介、产品详情中的多行说明，或者用户留言等，以更符合网页阅读习惯的方式展示出来。直接输出这些纯文本，页面上会发现原有的换行符丢失，所有内容挤成一团，严重影响可读性。这时，linebreaks 过滤器就成了解决这个问题的得力助手，它能巧妙地将纯文本中的换行符转换为标准的HTML段落和换行标签。

什么是 linebreaks 过滤器？

简单来说，linebreaks 过滤器是一个文本处理工具，它的核心作用是将纯文本中的回车换行符（\n）智能地转换为HTML的段落标签（<p>）和换行标签（<br/>）。

具体工作原理是：

1. 如果文本中连续出现一个或多个空行（即两个或更多个换行符），linebreaks 会将它们之间的文本块用 <p>...</p> 标签包裹起来，形成独立的段落。
2. 如果文本中只出现单个换行符（即行内换行），它会将其转换为 <br/> 标签，实现行内强制换行。

这样一来，你在后台文本框里输入的自然分段和换行，到了前端页面就能得到美观的呈现，大大提升了内容的阅读体验。

为什么在 {% filter %}{% endfilter %} 块中使用 linebreaks？

在安企CMS的模板引擎中，过滤器不仅可以作用于单个变量（例如 {{ variable | linebreaks }}），还可以作用于一个包含多行内容或复杂结构的“块”。这正是 {% filter %}{% endfilter %} 块发挥作用的场景。

当你需要对一段非单一变量的文本内容进行统一的 linebreaks 处理时，比如这段内容可能混合了静态文本、多个动态变量，甚至是其他标签的输出，使用 {% filter %}{% endfilter %} 块就显得非常方便和强大。它允许你将任何希望被过滤器处理的内容都包裹在这个块中，然后统一应用过滤器。

举个例子： 假设你有一个页面的底部声明，其中包含版权信息和一些多行的联系方式。这些内容可能部分是固定文本，部分来自系统设置的变量。你希望它们都能保持后台编辑时的换行和分段效果，这时就可以将整个声明部分放入 {% filter linebreaks %}{% endfilter %} 块中。

如何正确使用 linebreaks 块级过滤器

使用 linebreaks 块级过滤器的基本语法是：

{% filter linebreaks %}
    你的多行纯文本内容，
    可以是静态文本，
    也可以包含 {{ 变量名称 }}，
    甚至可以是其他标签的输出。

    这里是另一个段落。
{% endfilter %}

然而，这里有一个非常重要的细节需要注意：安企CMS的模板引擎默认会对所有输出的HTML内容进行自动转义，以防止跨站脚本攻击（XSS）。这意味着，如果 linebreaks 过滤器生成了 <p> 和 <br/> 标签，而你没有进行额外处理，这些标签在页面上会以纯文本形式显示（例如，你会看到 <p> 而不是真正的段落）。

为了让 linebreaks 生成的HTML标签能够被浏览器正确解析和渲染，你需要配合使用 safe 过滤器。safe 过滤器会告诉模板引擎，这段内容是安全的，不需要进行HTML转义。

因此，正确且推荐的使用方式是：

{% filter linebreaks | safe %}
    {# 假设 `system.SiteCopyright` 是从后台获取的多行版权信息 #}
    {{ system.SiteCopyright }}

    这是一段额外的静态多行说明。
    它可以是任何你想要格式化的纯文本。
    比如一个地址：
    北京市海淀区中关村大街1号
    安企CMS大厦10层
{% endfilter %}

与 linebreaksbr 的区别： 安企CMS还提供了 linebreaksbr 过滤器。它与 linebreaks 类似，但更简单：它仅仅将所有的换行符 \n 转换为 <br/> 标签，而不会像 linebreaks 那样用 <p> 标签来创建段落。如果你只需要简单的行内换行，而不需要严格的段落结构，那么 linebreaksbr 可能是更合适的选择。

实际应用场景：

1. 文章/产品简介： 如果你的文章或产品简介允许后台输入多行文本，并希望在前端展示时保持分段，linebreaks | safe 是理想选择。
2. 自定义多行文本字段： 比如你在内容模型中定义了一个“产品特色”的多行文本字段，希望每点特色能单独成行或成段。
3. 页脚版权或联系信息： 网站页脚通常包含多行版权声明、地址等，使用 linebreaks | safe 可以保持排版整洁。
4. 站点关闭提示： 在后台设置的“闭站提示”内容，如果需要多行展示，也同样适用。

通过灵活运用 linebreaks 块级过滤器，你可以让安企CMS网站中的纯文本内容以更专业、更易读的方式呈现在用户面前，极大提升用户体验和内容展示效果。

FAQ

Q1: 为什么我使用了 {% filter linebreaks %} 过滤器，但页面上看到的还是纯文本，没有变成段落和换行？ A1: 这很可能是因为你没有在 linebreaks 过滤器之后添加 | safe 过滤器。安企CMS模板引擎默认会将所有HTML内容进行转义以确保安全。linebreaks 过滤器虽然生成了 <p> 和 <br/> 标签，但如果它们没有被 | safe 标记为“安全”，模板引擎就会将其转义显示为 <p> 和 <br/>。正确的用法应该是 {% filter linebreaks | safe %}。

Q2: linebreaks 和 linebreaksbr 过滤器有什么区别？我该如何根据需求选择？ A2: 它们的主要区别在于对空行的处理方式。

• linebreaks 过滤器会将连续的空行视为段落分隔符，将空行之间的文本块用 <p>...</p> 标签包裹，并将文本块内部的单个换行符转换为 <br/>。它适用于需要结构化段落的场景。
• linebreaksbr 过滤器则更简单粗暴，它仅仅将文本中所有的换行符 \n 都替换为 <br/> 标签，不会生成 <p> 标签。如果你只是想让每行文字简单地强制换行，而不需要严格的HTML段落结构，那么 linebreaksbr 更为合适。选择哪一个取决于你希望内容在前端呈现的精确HTML结构。

Q3: {% filter %}{% endfilter %} 块可以嵌套使用吗？如果嵌套了，过滤器的作用顺序是怎样的？ A3: {% filter %}{% endfilter %} 块可以嵌套使用。当存在嵌套时，过滤器会从最内层向最外层依次应用。这意味着最内层 filter 块中的内容会首先被其指定的过滤器处理，然后其输出结果会作为外层 filter 块的输入，再被外层过滤器处理，依此类推。如果你在内层过滤器处理后希望输出HTML，并将其传递给外层过滤器或直接显示，别忘了在内层过滤器链的末尾使用 | safe，否则内层生成的HTML可能会被