usePageTitle

Описание

usePageTitle — хук, который устанавливает document.title на время жизни компонента. Поддерживает вложенное использование: хранит стек заголовков и при размонтировании восстанавливает предыдущий заголовок (или исходный, если стек пуст).

---

Сигнатура

function usePageTitle(title: string): void;

• Параметры

  • title: string — заголовок страницы, который следует установить на текущем рендере.

• Возвращает

  • void — побочных значений нет; хук управляет document.title и историей заголовков.

---

Примеры

1) Базовое использование

import { usePageTitle } from '@webeach/react-hooks';

export function SettingsPage() {
  usePageTitle('Settings — MyApp');

  return <h1>Settings</h1>;
}

2) Вложенные компоненты: приоритет последнего смонтированного

import { usePageTitle } from '@webeach/react-hooks';

function PageLayout() {
  usePageTitle('Dashboard — MyApp');

  return <Widget />; // дочерний может переопределить заголовок
}

function Widget() {
  usePageTitle('Notifications — MyApp');

  return <div />; // пока Widget смонтирован, в заголовке «Notifications — MyApp»
}
// После размонтирования Widget заголовок снова станет «Dashboard — MyApp»

3) Реактивное обновление заголовка по пропсам/состоянию

import { usePageTitle } from '@webeach/react-hooks';

type UserProfileProps = {
  name: string;
};

export function UserProfile(props: UserProfileProps) {
  const { name } = props;

  usePageTitle(`${name} — Profile`);

  return <h1>{name}</h1>;
}

---

Поведение

1. LIFO‑приоритет

   • Последний смонтированный usePageTitle имеет приоритет и определяет текущий заголовок. Обновления «нижних» уровней не отображаются, пока верхний экземпляр не будет размонтирован.

2. Восстановление заголовка

   • При размонтировании хук снимает свою запись из стека и восстанавливает предыдущий заголовок. Когда стек пуст, возвращается исходный document.title, считанный при первом использовании хука.

3. Обновление на каждом рендере

   • При изменении title у текущего экземпляра заголовок обновляется сразу; запись в стеке обновляется без изменения порядка (приоритет остаётся у последнего смонтированного).

4. Layout‑семантика

   • Изменение заголовка выполняется в layout‑фазе (изоморфный layout‑эффект), что гарантирует своевременное применение перед пейнтом на клиенте.

5. SSR‑безопасность

   • На сервере побочных эффектов нет; обращения к document происходят только после маунта. Хук безопасен для SSR/ISR.

6. Глобальная исходная величина

   • Исходный document.title сохраняется один раз при первом использовании хука и используется для восстановления после снятия последнего заголовка.

---

Когда использовать

• Страницы и маршруты SPA/MPA, где компонент отвечает за заголовок вкладки.
• Вложенные виджеты/модальные окна, временно переопределяющие заголовок.
• Динамические заголовки, зависящие от данных (имя пользователя, состояние страницы и т.п.).

---

Когда не использовать

• Если заголовок управляется роутером/мета‑фреймворком (Next/Remix/React‑Helmet) — избегайте дублирования источников истины, используйте один механизм.
• Если заголовок не должен меняться в зависимости от компонента — достаточно статической разметки.

---

Частые ошибки

1. Ожидание приоритета «последнего изменения», а не «последнего маунта»

   • Порядок в стеке определяется маунтом, а не временем последнего обновления. Чтобы временно повысить приоритет, монтируйте отдельный экземпляр хука выше по иерархии или размонтируйте текущий верхний.

2. Жёсткое управление заголовком в нескольких местах одновременно

   • Если и роутер, и компоненты меняют заголовок, возможны «перетягивания каната». Выберите единый источник истины.

3. Попытка читать document во время SSR

   • На сервере document недоступен. Оставьте эту работу хуку — он выполнит изменения на клиенте после маунта.

---

Смотрите также

• usePageVisibility