Кнопка «Наверх» — вещь настолько простая, что обычно её делают прямо в проекте: ссылка, немного CSS, пара строк JavaScript — готово.

Для одной страницы это нормально. Но потом проект растёт. Появляется мобильная версия, cookie-баннер, чат в углу, требования к контрасту, строгий CSP. Где-то нужно добавить кнопку ещё и в Django Admin. И тот самый маленький кусок кода начинает жить своей жизнью.

Такой модуль нужен давно: кнопка «Наверх» встречается на множестве сайтов, но в Django-проектах её по-прежнему часто собирают вручную — каждый раз немного по-своему.

Мне хотелось получить готовое решение: подключил, настроил через админку и больше не возвращаешься к этому коду при каждом новом проекте.

Так появился django-scroll-to-top.

Кнопка «Наверх» на демо-сайте

Конечно, для одной страницы можно написать всё вручную — и это будет правильным решением. Пакет нужен в другом случае: когда хочется поставить кнопку один раз, а потом не возвращаться к ней при каждом изменении интерфейса.

Не очередной большой фронтенд-комбайн, а обычный Django-модуль, который:

• подключается через один template tag;

• работает и на сайте, и в стандартной Django Admin;

• настраивается через админку, без правок CSS и JavaScript в проекте;

• не тащит jQuery, CDN и обязательную сборку фронтенда;

• работает при строгом CSP;

• учитывает клавиатуру, фокус, контраст и отключение анимаций;

• не прячется под cookie-баннером, чатом или мобильной навигацией.

Пакет пока находится в серии 0.x: его уже можно использовать, но до версии 1.0 отдельные точки интеграции ещё могут меняться. Поддерживаются Python 3.10+ и Django 4.2 LTS, 5.x и 6.0.

В обычном случае нужно установить пакет:

python -m pip install django-scroll-to-top

Добавить приложение в INSTALLED_APPS:

INSTALLED_APPS = [
    # ...
    "django_scroll_to_top",
]

Если нужна интеграция со стандартной Django Admin, пакет должен стоять перед django.contrib.admin:

INSTALLED_APPS = [
    # ...
    "django_scroll_to_top",
    "django.contrib.admin",
]

Подключить URLConf:

# urls.py
from django.urls import include, path

urlpatterns = [
    # ...
    path(
        "scroll-to-top/",
        include(
            ("django_scroll_to_top.urls", "django_scroll_to_top"),
            namespace="django_scroll_to_top",
        ),
    ),
]

Применить миграции:

python manage.py migrate

И добавить тег в общий шаблон:

{% load scroll_to_top %}

{# содержимое страницы #}

{% scroll_to_top %}

После этого кнопка уже появится на сайте.

Настройки внешнего вида не передаются длинным списком аргументов в шаблоне. Они хранятся в базе и редактируются через Django Admin: можно поменять угол, цвета, размер, иконку, поведение при прокрутке и отдельные параметры для мобильной версии.

У кнопки есть две независимые области настроек:

• site — страницы сайта;

• admin — стандартная Django Admin.

То есть в админке можно сделать одну кнопку, а на публичной части сайта — другую. Например, в админке оставить спокойный нейтральный вариант, а на сайте подобрать цвета под оформление проекта.

Раздел django-scroll-to-top в Django Admin

Настройки работают через ревизии. Можно создать черновик, посмотреть результат, опубликовать его, а потом при необходимости вернуться к предыдущему варианту.

Предпросмотр кнопки в админке

Для кнопки «Наверх» это может показаться избыточным. Но когда внизу страницы появляется баннер, чат или новая мобильная панель, возможность поправить кнопку через админку заметно удобнее, чем искать старый CSS и выпускать изменения только ради отступа.

По умолчанию в пакет добавлен небольшой набор иконок из Tabler Icons. Я выбрал его потому, что это аккуратные и узнаваемые SVG-иконки с MIT-лицензией. Они используют currentColor, поэтому нормально подхватывают выбранные цвета кнопки.

В админке можно выбрать стрелку, шеврон, caret и другие привычные обозначения прокрутки вверх.

Встроенный набор иконок Tabler

Но встроенным набором всё не ограничивается. Можно загрузить собственную SVG-иконку через админку: например, если у проекта уже есть фирменный набор иконок или хочется использовать свой знак вместо обычной стрелки.

Загруженная SVG не отдаётся в браузер как есть: перед использованием она проходит проверку и очистку от потенциально опасных конструкций. Для иконки также можно сохранить автора, источник и информацию о лицензии.

То есть для быстрого старта есть готовые варианты, а для проекта со своим оформлением не придётся менять шаблоны или лезть в код пакета.

django-scroll-to-top не пытается доказать, что кнопка «Наверх» сама по себе сложная задача. В простом проекте её действительно можно сделать вручную за несколько минут.

Но если такая кнопка нужна не один раз, а как нормальный переиспользуемый элемент сайта или админки, удобнее подключить готовый модуль и не держать в каждом проекте свою слегка отличающуюся версию.

В пакете уже есть отдельные настройки для мобильных устройств, варианты оформления, проверка контраста, строгий CSP, безопасная загрузка SVG и обход плавающих виджетов. Это уже тема для следующей статьи. Здесь хотелось показать главное: кнопку можно быстро подключить и не собирать заново в каждом Django-проекте.

Репозиторий: GitHub
Пакет: PyPI

Буду рад отзывам, замечаниям и особенно сообщениям о том, как пакет ведёт себя в проектах с нестандартной Django Admin, сторонними темами, cookie-баннерами и чатами.