django-browser-reload 1.15.0

需求

支持Python 3.8到3.12。

支持Django 3.2到5.1。

所有Django版本都支持WSGI。Django 4.2+支持ASGI。

您的浏览器需要支持

• EventSource - 通用可用。

• SharedWorker - 在Chrome、Edge、Firefox和Opera上长期可用。自版本16（2022-09-12）以来在Safari上可用。

安装

1. 使用pip安装

   python -m pip install django-browser-reload

2. 确保您的"django.contrib.staticfiles"包含在您的INSTALLED_APPS中。

3. 将django-browser-reload添加到您的INSTALLED_APPS

   INSTALLED_APPS = [
       ...,
       "django_browser_reload",
       ...,
   ]

4. 在您的根URLconf中包含应用程序URL

   from django.urls import include, path
   
   urlpatterns = [
       ...,
       path("__reload__/", include("django_browser_reload.urls")),
   ]

   如果需要，您可以使用另一个前缀。

5. 添加中间件

   MIDDLEWARE = [
       # ...
       "django_browser_reload.middleware.BrowserReloadMiddleware",
       # ...
   ]

   中间件应列在其他任何编码响应的中间件之后，例如 Django 的 GZipMiddleware。

   当 DEBUG 为 True 时，中间件会自动在 HTML 响应的 </body> 标签之前插入所需的脚本标签。它会为每个 HTML 响应执行此操作，这意味着它将包含在 Django 的调试页面、管理页面等中。如果您想有更多的控制权，您可以在模板中插入脚本标签——见下文。

完成！📯

为了更快、更有效地重新加载，还需要设置 Django 内置的 Watchman 支持。

它的作用

当 DEBUG 为 True 时，模板标签包括一个小脚本。此脚本连接回开发服务器，当静态资源或模板被修改，或者 runserver 重新启动后，它会自动重新加载。重新加载只发生在最新打开的标签页中。

示例项目

请参阅 GitHub 仓库 example/ 目录中的 示例项目。启动它并修改其文件以查看重新加载的效果。

模板标签

如果您觉得中间件不适用，您还可以在相关页面上使用模板标签来插入脚本。模板标签同时支持 Django 模板和 Jinja 版本，并且仅在 DEBUG 为 True 时输出脚本标签。

对于 Django 模板，请在基本模板中加载标签并使用它。标签可以放在任何位置，但最好放在 </body> 之前。

{% load django_browser_reload %}

...

    {% django_browser_reload_script %}
  </body>
</html>

要将 django-browser-reload 添加到 Django 的管理中，请在名为 admin/base_site.html 的模板中进行操作。

{% extends "admin/base_site.html" %}

{% load django_browser_reload %}

{% block extrahead %}
    {{ block.super }}
    {% django_browser_reload_script %}
{% endblock %}

这遵循 Django 文档中关于 扩展已覆盖模板 的说明。

对于 Jinja 模板，您需要执行两个步骤。首先，将标签函数加载到您的 自定义环境 的全局作用域中。

# myproject/jinja2.py
from jinja2 import Environment
from django_browser_reload.jinja import django_browser_reload_script


def environment(**options):
    env = Environment(**options)
    env.globals.update(
        {
            # ...
            "django_browser_reload_script": django_browser_reload_script,
        }
    )
    return env

其次，在基本模板中渲染标签。它可以放在任何位置，但最好放在 </body> 之前。

...
    {{ django_browser_reload_script() }}
  </body>
</html>

完成了！

它是如何工作的

下面是一个图表

                                     Browser

                             Tab 1    Tab 2     Tab N
                           listener  listener  listener
                                \       |       /
  Django                         \      |      /
                                  \     |     /
Events View --------------------> Shared worker

模板标签在每个页面上包括一个监听脚本。此监听脚本启动或连接到一个 SharedWorker，运行工作脚本。然后工作脚本连接到 Django 的事件视图，并使用 EventSource 接收服务器发送的事件。

此事件源使用 StreamingHttpResponse 向工作发送事件。视图继续无限期地流式传输事件，直到断开连接。（这需要一个线程，如果您使用 runserver 的 --nothreading 选项，则无法工作。）

在相关事件发生时，工作会重新加载最新连接的标签页。（它避免重新加载 所有 标签页，因为这可能是昂贵的。）

当模板更改时，django-browser-reload 会利用 Django 的自动重新加载基础设施。一个内部 Django 信号指示模板文件何时更改。事件视图接收此信号并将事件发送到工作，从而触发重新加载。没有智能过滤 - 如果 任何 模板文件更改，则视图会重新加载。

当服务器重启时，django-browser-reload 使用版本 ID 来重新加载。此 ID 在导入视图模块时随机生成，因此每次服务器启动时都会不同。当服务器重启时，工作进程的 EventSource 将以最小的延迟重新连接。在连接时，事件视图发送版本 ID，工作进程将其视为不同，从而触发重新加载。

事件视图还会每秒发送版本 ID 以保持连接活跃。