# Django 5.2.8 documentation

# `django.urls` 实用函数

## reverse()

The `reverse()` function can be used to return an absolute path reference for a given view and optional parameters, similar to the `url` tag:

reverse(viewname, urlconf=None, args=None, kwargs=None, current_app=None, *, query=None, fragment=None)

`viewname` can be a URL pattern name or the callable view object used in the URLconf. For example, given the following `url`:

    from news import views

    path("archive/", views.archive, name="news-archive")

你可以使用以下任何一种方式来反查 URL：

    # using the named URL
    reverse("news-archive")

    # passing a callable object
    # (This is discouraged because you can't reverse namespaced views this way.)
    from news import views

    reverse(views.archive)

如果 URL 接受参数，你可以在 `args` 中传递参数。例如：

    from django.urls import reverse

    def myview(request):
        return HttpResponseRedirect(reverse("arch-summary", args=[1945]))

你也可以传递 `kwargs` 而不是 `args`。例如：

    >>> reverse("admin:app_list", kwargs={"app_label": "auth"})
    '/admin/auth/'

`args` 和 `kwargs` 不能同时传递给 `reverse()`。

如果不能匹配，`reverse()` 会引发一个 `NoReverseMatch` 异常。

`reverse()` 函数可以反查 URL 的多种正则表达式模式，但不是每一种可能的模式。目前主要的限制是，模式不能包含使用竖条（`"|"`）字符的替代选择。你可以很高兴地使用这样的模式与传入的 URL 进行匹配，并将它们发送给视图，但你不能反查这样的模式。

`current_app` 参数允许你向解析器提供一个提示，说明当前执行的视图属于哪个应用程序。这个 `current_app` 参数被用作提示，以便根据 命名空间的 URL 解析策略，将应用程序名称空间解析为特定应用程序实例上的 URL。

`urlconf` 参数是 URLconf 模块，其中包含用于反查的 URL 模式。默认情况下，使用的是当前线程的根 URLconf。

The `query` keyword argument specifies parameters to be added to the returned URL. It can accept an instance of `QueryDict` (such as `request.GET`) or any value compatible with `urllib.parse.urlencode()`. The encoded query string is appended to the resolved URL, prefixed by a `?`.

The `fragment` keyword argument specifies a fragment identifier to be appended to the returned URL (that is, after the path and query string, preceded by a `#`).

例如：

    >>> from django.urls import reverse
    >>> reverse("admin:index", query={"q": "biscuits", "page": 2}, fragment="results")
    '/admin/?q=biscuits&page=2#results'
    >>> reverse("admin:index", query=[("color", "blue"), ("color", 1), ("none", None)])
    '/admin/?color=blue&color=1&none=None'
    >>> reverse("admin:index", query={"has empty spaces": "also has empty spaces!"})
    '/admin/?has+empty+spaces=also+has+empty+spaces%21'
    >>> reverse("admin:index", fragment="no encoding is done")
    '/admin/#no encoding is done'

Changed in Django 5.2:

The `query` and `fragment` arguments were added.

Note

`reverse()` 返回的字符串已经被 urlquoted。例如：

    >>> reverse("cities", args=["Orléans"])
    '.../Orl%C3%A9ans/'

对 `reverse()` 的输出应用进一步的编码（如 `urllib.parse.quote()`）可能会产生不理想的结果。

按视图对象反转基于类的视图

The view object can also be the result of calling `as_view()` if the same view object is used in the URLConf. Following the original example, the view object could be defined as:

`news/views.py`

     from django.views import View

     class ArchiveView(View): ...

     archive = ArchiveView.as_view()

但是，请记住，命名空间视图不能按视图对象反转。

## `reverse_lazy()`

reverse() 的惰性执行版本。

reverse_lazy(viewname, urlconf=None, args=None, kwargs=None, current_app=None, *, query=None, fragment=None)

当你需要在你的项目的 URLConf 被加载之前使用 URL 反查时，这个功能很有用。一些常见的需要使用该功能的情况是：

