Вложенные раскладки, группы и шаблоны

Цепочку от корневой раскладки до страницы вы уже собирали в прошлой статье. Интересное начинается на переходе: что происходит с общей частью цепочки, когда меняется только её хвост. В части II ответ был печальный — перерисовка из состояния сносила разметку целиком, вместе с открытым меню и позицией прокрутки, и их приходилось запоминать руками.

Раскладка от этого избавлена, и не благодаря Next, а благодаря React: позиция компонента в дереве при переходе не изменилась — значит, состояние остаётся при нём. Это то самое правило из статьи «Когда состояние сохраняется, а когда сбрасывается», просто применённое к маршрутам.

Маршрутов в песочнице нет, поэтому адрес здесь живёт в состоянии. Всё остальное настоящее: судьбу поддерева при смене страницы решает React, а не наша выдумка.

// app/dashboard/layout.tsx — обёртка для всего, что лежит ниже /dashboard
function DashboardLayout({ children }: { children: React.ReactNode }) {
  const [open, setOpen] = React.useState(false);
  console.log("раскладка: рендер");
  return (
    <section style={{ border: "1px dashed #999", padding: 8 }}>
      <button id="menu" onClick={() => setOpen(!open)}>
        меню: {open ? "открыто" : "закрыто"}
      </button>
      {children}
    </section>
  );
}

// app/dashboard/reports/page.tsx и app/dashboard/settings/page.tsx
function ReportsPage() {
  return <p>Отчёты</p>;
}
function SettingsPage() {
  return <p>Настройки</p>;
}

// маршрутизатора в песочнице нет, адрес держим в состоянии; судьбу поддерева
// при смене страницы решает настоящий React — а нас интересует именно она
function App() {
  const [url, setUrl] = React.useState("/dashboard/reports");
  return (
    <div>
      <button id="go" onClick={() => setUrl("/dashboard/settings")}>
        перейти в настройки
      </button>
      <DashboardLayout>
        {url === "/dashboard/reports" ? <ReportsPage /> : <SettingsPage />}
      </DashboardLayout>
    </div>
  );
}

ReactDOM.createRoot(document.getElementById("root")!).render(<App />);
setTimeout(() => document.getElementById("menu")!.click(), 50); // открыли меню
setTimeout(() => document.getElementById("go")!.click(), 100); // и «перешли» на другую страницу
setTimeout(() => {
  console.log(document.getElementById("menu")!.textContent);
}, 200);

Меню осталось открытым — хотя страница внутри раскладки поменялась. Обратите внимание и на вывод: «раскладка: рендер» напечаталось трижды. Перерисовка и пересоздание — разные вещи: компонент перерисовался, но остался тем же экземпляром, и open у него тот же. Настоящий Next при переходе общую часть цепочки даже не перерисовывает: он запрашивает у сервера только изменившийся хвост, а раскладки берёт готовыми — это называется частичной отрисовкой.

Раскладок в цепочке может быть сколько угодно: app/layout.tsx, app/dashboard/layout.tsx, app/dashboard/settings/layout.tsx. Каждая обернёт всё, что лежит ниже её папки, и каждая переживёт переходы внутри своего поддерева. Уровень выбирается не по красоте дерева, а по времени жизни: чем дольше вещь должна жить, тем выше её раскладка.

const files = new Set([
  "app/layout.tsx",
  "app/dashboard/layout.tsx",
  "app/dashboard/reports/page.tsx"
]);

function hasPage(dir: string): boolean {
  return files.has(dir + "/page.tsx");
}

console.log(hasPage("app/dashboard"));
console.log(hasPage("app/dashboard/reports"));

Правило «папка — это сегмент» упирается в стену на первом же реальном сайте. Витрине нужны адреса / и /pricing с одной шапкой, кабинету — /dashboard с другой. Раскладку можно положить только на папку, а любая папка добавляет сегмент: получить общую обёртку для двух страниц, не заведя над ними /marketing, вроде бы нельзя.

Скобки снимают ровно это ограничение. Папка с именем в круглых скобках — группа маршрутов: она участвует в дереве файлов, но не участвует в адресе.

