Django Spurl 使用与技术文档

1. 安装指南

要使用 Django Spurl，您可以通过两种方式安装：

• 使用 pip 安装：

  pip install django-spurl
  

• 从 GitHub 检出 spurl：

确保将 spurl 添加到您的 INSTALLED_APPS 设置中：

INSTALLED_APPS = (
    ...
    'spurl',
)

在模板中使用 Spurl 前，需要在模板中加载它的模板库：

{% load spurl %}

2. 项目使用说明

Spurl 是一个 Django 模板库，用于操作 URLs。它不是 Django 内置的 {% url %} 模板标签的替代品，而是一个用于在模板中操作 URL 组件的通用工具集。以下是一些使用场景：

添加查询参数到 URL

若您的数据库中存储了外部 URL 列表，当在模板中创建这些 URL 的链接时，您可能需要为每个 URL 添加一个查询参数 referrer=mysite.com。使用 Spurl 可以避免生成 malformed 链接。

示例代码：

{% for url, title in list_of_links %}
    <a href="{% spurl base=url add_query="referrer=mysite.com" %}">{{ title }}</a>
{% endfor %}

处理安全的外部 URL

如果您的网站需要在安全和非安全模式下运行，Spurl 可以帮助确保页面上的资源链接与页面本身的安全状态相匹配，避免浏览器显示混合内容警告。

示例代码：

{% for image_url in list_of_image_urls %}
    <img src="{% spurl base=image_url secure=request.is_secure %}" />
{% endfor %}

与 {% url %} 模板标签一起使用

尽管 Spurl 主要用于操作外部 URL，但也可以与 Django 的 {% url %} 标签配合使用。您需要先使用 {% url %} 将反转的 URL 存储到模板变量中，然后传递给 Spurl。

示例代码：

{% url your_url_name as my_url %}
<a href="{% spurl path=my query="foo=bar&bar=baz" %}">点击这里!</a>

3. 项目 API 使用文档

以下是 Spurl 支持的参数列表：

• base: 解析并使用作为基础 URL。
• scheme: 设置 URL 的协议部分。
• host: 设置 URL 的主机部分。
• auth: 处理 HTTP 基础认证。
• path: 设置 URL 的路径部分。
• add_path: 添加路径组件到现有路径。
• fragment: 设置 URL 的片段部分。
• port: 设置 URL 的端口部分。
• query: 设置 URL 的查询部分。
• add_query: 追加查询参数到现有查询字符串。
• set_query: 追加查询参数到现有查询字符串，并覆盖同名参数。
• toggle_query: 在两个值之间切换查询参数。

4. 项目安装方式

请参照安装指南部分的内容进行安装。简而言之，您可以通过 pip 或从 GitHub 检出代码的方式进行安装，并确保将其添加到 INSTALLED_APPS 中。在模板中使用前，不要忘记加载 Spurl 的模板库。