- 提供一个反查的 URL 作为基于类的通用视图的 `url` 属性。

- 为装饰器提供一个反查的 URL（例如 `django.contrib.auth.decorators.permission_required()` 装饰器的 `login_url` 参数）。

- 提供一个反查的 URL 作为函数签名中参数的默认值。

Changed in Django 5.2:

The `query` and `fragment` arguments were added.

## `resolve()`

`resolve()` 函数可用于解析到相应视图函数的 URL 路径。该函数的签名如下：

resolve(path, urlconf=None)

`path` 是你要解析的 URL 路径。与 `reverse()` 一样，你不需要担心 `urlconf` 参数。该函数返回一个 `ResolverMatch` 对象，允许你访问关于解析 URL 的各种元数据。

如果 URL 没有解析，函数会引发一个 `Resolver404` 异常（`Http404` 的一个子类）。

class ResolverMatch
  func

    用于服务 URL 的视图函数。

  args

    从 URL 中解析出的传递给视图函数的参数。

  kwargs

    所有将传递给视图函数的关键字参数，即 `captured_kwargs` 和 `extra_kwargs`。

  captured_kwargs

    从 URL 解析出的将传递给视图函数的捕获关键字参数。

  extra_kwargs

    将传递给视图函数的额外关键字参数。

  url_name

    与 URL 匹配的 URL 模式的名称。

  route

    匹配 URL 模式的路径。

    例如，如果 `path('users/<id>/', ...)``是匹配的模式，``route` 将包含 `'users/<id>/'`。

  tried

    在 URL 匹配一个模式或耗尽可用模式之前尝试的 URL 模式列表。

  app_name

    匹配 URL 模式的应用程序命名空间。

  app_names

    匹配 URL 模式的完整应用程序命名空间中的单个命名空间组件列表。例如，如果 `app_name` 是 `'foo:bar'`，那么 `app_names` 将是 `['foo', 'bar']`。

  namespace

    匹配 URL 模式的实例命名空间。

  namespaces

    匹配 URL 模式的完整实例命名空间中的单个命名空间组件列表，即，如果命名空间是 `foo:bar`，那么命名空间将是 `['foo'，'bar']`。

  view_name

    匹配 URL 的视图名称，包括命名空间（如果有的话）。

然后可以查询一个 `ResolverMatch` 对象，以提供与 URL 相匹配的 URL 模式的信息：

    # Resolve a URL
    match = resolve("/some/path/")
    # Print the URL pattern that matches the URL
    print(match.url_name)

一个 `ResolverMatch` 对象也可以解包为以下三个：

    func, args, kwargs = resolve("/some/path/")

`resolve()` 的一个可能的用法是测试一个视图在重定向到它之前是否会引发 `Http404` 错误：

    from urllib.parse import urlsplit
    from django.urls import resolve
    from django.http import Http404, HttpResponseRedirect

    def myview(request):
        next = request.META.get("HTTP_REFERER", None) or "/"
        response = HttpResponseRedirect(next)

        # modify the request and response as required, e.g. change locale
        # and set corresponding locale cookie

        view, args, kwargs = resolve(urlsplit(next).path)
        kwargs["request"] = request
        try:
            view(*args, **kwargs)
        except Http404:
            return HttpResponseRedirect("/")
        return response

## `get_script_prefix()`

get_script_prefix()

通常，你应该始终使用 `reverse()` 来定义应用程序中的 URL。然而，如果你的应用程序自己构建了 URL 层次结构的一部分，偶尔可能需要生成 URL。在这种情况下，你需要能够找到 Django 项目在其 Web 服务器内的基本 URL（通常，`reverse()` 会为你处理这个）。在这种情况下，你可以调用 `get_script_prefix()`，它将返回你的 Django 项目的 URL 的脚本前缀部分。如果你的 Django 项目位于其 Web 服务器的根目录，这将始终是 `"/"`。

Warning

此函数 不能 在请求-响应周期之外使用，因为它依赖于在该周期期间初始化的值。