django-querystring-tag

此小巧的包添加了{% querystring %}标签：一个强大、经过良好测试的模板标签，用于修改和渲染安全的、适当编码的查询字符串值。

这是一种创建分页链接、筛选器和其他状态保留链接的干净简单方法，而不会使您的视图代码变得混乱！

安装

1. 从pypi安装包

   使用Poetry

   $ poetry add django-querystring-tag
   

   使用pip

   $ pip install django-querystring-tag
   

2. 将“querystring_tag”添加到您的Django项目设置中的INSTALLED_APPS列表中。

将querystring_tag添加到内置功能（可选）

要自由使用{% querystring %}标签，而无需将{% load querystring_tag %}添加到所有模板中，您可以将"querystring_tag.templatetags.querystring_tag"添加到您选择的模板后端的['OPTIONS']['builtins']列表中。这里是一个示例。

如何使用

首先，将标签加载到您想使用的模板中

{% load querystring_tag %}

然后，您可以使用该标签如下所示

{% querystring param_one='value' param_two+='add-to-existing' param_three-="remove-from-existing" %}

基础用法

1. 标签默认使用 request.GET 作为数据源。如果您有其他想法，请查看 source_data 选项。
2. 下面的示例故意很简单：您可以在同一个标签中进行您需要的任何修改。尽情发挥吧！
3. 您可能会想：“我想在一个包含模板中使用它，参数名是动态的。这会工作吗？”是的，它会！我知道这很罕见，但您也可以为参数名使用模板变量。
4. 您不想在链接中保留Google跟踪参数，对吧？我想不是。默认情况下，以 utm_ 开头的任何参数都会被移除。如果您想保留它们，请添加 remove_utm=False。
5. 您可能也不想在链接中保留空白参数，对吧？看，我已经读懂了您的想法！默认情况下也会移除空白值。如果您想保留它们，请添加 remove_blank=False。
6. 想要将返回值变量化而不是渲染它？那就试试“as”选项。它就像您预期的那样工作。

使用 = 来设置或替换一个参数

最常见的需求是完全替换特定参数的值。这通过使用常规关键字参数来实现，在参数名和值之间使用 = 操作符。例如，如果您的查询字符串看起来像这样

?q=test&baz=1

您想添加一个值为 bar 的 foo 变量

{% querystring foo="bar" %}

这将产生以下输出

?q=test&baz=1&foo=bar

使用 -= 来从一个多值参数中移除值

当处理多值参数时，您可能会发现自己需要 移除 特定值，而不影响其他任何值。

在这些情况下，您可以使用 -= 操作符而不是常规的 =。例如，如果当前的查询字符串看起来像这样

?q=test&bar=1&bar=2&bar=3

并且您想移除 &bar=2，您的查询字符串标签可能看起来像这样

{% querystring bar-=2 %}

这将产生以下输出

?q=test&bar=1&bar=3

如果指定的值不存在，该指令将被简单地忽略。

使用 += 来向一个多值参数添加值

当处理多值参数时，您可能会发现自己需要 添加 参数的特定值，而不影响其他任何值。

在这些情况下，您可以使用 += 操作符而不是常规的 =。例如，如果当前的查询字符串看起来像这样

?q=test&bar=1&bar=2&bar=3

并且您想添加 &bar=4，您的查询字符串标签可能看起来像这样

{% querystring bar+=4 %}

这将产生以下输出

?q=test&bar=1&bar=2&bar=3&bar=4

如果指定的值已经存在，该指令将被简单地忽略。

使用 only 来指定您想要保留的参数

当您只想让查询字符串包含特定参数的值时，请在 {% querystring %} 标签的开始处使用 only。

例如，假设当前的查询字符串看起来像这样

?q=keywords&group=articles&category=2&published_after=2022-01-01

并且您只想在链接中包含 q 和 group 参数。您可以这样做

{% querystring only 'q' 'group' %}

这将产生以下输出

?q=keywords&group=articles

您也可以将 only 与任何数量的修改结合起来。只需确保将 only 关键字和相关的参数名作为最左边的参数，如下所示

{% querystring only 'q' group="group_value" clear_session="true" %}