const files = [
  "app/(marketing)/page.tsx",
  "app/(marketing)/pricing/page.tsx",
  "app/(app)/dashboard/page.tsx",
  "app/(app)/dashboard/settings/page.tsx"
];

// адрес собирается из папок между "app" и файлом; папка в скобках сегментом
// не становится — она нужна только чтобы положить рядом свою раскладку
function urlOf(file: string): string {
  const segments = file
    .split("/")
    .slice(1, -1)
    .filter((name) => !name.startsWith("("));
  return "/" + segments.join("/");
}

for (const file of files) {
  console.log(file, "→", urlOf(file));
}

Файлы лежат в разных группах, а адреса выглядят так, будто никаких групп нет. Смысл группы виден в соседнем файле: app/(marketing)/layout.tsx обернёт витрину, app/(app)/layout.tsx — кабинет, и ни одна из этих раскладок не попадёт в чужое поддерево.

Раз группы из адреса выпадают, два файла из разных групп легко сойдутся на одном адресе. Фреймворк такое дерево не соберёт — и это хорошая новость: конфликт находится при сборке, а не в проде.

const files = [
  "app/(marketing)/about/page.tsx",
  "app/(company)/about/page.tsx"
];

const taken = new Map<string, string>();
for (const file of files) {
  const url =
    "/" +
    file
      .split("/")
      .slice(1, -1)
      .filter((name) => !name.startsWith("("))
      .join("/");
  const busy = taken.get(url);
  if (busy) console.log("конфликт на", url, "—", busy, "и", file);
  else taken.set(url, file);
}

В терминале круглые скобки — знак самой оболочки: папку заводят как mkdir "(marketing)", иначе zsh ответит невнятной ошибкой разбора.

Группы используют и без раскладки — просто чтобы разложить полсотни маршрутов по смыслу: (auth), (legal), (admin). Адреса от этого не меняются, а дерево перестаёт быть свалкой.

Сохранение состояния — главное достоинство раскладки и иногда главная помеха. Анимация появления проигрывается один раз и больше не повторяется. Форма обратной связи хранит текст, набранный на прошлой странице. Счётчик просмотров в эффекте срабатывает при первом входе в раздел и молчит все следующие переходы.

Для этих случаев есть template.tsx. Файл выглядит точно так же — компонент с пропом children, — но Next выдаёт ему новый ключ на каждый переход. А что React делает с изменившимся ключом, вы знаете: сносит старое поддерево и монтирует новое.

Ниже одна и та же обёртка стоит дважды: сверху обычная, снизу — с ключом. Прежде чем нажать «Run», решите, сколько строк и каких напечатает эффект после единственного «перехода».

// одна и та же обёртка в двух ролях: сверху — как раскладка, снизу — как шаблон
function Chrome({ name, children }: { name: string; children: React.ReactNode }) {
  React.useEffect(() => {
    console.log(name + ": смонтирована");
    return () => console.log(name + ": размонтирована");
  }, [name]);
  return (
    <p style={{ border: "1px solid #999", padding: 6 }}>
      {name} → {children}
    </p>
  );
}

function App() {
  const [url, setUrl] = React.useState("/a");
  return (
    <div>
      <button id="go" onClick={() => setUrl(url === "/a" ? "/b" : "/a")}>
        переход
      </button>
      <Chrome name="layout">{url}</Chrome>
      {/* новый ключ на каждый адрес — ровно это Next делает с template.tsx */}
      <Chrome key={url} name="template">
        {url}
      </Chrome>
    </div>
  );
}

ReactDOM.createRoot(document.getElementById("root")!).render(<App />);
setTimeout(() => document.getElementById("go")!.click(), 50);

Верхняя обёртка о переходе не узнала: её эффект отработал один раз при монтировании. Нижняя пережила полный цикл — уборка старого экземпляра, монтирование нового. Никакой магии в template.tsx нет, это тот же приём с ключом, только ключ подставляет фреймворк.

Оба файла спокойно живут в одной папке: сначала layout.tsx, внутри него template.tsx, внутри шаблона — page.tsx. Так и делают, когда меню раздела должно пережить переход, а содержимое — появиться с анимацией.

