Django-кнопка «Наверх»: подключить за минуту вместо очередного велосипеда

krox1 час назад

Django-кнопка «Наверх»: подключить за минуту вместо очередного велосипеда

Уровень сложностиПростойВремя на прочтение4 минОхват и читатели3.5KDjango*Python*Open source*Веб-разработка*КейсDjango-кнопка «Наверх»: подключить за минуту вместо очередного велосипеда

Кнопка «Наверх» — вещь настолько простая, что обычно её делают прямо в проекте: ссылка, немного 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: можно поменять угол, цвета, размер, иконку, поведение при прокрутке и отдельные параметры для мобильной версии.

Настройка через 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-баннерами и чатами.Теги:• django
• python
• django admin
• кнопка Наверх
• scroll to top
• ui-компоненты
• веб-разработка
• frontend
• svg
• доступностьХабы:• Django
• Python
• Open source
• Веб-разработка