`add`过滤器在`languages`标签返回的多语言站点链接中，如何动态添加语言参数？

在 AnQiCMS 灵活的多语言支持下，为全球用户提供内容已经变得非常便捷。系统内置的 languages 标签能够轻松列出您网站支持的所有语言版本及其对应的链接。然而，在某些场景下，我们可能不仅希望提供语言切换功能，还需要在这些多语言链接中动态地添加额外的参数，例如用于营销追踪、A/B 测试，或是加载特定语言的个性化内容。这时，AnQiCMS 强大的模板过滤器，特别是 add 过滤器，就能派上大用场。

理解 AnQiCMS 的多语言链接基础

首先，让我们回顾一下 languages 标签的基本用法。这个标签主要用于获取您网站配置的所有语言版本信息，它会返回一个包含 item 对象的数组，每个 item 都代表一个语言站点，并提供如 Link（语言站点的完整 URL）、LanguageName（语言名称）、Language（语言代码）等信息。

以下是一个典型的 languages 标签用法示例，用于在页面上展示语言切换选项：

{%- languages websites %}
{%- if websites %}
<div>
    <span>切换语言：</span>
    {%- for item in websites %}
    <a href="{{item.Link}}">
        {%- if item.LanguageIcon %}
        <img src="{{item.LanguageIcon}}" alt="{{item.LanguageName}}图标" />
        {%- else %}
        {{item.LanguageEmoji}}
        {% endif %}
        {{item.LanguageName}}
    </a>
    {%- endfor %}
</div>
{%- endif %}
{%- endLanguages %}

这段代码会遍历所有已配置的语言站点，并为每个站点生成一个包含其标准链接的 <a> 标签。

动态添加语言参数：’add’ 过滤器的妙用

现在，假设我们有一个需求：在用户切换语言时，除了跳转到对应的语言页面外，我们还想在 URL 中追加一个 ?source=language_switcher 的参数，以便追踪用户是通过语言切换器进行跳转的。或者，我们希望在链接中明确带上语言代码，例如 ?lang=en 或 ?lang=zh-cn。

这时，add 过滤器就显得尤为重要了。add 过滤器如同其名，主要用于将两个值“相加”。在字符串语境下，它会将两个字符串拼接起来。

例如，{{ "Hello "|add:"World!" }} 会输出 Hello World!。

要将语言参数动态添加到 item.Link 中，我们可以将 item.Link 作为第一个操作数，将要添加的参数字符串作为第二个操作数，通过 add 过滤器进行拼接。

示例一：添加固定的追踪参数

如果您想为所有语言切换链接添加一个固定的追踪参数，可以这样做：

{%- languages websites %}
{%- if websites %}
<div>
    <span>切换语言：</span>
    {%- for item in websites %}
    <a href="{{ item.Link|add:"?source=language_switcher" }}">
        {%- if item.LanguageIcon %}
        <img src="{{item.LanguageIcon}}" alt="{{item.LanguageName}}图标" />
        {%- else %}
        {{item.LanguageEmoji}}
        {% endif %}
        {{item.LanguageName}}
    </a>
    {%- endfor %}
</div>
{%- endif %}
{%- endLanguages %}

在上面的例子中，item.Link|add:"?source=language_switcher" 将每个语言站点的原始链接与其后的追踪参数字符串拼接起来。

示例二：添加动态的语言代码参数

如果您希望链接中包含当前语言代码，例如 ?lang=zh-cn 或 ?lang=en，那么我们需要将参数名与 item.Language（当前语言的代码）进行拼接。这可以通过链式使用 add 过滤器实现：

{%- languages websites %}
{%- if websites %}
<div>
    <span>切换语言：</span>
    {%- for item in websites %}
    <a href="{{ item.Link|add:"?lang="|add:item.Language }}">
        {%- if item.LanguageIcon %}
        <img src="{{item.LanguageIcon}}" alt="{{item.LanguageName}}图标" />
        {%- else %}
        {{item.LanguageEmoji}}
        {% endif %}
        {{item.LanguageName}}
    </a>
    {%- endfor %}
</div>
{%- endif %}
{%- endLanguages %}

这里，我们首先将 item.Link 与 "?lang=" 拼接，然后将结果再与 item.Language（例如 “en”、”zh-cn”）拼接，最终形成如 https://example.com/en/?lang=en 这样的动态链接。

结合实际场景的更多应用

这种动态添加参数的能力在许多场景中都非常实用：

  • A/B 测试： 您可以通过 |add:"?test_variant=A" 或 |add:"?test_variant=B" 来区分不同语言版本的测试组。
  • 个性化内容加载： 如果您的前端逻辑需要根据 URL 参数加载特定组件或内容，这种方式能提供很大的灵活性。
  • 特定区域或渠道营销： 为从特定渠道（如社交媒体、邮件营销）进入的语言页面添加识别参数，有助于更精细地分析流量来源和用户行为。

在使用 add 过滤器拼接 URL 参数时，您需要注意 URL 编码和现有参数的问题。如果 item.Link 可能已经包含问号 (?) 和其他参数，直接使用 ? 会导致 URL 格式错误。在这种情况下，您需要一个更复杂的逻辑来判断是使用 ? 还是 &。AnQiCMS 的模板引擎也提供了判断和条件语句，例如 if 标签和 contain 过滤器，可以帮助您构建更健壮的 URL。但对于大多数简单直接的参数添加需求，add 过滤器足以快速高效地实现您的目的。

通过灵活运用 languages 标签和 add 过滤器，您可以为多语言网站提供更丰富、更智能的用户体验，并更好地满足营销和数据分析的需求。

常见问题 (FAQ)

  1. 问：为什么我需要动态添加语言参数，而不是直接使用 item.Link？ 答：item.Link 通常提供的是语言站点的基础 URL，不包含额外的动态信息。动态添加参数可以帮助您实现多种高级功能，例如：

    • 流量追踪与分析： 标记用户是通过哪个语言切换器或特定入口进入的，方便营销归因。
    • A/B 测试： 在不同语言版本上同时测试不同的设计或内容变体，通过 URL 参数来区分测试组。
    • 个性化内容： 指示前端脚本加载特定参数对应的个性化内容或功能。
    • SEO 优化： 配合某些工具要求在 URL 中明确显示语言代码。

  2. 问：如果 item.Link 已经包含问号（?）等参数，我直接使用 |add:"?param=value" 会有什么问题？ 答：直接使用 |add:"?param=value" 会导致 URL 中出现两个问号（例如 https://example.com/en/?key=val?param=value），这会破坏 URL 的结构，可能导致页面无法正确加载或参数无法解析。 推荐做法是： 在添加参数前，先判断 item.Link 中是否已经存在问号。如果存在，则使用 & 连接新参数；如果不存在，则使用 ? 连接。这通常需要更复杂的模板逻辑，例如结合 if 标签和 contain 过滤器来构建 URL。一个简化的示例如下：

    {% set separator = "?" %}
{% if item.Link|contain:"?" %}{% set separator = "&" %}{% endif %}
<a href="{{ item.Link|add:separator|add:"param=value" }}">...</a>

  3. 问：我可以在 add 过滤器中添加多个参数吗？ 答：可以。您可以通过链式调用 add 过滤器来添加多个参数。请确保后续参数使用 & 符号连接，而第一个参数根据上面提到的规则使用 ? 或 &。 例如： “`twig {% set separator = “?” %} {% if item.