在日常的网站内容运营中，我们经常需要在安企CMS后台录入一些多行文本内容，例如文章的简介、产品的特色描述，或者自定义字段中的详细说明。这些内容通常以纯文本的形式输入，然而，当我们期望它们在前台网页上也能按照原有的段落和换行效果展示时，却发现它们往往挤成了一行，失去了原有的排版。

这并非安企CMS系统本身的问题，而是HTML网页渲染机制的特性。在HTML中，浏览器默认会将纯文本中的所有回车符（即换行符）都视为空格处理，并不会自动换行。只有当内容中包含 <p>（段落）或 <br/>（强制换行）这样的HTML标签时，浏览器才会根据标签的指示进行相应的换行或分段显示。

安企CMS的解决方案：强大的文本过滤器

为了让用户输入的纯文本内容在前台网页上也能完美呈现原始的换行效果，安企CMS提供了一套灵活且强大的模板过滤器机制。其中，linebreaks 和 linebreaksbr 这两个过滤器正是为解决纯文本换行问题而设计的利器。

这些过滤器能够智能地解析纯文本中的换行符，并将其自动转换为浏览器能够识别的HTML换行标签，从而完美地保留您在后台输入的原始排版。

深入了解 linebreaks 和 linebreaksbr

  1. linebreaksbr 过滤器：简单直接的换行 这个过滤器是最直接的解决方案，它会将纯文本内容中的每一个换行符（\n）都替换为HTML的 <br/> 标签。这意味着，无论您在后台敲了多少次回车，前台页面都会在相应位置显示一个强制换行。

    使用示例： 假设您在后台输入的内容是：

    第一行文字
第二行文字
第三行文字

    在前台模板中使用 linebreaksbr 过滤器，代码如下：

    {{ 你的纯文本变量|linebreaksbr|safe }}

    它将被渲染为：

    第一行文字<br/>
第二行文字<br/>
第三行文字

  2. linebreaks 过滤器：更智能的段落处理 相比于 linebreaksbr 的简单粗暴，linebreaks 过滤器则显得更加智能和符合语义。它会做两件事：

    • 将单个换行符（\n）转换为 <br/> 标签。
    • 将连续的两个或多个换行符（即空行分隔的段落）用 <p> 和 </p> 标签包裹起来，形成标准的HTML段落。

    使用示例： 假设您在后台输入的内容是：

    这是第一段。
这里是第一段的第二行。


这是第二段。

    在前台模板中使用 linebreaks 过滤器，代码如下：

    {{ 你的纯文本变量|linebreaks|safe }}

    它将被渲染为：

    <p>这是第一段。<br/>这里是第一段的第二行。</p>
<p>这是第二段。</p>

    您可以根据内容排版的具体需求，选择更适合的过滤器。如果内容多为短句或列表，linebreaksbr 可能更合适；如果内容是结构化的段落文章，linebreaks 则能提供更优的HTML语义。

为什么需要 |safe？

在使用 linebreaks 或 linebreaksbr 过滤器时，您会注意到它们后面都紧跟着一个 |safe 过滤器。这是非常关键的一步！

安企CMS的模板系统为了安全考虑，默认会对所有输出的变量进行HTML实体转义，以防止跨站脚本攻击（XSS）。这意味着，如果过滤器将 \n 转换为 <br/> 后没有 |safe，浏览器看到的将不是换行，而是直接显示 <br/> 这个文本字符串。

|safe 过滤器告诉模板引擎：“我知道这个变量输出的是HTML内容，请不要对其进行转义，直接按HTML解析显示。” 因此，当您使用 linebreaks 或 linebreaksbr 这类生成HTML标签的过滤器时，务必加上 |safe。

在哪些地方可以使用这些过滤器？

这些强大的文本过滤器可以应用在任何存储纯文本并需要保留换行效果的地方：

  • 文章详情（archiveDetail）的 Content 或 Description 字段： 
    
{% archiveDetail articleContent with name="Content" %}
<div class="article-body">
    {{ articleContent|linebreaks|safe }}
</div>
  • 分类详情（categoryDetail）的 Content 或 Description 字段： 
    
{% categoryDetail categoryDesc with name="Description" %}
<p class="category-description">
    {{ categoryDesc|linebreaksbr|safe }}
</p>
  • 单页面（pageDetail）的 Content 字段： 
    
{% pageDetail pageText with name="Content" %}
<div class="page-content">
    {{ pageText|linebreaks|safe }}
</div>
  • 内容模型自定义字段： 如果您在内容模型中定义了多行文本类型的自定义字段，例如 product_features，同样可以通过这种方式处理： 
    
{% archiveDetail features with name="product_features" %}
<div class="product-features">
    {{ features|linebreaksbr|safe }}
</div>

实战演练：让文章内容自动换行

假设您正在编辑一篇安企CMS的文章详情页模板（如 article/detail.html），并希望文章正文内容能按照后台输入的换行效果展示。

  1. 找到文章内容的输出位置，通常会是类似 {{ archive.Content }} 或者通过 archiveDetail 标签获取的内容。
  2. 应用 linebreaks 或 linebreaksbr 过滤器，并加上 |safe。

示例代码片段：

{# 获取当前文章的完整内容 #}
{% archiveDetail articleContent with name="Content" %}

<article class="main-article">
    <h1 class="article-title">{% archiveDetail with name="Title" %}</h1>
    <div class="article-meta">
        发布时间：<span>{% archiveDetail with name="CreatedTime" format="2006-01-02" %}</span>
        分类：<a href="{% categoryDetail with name='Link' %}">{% categoryDetail with name='Title' %}</a>
    </div>
    <div class="article-body">
        {# 使用 linebreaks 过滤器，将纯文本换行符转换为 HTML 段落和换行标签 #}
        {{ articleContent|linebreaks|safe }}
    </div>
</article>

通过以上步骤，您在安企CMS后台输入的纯文本内容，将能够自动、正确地在前台网页上实现换行和段落效果，极大提升了内容展示的灵活性和用户体验。

常见问题 (FAQ)

  1. Q: 什么时候应该用 linebreaks，什么时候用 linebreaksbr 呢？它们有什么区别？ A: 主要看您对排版的需求。linebreaksbr 更直接，它会将每个换行符（回车）都简单地转换为一个 <br/> 标签，适合处理列表、地址、诗歌或简短的描述等场景，保留原始的逐行显示。而 linebreaks 则更智能，它会将单个换行符转换为 <br/>，但会将由空行分隔的文本块识别为不同的段落，并用 <p> 标签包裹起来，更适合处理结构化的文章正文，提供更好的HTML语义。

  2. Q: 我已经使用了 linebreaksbr 过滤器，但是网页上显示出来的还是 <br/> 这个文本，并没有实际换行，这是怎么回事？ A: 出现这种情况，很可能是您忘记在过滤器后面加上 |safe 标签。安企CMS模板系统默认会对所有输出的变量进行HTML实体转义，以防止安全问题。所以，当 linebreaksbr 过滤器将换行符转换为 <br/> 后，如果没有 |safe 标签来明确告诉模板系统“