Маршрутизация и навигация frontend-приложений¶
Требования этого документа применяются к browser-навигации frontend-приложений
профилей CSR, SSR, SSG и edge по frontend/rendering-profiles.md. Уровни
обязательности определены в корневом README.md.
Маршрут — соответствие URL пользовательскому состоянию приложения. Deep link — URL, предназначенный для прямого открытия без предварительного перехода внутри приложения.
FE-NAV-001. URL как контракт навигации¶
Уровень: MUST
Применяется к: пользовательскому состоянию, включённому в browser history или предназначенному для прямого открытия
Проект должен версионировать шаблон маршрута и семантику path, query и fragment, которые влияют на пользовательский результат. Для одного субъекта, версии приложения и доступных данных прямое открытие, reload, внутренний переход и переходы back/forward должны разрешать тот же идентификатор ресурса, объявленное состояние маршрута и результат проверки доступа.
Отсутствующее, пустое и не соответствующее грамматике маршрута значение параметра должны иметь разные контрактные результаты, когда различается их смысл. Добавление записи в history и замена текущей записи должны соответствовать пользовательскому намерению; восстановление записи history не должно повторно выполнять необратимый эффект.
Обоснование¶
URL, который работает только после внутреннего перехода, нельзя безопасно сохранить, открыть после reload или использовать как deep link.
Проверка¶
- e2e-тест прямого открытия, reload и внутреннего перехода;
- тест back/forward после чтения и изменяющей операции;
- параметризованный тест отсутствующего, пустого и не соответствующего грамматике параметра.
Исключения¶
Эфемерное состояние MAY не кодироваться в URL, если его потеря при reload и переходе по ссылке является объявленным пользовательским результатом и не влияет на ресурс, полномочия или необратимую операцию.
FE-NAV-002. Результат перехода и изменение маршрута¶
Уровень: MUST
Применяется к: разрешению маршрута и изменению опубликованного URL
Приложение должно различать успешный маршрут, отсутствие ресурса, недостаточные
права и техническую недоступность, не перенаправляя эти исходы молча на
домашнюю страницу. Client-side route guard не должен заменять backend-
авторизацию по FE-SEC-005. После выхода или изменения прав защищённый маршрут
должен прекратить показывать прежние данные по FE-API-008.
Удалённый или изменённый опубликованный URL должен либо сохранять прежнюю
семантику на период совместимости, либо иметь явное отображение на новый URL.
Redirect должен переносить только разрешённые параметры и выполнять
FE-SEC-008. Неизвестный URL не должен становиться успешным результатом
несвязанного маршрута.
Обоснование¶
Неявный fallback скрывает сломанную ссылку, а client guard и устаревшее представление не обеспечивают разграничение доступа.
Проверка¶
- e2e-тест отсутствующего, запрещённого и недоступного маршрута;
- тест активного защищённого маршрута при выходе и отзыве прав;
- contract-тест старого URL, redirect и неизвестного URL.
Исключения¶
Catch-all route MAY показывать общий экран ошибки, если сохраняет различимый машинный и пользовательский результат исходного отказа.
FE-NAV-003. Фокус и позиция после перехода¶
Уровень: SHOULD
Применяется к: client-side переходу без полной загрузки документа
Для каждого класса маршрута проекту следует определить точку фокуса нового представления и после перехода устанавливать фокус в эту точку, а также обновлять доступное имя документа. Переход back/forward следует восстанавливать позицию прокрутки, если ресурс и пользовательское намерение не требуют показать изменившееся место.
Обоснование¶
Визуальная смена маршрута без изменения фокуса и имени документа незаметна для части пользователей и затрудняет возврат по history.
Проверка¶
- e2e-тест фокуса, имени документа и прокрутки;
- ручная проверка перехода с клавиатурой и экранным читателем.
Исключения¶
Фокус MAY оставаться на инициаторе, если он остаётся видимым, активным и содержательно управляет обновлённой областью.