使用 discard 来指定您想要丢失的参数

当您想从查询字符串中排除特定参数时，请在 {% querystring %} 标签的开始处使用 discard。

例如，假设当前的查询字符串看起来像这样

?q=keywords&group=articles&category=2&published_after=2022-01-01

并且您想保留除了 group 和 published_after 之外的所有内容。您可以这样做

{% querystring discard 'group' 'published_after' %}

这将产生以下输出

?q=keywords&group=articles

您也可以将 discard 与任何数量的修改结合起来。只需确保将 discard 关键字和相关的参数名作为最左边的参数，如下所示

{% querystring discard 'published_after' group="group_value" clear_session="true" %}

使用模板变量作为参数名

与许多自定义模板标签不同，{% querystring %} 支持在键和值中使用模板变量。例如，如果该标签被用于生成分页链接，并且 page_param_name 和 page_num 是模板中可用的变量，您可以使用它们如下

{% querystring page_param_name=page_num %}

支持的价值类型

值可以是字符串、布尔值、整数、日期、日期时间、Django 模型实例或这些值的可迭代对象。

当遇到 Django 模型实例时，{% querystring %} 将自动从其中提取 pk 值，并使用该值来修改查询字符串。要使用不同的字段值，可以使用标签的 model_value_field 选项（详细信息请参阅下方）。或者，您可以在模型类中添加一个 querystring_value_field 属性。例如

class Category(models.Model):
    name = models.CharField(max_length=50)
    slug = models.SlugField(max_length=50, unique=True)

    # use 'slug' values in querystrings
    querystring_value_field = "slug"

指定多个值

如上所述，您可以通过提供一个可迭代对象作为值来一次性指定参数的多个值。这可以是原生的 Python 类型，如 list、tuple 或 set，也可以是实现 __iter__ 方法以支持迭代的任何东西，例如 QuerySet。

例如，如果上下文中包含一个变量 tag_list，它是一个字符串列表（['tag1', 'tag2', 'tag3']），您可以通过引用列表值来包含所有这些值。例如

{% querystring tags=tag_list %}

上述输出的结果将是

"?tags=tag1&tags=tag2&tags=tag3"

选项参考

source_data

支持的价值类型: QueryDict、dict、str

默认值: request.GET

默认情况下，该标签使用 request.GET 作为查询字符串的数据源，但可以使用 source_data 关键字参数来指定使用替代的 QueryDict、dict 或字符串值。

例如，如果您正在使用 Django 表单验证查询数据，并且只想包括有效数据，您可以使用表单的 cleaned_data 来生成查询字符串。

{% querystring source_data=form.cleaned_data page=2 %}

remove_blank

支持的价值类型: bool

默认值: True

默认情况下，任何值为 None 或 ""（空字符串）的参数值都将从查询字符串中删除。

要保留空值，请在 {% querystring %} 标签中包含 remove_blank=False。

remove_utm

支持的价值类型: bool

默认值: True

默认情况下，以 "utm_" 开头的参数名称（用于 Google Analytics 跟踪参数的格式）将被排除在生成的查询字符串之外，因为您不太可能在链接到其他页面的链接中重复使用这些参数。

要保留这些参数，请在 {% querystring %} 标签中包含 remove_utm=False。

model_value_field

支持的价值类型: str

默认值: "pk"

默认情况下，当遇到作为值的 Django 模型实例时，{% querystring %} 将从实例中提取 pk 值，并在查询字符串中使用它。如果您想使用不同的字段值，可以使用 model_value_field 选项来指定替代字段。

例如，如果模型有一个 slug 字段，您正在使用它作为公共标识符，您可以在查询字符串中指定使用 slug 值，如下所示

{% querystring tags=tag_queryset model_field_value='slug' %}

在本地测试代码

如果您安装了最新的 Python 3 版本，您可以使用简单的 virtualenv 在本地运行测试。在克隆存储库后，将您的计算机上的项目根目录导航到项目根目录，然后运行以下命令

设置 virtualenv

$ virtualenv venv
$ source venv/bin/activate
$ pip install -e '.[test]' -U

运行测试

$ pytest

完成后

$ deactivate