Шаблон нужен реже, чем кажется. Начинайте с раскладки; заводите template.tsx, только когда поймали конкретную беду — не проигравшуюся анимацию или не сбросившуюся форму.

Первое, что хочется сделать в раскладке, — подсветить активный пункт меню. И тут выясняется, что адрес раскладке никто не передал: у неё есть children, а у динамических сегментов ещё и params — всё. Ни pathname, ни searchParams в списке пропсов нет; строку запроса получает только page.tsx.

Это следствие предыдущего раздела, а не забывчивость авторов. Раскладка не пересоздаётся при переходе — значит, она не может зависеть от адреса: иначе её пришлось бы перерисовывать на каждый переход, и вся выгода общей части цепочки исчезла бы.

Придумать себе недостающий проп компилятор не мешает — он проверяет то, что написано, а не то, что передаст фреймворк. Зато вызов без пропа он ловит сразу.

function DashboardLayout({
  children,
  pathname
}: {
  children: React.ReactNode;
  pathname: string;
}) {
  console.log("pathname в раскладке:", pathname);
  return (
    <section>
      <nav>{pathname === "/dashboard" ? "Кабинет (вы здесь)" : "Кабинет"}</nav>
      {children}
    </section>
  );
}

ReactDOM.createRoot(document.getElementById("root")!).render(
  <DashboardLayout>
    <p>Отчёты</p>
  </DashboardLayout>
);

Компилятор указал на вызов: «Свойство "pathname" отсутствует в типе "{ children: Element; }" и является обязательным в типе "{ children: ReactNode; pathname: string; }"». А теперь важное: в настоящем Next такого вызова в вашем коде нет вовсе — раскладку вызывает фреймворк, и передаёт он ей только children. Ошибке взяться неоткуда, и предупреждать компилятору не о чем: он проверяет ваши вызовы, а не чужие.

А в выводе — та же история с другой стороны: тип обещал string, а напечаталось undefined. Типы живут до запуска, значение приходит после — и придуманный проп так и остаётся пустым.

Правильный ход — вынести кусочек, которому нужен адрес, в маленький клиентский компонент и позвать в нём usePathname. Раскладка остаётся неподвижной, а перерисовывается только подсветка. Как это делается и почему такой компонент почти ничего не стоит — в статье про переходы.

Три инструмента этой статьи отвечают на разные вопросы, и путать их дорого. Сведём ответы в одну таблицу.

Проверить себя можно, не запуская Next: цепочка целиком выводится из путей файлов. Соберём её вместе с шаблонами — заодно видно, что шаблон стоит внутри своей раскладки.

const files = new Set([
  "app/layout.tsx",
  "app/(marketing)/layout.tsx",
  "app/(marketing)/pricing/page.tsx",
  "app/(app)/layout.tsx",
  "app/(app)/template.tsx",
  "app/(app)/dashboard/page.tsx"
]);

// цепочка идёт по ПАПКАМ файла страницы, а не по сегментам адреса
function chainOf(page: string): string[] {
  const chain: string[] = [];
  let dir = "";
  for (const part of page.split("/").slice(0, -1)) {
    dir = dir ? dir + "/" + part : part;
    if (files.has(dir + "/layout.tsx")) chain.push(dir + "/layout.tsx");
    if (files.has(dir + "/template.tsx")) chain.push(dir + "/template.tsx");
  }
  chain.push(page);
  return chain;
}

console.log(chainOf("app/(marketing)/pricing/page.tsx").join(" → "));
console.log(chainOf("app/(app)/dashboard/page.tsx").join(" → "));

Скобки в первой цепочке есть, а в адресе /pricing их нет — вся идея групп умещается в это расхождение. Дерево файлов отвечает сразу на два вопроса, и отвечает по-разному: адрес читается без групп, а цепочка обёрток — с ними.

И последнее по порядку, но не по важности: лишний уровень раскладки — это лишняя вложенность разметки и лишняя граница, через которую придётся что-то пробрасывать. Раскладку заводят под конкретную общую часть, а не «на всякий случай, вдруг пригодится».