Совместимость API

Библиотека Navigo предназначена для организации маршрутизации на стороне клиента в одностраничных приложениях (SPA). Одним из ключевых аспектов при работе с библиотекой является понимание совместимости API между разными версиями, что позволяет корректно обновлять приложения без нарушения существующей логики маршрутизации.

Версионирование и поддержка

Navigo придерживается принципов семантического версионирования. Основные версии имеют следующие характеристики:

  • v7.x – текущая стабильная версия с поддержкой ES6+, более простой конфигурацией маршрутов и улучшенной производительностью.
  • v6.x – устаревшая версия, поддерживает стандартные возможности маршрутизации, но имеет отличия в синтаксисе и API методов.
  • v5.x и ниже – сильно устаревшие, рекомендуются только для поддержки старого кода.

Совместимость между версиями не всегда полная: методы могут быть переименованы, структура параметров изменена, а старые способы регистрации маршрутов могут перестать работать.

Основные изменения API

Регистрация маршрутов

v5 и v6:

var router = new Navigo('/');
router.on('/home', function() {
  console.log('Home page');
});
router.on('/about', function() {
  console.log('About page');
});
router.resolve();

v7:

const router = new Navigo('/', { hash: true });

router.on({
  '/home': () => console.log('Home page'),
  '/about': () => console.log('About page')
});

router.resolve();

Ключевое отличие – возможность передавать объект с маршрутами вместо последовательных вызовов .on(), а также поддержка опции hash для использования хеш-маршрутов.

Навигация и переход между маршрутами

В старых версиях:

router.navigate('/home');

В v7 сохраняется аналогичный метод, но добавлена возможность передачи дополнительных параметров:

router.navigate('/home', { state: { user: 'John' } });

Это обеспечивает совместимость с History API и позволяет хранить состояние при навигации.

Динамические параметры

В версиях до v7:

router.on('/user/:id', function(params) {
  console.log(params.id);
});

В v7 синтаксис остаётся совместимым, но появилась дополнительная опция hooks:

router.on('/user/:id', {
  uses: ({ params }) => console.log(params.id),
  before: (done, match) => {
    console.log('Before hook', match.params.id);
    done();
  }
});

Теперь можно задействовать хуки для валидации параметров и асинхронной загрузки данных до рендеринга компонента.

Совместимость с History API и Hash

Navigo поддерживает два режима работы маршрутизатора:

  1. History API (pushState) – позволяет использовать чистые URL без #. Совместимость зависит от браузера: все современные версии поддерживаются, старые требуют fallback.
  2. Hash-маршруты (/#/) – используется в случаях, когда сервер не поддерживает pushState или требуется обратная совместимость.

Конструктор принимает опцию { hash: true } для включения hash-маршрутов. С точки зрения API, большинство методов (on, navigate, resolve) работают одинаково в обоих режимах.

Обратная совместимость

Для проектов, изначально использующих старые версии Navigo, важно учитывать следующие моменты:

  • Старый синтаксис .on(path, handler) продолжает работать, но использование объекта маршрутов более предпочтительно.
  • Опции linksSelector и useHash в v7 переименованы и могут вести себя иначе.
  • Асинхронные хуки и state в navigate() доступны только в v7 и выше.
  • Методы .updatePageLinks() и .notFound() сохраняют совместимость, но требуют проверки аргументов.

Практические рекомендации по миграции

  1. Проверить, какая версия Navigo используется в проекте.
  2. Если проект использует v5 или v6, постепенно переписывать маршруты на объектную форму для совместимости с v7.
  3. При наличии динамических параметров подключать хуки для асинхронной валидации.
  4. Тестировать навигацию в обоих режимах – History API и hash.
  5. Убедиться, что все вызовы navigate() передают корректное состояние, особенно при обновлении страницы или переходах между вкладками.

Совместимость API в Navigo построена таким образом, что базовые возможности маршрутизации остаются неизменными, но новые версии расширяют функционал за счёт удобных объектов маршрутов, хуков и поддержки состояния. Это позволяет плавно обновлять приложения без полной переработки существующей структуры маршрутов.

Оглавление