Опции конфигурации

Библиотека Page.js предоставляет набор опций, позволяющих управлять поведением маршрутизатора без изменения его внутренней логики. Конфигурация осуществляется через вызов функции page() с соответствующими аргументами или через вспомогательные методы.

Ключевые аспекты настройки:

  • управление историей браузера
  • настройка базового пути приложения
  • контроль обработки кликов по ссылкам
  • работа с хеш-навигацией
  • настройка обработки 404 маршрутов

Опция base

Опция base задаёт базовый путь приложения. Это особенно важно при развертывании не в корне домена.

page.base('/app');

После установки:

  • маршрут /users фактически будет доступен по адресу /app/users
  • все внутренние переходы будут автоматически учитывать этот префикс

Особенности:

  • должна быть вызвана до регистрации маршрутов
  • влияет только на клиентскую навигацию
  • не изменяет реальные URL на сервере

Типичный сценарий использования:

  • SPA размещено по адресу https://example.com/app/
  • сервер настроен на отдачу index.html по всем вложенным маршрутам

Опция strict

Опция strict управляет чувствительностью маршрутов к завершающему слешу.

page.strict(true);

Поведение:

  • true — /about и /about/ считаются разными маршрутами
  • false (по умолчанию) — различие игнорируется

Пример:

page('/about', handler);

  • при strict: false:

    • /about
    • /about/

    оба маршрута попадут в обработчик

  • при strict: true:

    • /about/ не будет соответствовать маршруту

Использование оправдано в случаях:

  • строгая SEO-структура
  • серверная маршрутизация требует точного совпадения

Опция decodeURLComponents

Контролирует декодирование параметров URL.

page.decodeURLComponents = true;

При включении:

  • параметры автоматически декодируются через decodeURIComponent

Пример:

/user/%D0%98%D0%B2%D0%B0%D0%BD

→ превращается в:

Иван

Если отключить:

page.decodeURLComponents = false;
  • параметры передаются в исходном виде
  • полезно при нестандартной обработке URL

Управление режимом истории

Использование HTML5 History API

По умолчанию Page.js использует history.pushState.

page.start();

Это обеспечивает:

  • чистые URL без #
  • поддержку навигации “назад/вперёд”

Отключение pushState (hashbang режим)

Если требуется поддержка старых браузеров или сервер не настроен:

page({
  hashbang: true
});

URL принимает вид:

/#!/about

Особенности:

  • маршрутизация происходит через location.hash
  • не требует серверной настройки
  • ухудшает читаемость URL

Принудительное отключение pushState

page({
  pushState: false
});

Результат аналогичен hashbang, но без !:

#/about

Опция click

Контролирует автоматический перехват кликов по ссылкам.

page({
  click: false
});

Если отключено:

  • Page.js не будет перехватывать <a> клики
  • навигацию необходимо обрабатывать вручную

По умолчанию:

  • перехватываются клики:

    • без target="_blank"
    • без download
    • внутри текущего домена

Это поведение предотвращает полную перезагрузку страницы.

Опция popstate

Управляет обработкой события popstate.

page({
  popstate: false
});

Если отключено:

  • кнопки браузера “назад/вперёд” не будут вызывать маршруты

Используется в случаях:

  • кастомная история
  • интеграция с другими роутерами

Опция dispatch

Определяет, нужно ли сразу обрабатывать текущий URL при старте.

page({
  dispatch: false
});

Поведение:

  • true (по умолчанию) — текущий маршрут обрабатывается сразу
  • false — требуется ручной вызов
page.start({ dispatch: false });
page.show(location.pathname);

Полезно:

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

Опция hashbang

Расширение для hash-навигации:

page({
  hashbang: true
});

Разница:

  • #/path — стандартный hash
  • #!/path — hashbang

Исторически использовался для:

  • SEO в старых поисковых системах
  • совместимости с legacy-проектами

Обработка 404 маршрутов

Page.js не имеет отдельной встроенной опции, но позволяет задать fallback:

page('*', notFoundHandler);

Альтернативный способ:

page((ctx, next) => {
  if (!ctx.handled) {
    notFoundHandler(ctx);
  }
});

Где:

  • ctx.handled — флаг успешного совпадения маршрута

Управление контекстом маршрута

Контекст (ctx) формируется с учетом конфигурации:

  • ctx.path — текущий путь
  • ctx.params — параметры маршрута
  • ctx.querystring — строка запроса
  • ctx.hash — якорь

Некоторые параметры зависят от опций:

  • decodeURLComponents
  • strict
  • base

Комбинирование опций

Пример полной конфигурации:

page.base('/app');

page({
  click: true,
  popstate: true,
  dispatch: true,
  hashbang: false
});

page.strict(false);
page.decodeURLComponents = true;

page.start();

Особенности:

  • порядок имеет значение
  • base должен устанавливаться до маршрутов
  • start() — последняя операция

Поведение при вложенных конфигурациях

Page.js не поддерживает изолированные конфигурации для разных групп маршрутов. Все опции глобальны:

  • невозможно задать разные base для разных модулей
  • невозможно частично отключить click для отдельных маршрутов

Решение:

  • использовать несколько экземпляров (редко)
  • либо оборачивать маршруты в middleware

Middleware и влияние конфигурации

Middleware-функции получают уже обработанный контекст:

page((ctx, next) => {
  console.log(ctx.path);
  next();
});

Влияние опций:

  • base — изменяет ctx.path
  • strict — влияет на совпадение маршрута
  • decodeURLComponents — влияет на ctx.params

Отладка конфигурации

Типичные проблемы:

Маршрут не срабатывает

Причины:

  • неверный base
  • включен strict
  • ошибка в пути

Двойной обработчик

Причины:

  • dispatch: true + ручной вызов page.show()

Не работает кнопка “назад”

Причины:

  • отключён popstate

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

Для SPA в продакшене:

page.base('/');
page.strict(false);
page.start();

Для подкаталога:

page.base('/app');
page.start();

Для старых браузеров:

page({
  hashbang: true
});

Для полного контроля:

page({
  click: false,
  popstate: false,
  dispatch: false
});

Влияние конфигурации на производительность

  • click: true — добавляет глобальный обработчик событий
  • popstate: true — подписка на историю браузера
  • dispatch: true — мгновенный вызов маршрута

Оптимизация:

  • отключать ненужные опции
  • минимизировать middleware

Расширение конфигурации

Page.js не предоставляет API для пользовательских опций, но можно:

  • использовать глобальные переменные
  • расширять ctx
page((ctx, next) => {
  ctx.user = getUser();
  next();
});

Взаимодействие с сервером

Конфигурация маршрутизатора должна соответствовать серверной настройке:

  • base должен совпадать с серверным роутингом
  • при использовании pushState сервер должен отдавать index.html для всех маршрутов

Пример для Express:

app.get('*', (req, res) => {
  res.sendFile('index.html');
});

Ограничения конфигурации

  • нет динамического изменения после start()
  • нет изоляции для модулей
  • нет встроенной системы профилей конфигурации

Решение:

  • инициализировать заново при необходимости
  • использовать внешние инструменты управления состоянием
Оглавление