Динамические сегменты и асинхронные params

Здесь будет встроен видео-разбор темы (5–7 минут, YouTube / RuTube / VK Видео) — тем, кто лучше воспринимает на слух, текст ниже не обязателен.

Тысячу папок под тысячу товаров никто не заводит. Вместо этого папку называют [id]: квадратные скобки говорят маршрутизатору, что сюда подойдёт любое значение сегмента, а какое именно стояло в адресе — узнает страница из пропа params.

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

ts

// адрес и шаблон сравниваются посегментно — так Next выбирает страницу
function match(pattern: string, url: string): Record<string, string> | null {
  const parts = pattern.split("/").filter(Boolean);
  const segments = url.split("/").filter(Boolean);
  if (parts.length !== segments.length) return null;

  const params: Record<string, string> = {};
  for (let i = 0; i < parts.length; i++) {
    const part = parts[i];
    if (part.startsWith("[")) {
      // имя внутри скобок становится ключом, значение приезжает из адреса
      params[part.slice(1, -1)] = segments[i];
    } else if (part !== segments[i]) {
      return null;
    }
  }
  return params;
}

console.log(match("/products/[id]", "/products/42"));
console.log(match("/products/[id]", "/products/kettle"));
console.log(match("/products/[id]", "/products/42/reviews"));

страница примера

Сначала предположите, что выведет код

Ключ в params — это имя внутри скобок, и никакой связи с содержимым адреса у него нет: назовёте папку [productId] — получите params.productId. Значение же всегда строка, даже если в адресе одни цифры.

Обратите внимание на последнюю строку: /products/42/reviews не подошёл. Динамический сегмент жаден к значениям, но занимает ровно один кусок пути — как одна папка в дереве, которой он и является.

Папка	Адрес	params
`app/products/[id]`	`/products/42`	`{ id: "42" }`
`app/products/[id]`	`/products/kettle`	`{ id: "kettle" }`
`app/products/[id]`	`/products`	404: сегменту нечем заполниться
`app/products/[id]`	`/products/42/reviews`	404: лишний сегмент
`app/shop/[category]/[id]`	`/shop/tea/42`	`{ category: "tea", id: "42" }`

А если рядом с [id] завести обычную папку new? Под адрес /products/new подойдут оба шаблона, и спор надо как-то решать. Next решает его в пользу буквального сегмента — попробуйте предсказать вывод.

ts

const routes = ["/products/new", "/products/[id]"];

function fits(pattern: string, url: string): boolean {
  const parts = pattern.split("/");
  const segments = url.split("/");
  return (
    parts.length === segments.length &&
    parts.every((part, i) => part.startsWith("[") || part === segments[i])
  );
}

function pick(url: string): string | undefined {
  // буквальный сегмент точнее переменного, поэтому такие шаблоны пробуются первыми
  const ordered = [...routes].sort((a, b) => Number(a.includes("[")) - Number(b.includes("[")));
  return ordered.find((pattern) => fits(pattern, url));
}

console.log(pick("/products/new"));
console.log(pick("/products/42"));

страница примера

Сначала предположите, что выведет код

Правило запоминается легко: чем меньше в шаблоне скобок, тем он точнее. Поэтому форма создания живёт в app/products/new/page.tsx и спокойно соседствует с [id] — до динамической папки очередь дойдёт только тогда, когда буквального совпадения не нашлось.

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

ts

function match(pattern: string, url: string): Record<string, string> {
  const parts = pattern.split("/").filter(Boolean);
  const segments = url.split("/").filter(Boolean);
  const params: Record<string, string> = {};
  parts.forEach((part, i) => {
    if (part.startsWith("[")) params[part.slice(1, -1)] = segments[i];
  });
  return params;
}

console.log(match("/shop/[category]/[id]", "/shop/tea/42"));

страница примера

Сначала предположите, что выведет код

Скобки — часть имени папки, а не какая-то особая запись в конфиге. В терминале такое имя иногда приходится брать в кавычки: mkdir "[id]" — иначе оболочка попробует прочитать скобки по-своему.

До Next.js 15 params был обычным объектом: params.id — и всё. В 15-й версии этот проп (вместе с searchParams) стал асинхронным, и старая привычка ломается сразу. Хорошая новость: ломается она громко.

ts

type PageProps = { params: Promise<{ id: string }> };

function ProductPage({ params }: PageProps) {
  // привычка из Next 14: params читают как обычный объект
  console.log("товар " + params.id);
}

ProductPage({ params: Promise.resolve({ id: "42" }) });

страница примера

Сначала предположите, что выведет код

Диагностика описывает случившееся дословно: Свойство "id" не существует в типе "Promise<{ id: string; }>". И всё же код выполнился, напечатав undefined: ошибки типов запуск не отменяют — типы живут до сборки, а в браузер уезжает обычный JavaScript. Об этом подробно говорилось в части III.

Лечение видно из самой ошибки: промис надо дождаться. Компонент страницы для этого объявляют асинхронной функцией — серверные компоненты так умеют. Почему асинхронным бывает только серверный компонент, разбирает статья «Данные прямо в компоненте: await вместо useEffect» в следующей главе.

ts

type PageProps = { params: Promise<{ id: string }> };

// страница может быть асинхронной функцией: серверный компонент умеет ждать
async function ProductPage({ params }: PageProps) {
  const { id } = await params;
  console.log("товар " + id);
  console.log(id + 1);
}

ProductPage({ params: Promise.resolve({ id: "42" }) });

страница примера

Сначала предположите, что выведет код

Вторая строка вывода — 421, а не 43. Адрес состоит из строк, и [id] не превращает 42 в число: это по-прежнему текст, который вы вытащили из URL. Проверка и разбор — ваша работа, к ней вернёмся в последнем разделе.

export default перед функцией страницы здесь снова опущен — почему, разбиралось в статье про App Router.

Зачем вообще было делать проп промисом? Чтобы отрисовка могла начаться раньше, чем известны детали запроса: общий каркас страницы уходит в браузер сразу, а место, которому нужен конкретный адрес, дожидается своего значения отдельно. Обещание вместо готового объекта — способ отодвинуть этот момент, и чем позже странице действительно понадобится адрес, тем больше успевает уехать до него.

В клиентском компоненте await не поставишь: функция с "use client" асинхронной быть не может. Зато есть use() из статьи про use() и Suspense — он разворачивает промис прямо в теле компонента.

tsx

// в настоящем файле сверху стоит "use client": асинхронной такая функция быть не может
function ProductPage({ params }: { params: Promise<{ id: string }> }) {
  console.log("вызов компонента");
  // use() разворачивает промис прямо в теле компонента
  const { id } = React.use(params);
  console.log("параметр прочитан: " + id);
  return <h1>Товар {id}</h1>;
}

// обычно этот проп даёт Next; здесь промис делаем руками
const params = Promise.resolve({ id: "42" });

ReactDOM.createRoot(document.getElementById("root")!).render(
  <React.Suspense fallback={<p>Загрузка…</p>}>
    <ProductPage params={params} />
  </React.Suspense>
);

страница примера

Сначала предположите, что выведет код

Строк «вызов компонента» две, а «параметр прочитан» — одна. Первый раз функция дошла до use(), промис ещё не был выполнен, и React приостановил отрисовку, показав запасную разметку из Suspense. Когда промис выполнился, React вызвал компонент заново — и на этот раз use() вернул значение. Это ровно то поведение, которое разбиралось в статье про use() и Suspense: никакого особого «получения параметров» в React не завелось.

Документация, файловое хранилище, старые адреса из чужой CMS — там, где глубина пути заранее неизвестна, одного [id] мало. Многоточие перед именем делает сегмент «съедающим»: [...slug] забирает всё, что осталось от адреса, и отдаёт массивом.

ts

// [...slug] забирает весь остаток адреса и отдаёт его массивом
function catchAll(base: string, url: string): { slug: string[] } | null {
  if (!url.startsWith(base + "/")) return null;
  return { slug: url.slice(base.length + 1).split("/") };
}

console.log(catchAll("/docs", "/docs/react"));
console.log(catchAll("/docs", "/docs/react/hooks/use-state"));
console.log(catchAll("/docs", "/docs"));

страница примера

Сначала предположите, что выведет код

Последняя строка — то самое место, где спотыкаются: [...slug] требует хотя бы один сегмент, поэтому сам /docs под него не подходит и отвечает 404. Чтобы папка ловила и родительский адрес, скобки удваивают.

ts

type Params = { slug?: string[] };

// двойные скобки: сегментов может не быть вовсе
function optionalCatchAll(base: string, url: string): Params | null {
  if (url === base) return { slug: undefined };
  if (!url.startsWith(base + "/")) return null;
  return { slug: url.slice(base.length + 1).split("/") };
}

console.log(optionalCatchAll("/docs", "/docs"));
console.log(optionalCatchAll("/docs", "/docs/react"));

// поэтому длину читают только после проверки — иначе падение уже в браузере
const params = optionalCatchAll("/docs", "/docs");
console.log(params?.slug?.length ?? 0);

страница примера

Сначала предположите, что выведет код

Разница не только в адресах, но и в типе: у [...slug] это string[], у [[...slug]] — string[] | undefined. Отсюда и главная ловушка: params.slug.length на корневом адресе падает. В примере поэтому и стоит ?., а что скажет компилятор без такой осторожности — видно в первой задаче в конце статьи.

Папка	Какие адреса ловит	params
`[id]`	`/docs/react`	`{ id: "react" }`
`[id]`	`/docs` и `/docs/a/b`	не ловит — 404
`[...slug]`	`/docs/a`, `/docs/a/b`	`{ slug: ["a"] }`, `{ slug: ["a", "b"] }`
`[...slug]`	`/docs`	не ловит — 404
`[[...slug]]`	`/docs`	`{ slug: undefined }`
`[[...slug]]`	`/docs/a/b`	`{ slug: ["a", "b"] }`

Съедающий сегмент всегда последний в своей ветке: класть что-то глубже бессмысленно — до этого места очередь не дойдёт, всё уже съедено. И в очерёдности он проигрывает всем: сначала буквальные сегменты, потом [id], и только потом [...slug].

Строку запроса ?tag=react&sort=new папками не опишешь — под неё и нет папок. Next разбирает её сам и отдаёт странице вторым пропом, searchParams, тоже промисом. Тип у него на первый взгляд странный: { [key: string]: string | string[] | undefined }.

Три варианта — потому что ключ в адресе может встретиться ноль раз, один раз или несколько. Соберём такой объект сами, и станет видно, откуда берётся массив.

ts

type SearchParams = { [key: string]: string | string[] | undefined };

// так строку запроса разбирает Next — отсюда и такой тип у пропа
function parseQuery(query: string): SearchParams {
  const result: SearchParams = {};
  for (const pair of query.split("&")) {
    const [key, value] = pair.split("=");
    const current = result[key];
    if (current === undefined) result[key] = value;
    else if (Array.isArray(current)) current.push(value);
    else result[key] = [current, value];
  }
  return result;
}

const searchParams = parseQuery("tag=react&tag=next&sort=new");
console.log(searchParams.sort);
console.log(searchParams.tag);
console.log(searchParams.page);

страница примера

Сначала предположите, что выведет код

Именно поэтому нельзя просто передать значение туда, где ждут строку: компилятор помнит про все три случая, даже если вы про них забыли.

ts

type SearchParams = { [key: string]: string | string[] | undefined };

function title(tag: string): string {
  return "Метка: " + tag;
}

const searchParams: SearchParams = { tag: ["react", "next"] };
console.log(title(searchParams.tag));

страница примера

Сначала предположите, что выведет код

Выполнение при этом прошло и напечатало «Метка: react,next» — массив тихо склеился в строку. Такие места и есть причина, по которой в части III столько внимания уделено сужению: разбирать варианты приходится руками.

ts

type SearchParams = { [key: string]: string | string[] | undefined };

// сужение из части III: три варианта — три ветки, никаких приведений типов
function firstValue(raw: string | string[] | undefined, fallback: string): string {
  if (raw === undefined) return fallback;
  return Array.isArray(raw) ? raw[0] : raw;
}

const searchParams: SearchParams = { tag: ["react", "next"], sort: "new" };
console.log(firstValue(searchParams.tag, "все"));
console.log(firstValue(searchParams.sort, "по дате"));
console.log(firstValue(searchParams.page, "1"));

страница примера

Сначала предположите, что выведет код

searchParams получает только page.tsx. Раскладке этот проп не дают: она не перерисовывается, когда меняется строка запроса, и данные из неё вводили бы в заблуждение.

Ещё одно различие стоит держать в голове. Значения из params можно узнать на сборке — для этого их перечисляют сами, функцией generateStaticParams из последнего раздела, и тогда страницы отрисовываются заранее. Строка запроса такой возможности не даёт вовсе: она известна только в момент запроса, и обращение к searchParams делает страницу динамической.

Пропсы params и searchParams приходят только компоненту страницы. Пробрасывать их вниз через десять уровней не обязательно: у клиентских компонентов есть хуки useParams() и useSearchParams() — они из следующей статьи, про переходы и роутер. Для серверной части выбор проще: передать значение пропсом сверху.

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

Хлопот прибавляется, когда параметров в адресе больше пары и клиент их не только читает, но и меняет: фильтр, сортировка, номер страницы. Тогда на каждый параметр приходится своё сужение типа и умолчание, как в firstValue, и своя запись обратно в адрес. Чем заменяют эти копии одного и того же кода, разобрано на полке React и Next.

[id] не проверяет ничего. /products/42, /products/kettle, /products/%D1%87%D0%B0%D0%B9 — все они дойдут до вашей страницы, и различать их придётся самим. Типизация тут не помощник: params.id честно объявлен строкой, потому что строкой и приходит.

ts

type Params = { id: string };

// для маршрутизатора /products/42 и /products/kettle одинаковы: он не проверяет ничего
function toProductId(params: Params): number | null {
  const id = Number(params.id);
  return Number.isInteger(id) && id > 0 ? id : null;
}

console.log(toProductId({ id: "42" }));
console.log(toProductId({ id: "kettle" }));
console.log(toProductId({ id: "42.5" }));
console.log(toProductId({ id: "0" }));

страница примера

Сначала предположите, что выведет код

Дальше на выбор: показать сообщение, отдать 404 или увести на другой адрес. Настоящая страница целиком выглядит так — этот пример компилируется, но не запускается: notFound() живёт в пакете next/navigation, а импортов песочница не знает.

tsx

// app/products/[id]/page.tsx целиком — этот пример песочница не запускает
type PageProps = { params: Promise<{ id: string }> };

async function ProductPage({ params }: PageProps) {
  const { id } = await params;
  const productId = Number(id);
  if (!Number.isInteger(productId)) {
    // в настоящем файле здесь вызывают notFound() из "next/navigation":
    // отрисовка прерывается и показывается not-found.tsx
    return <p>Такого товара нет</p>;
  }
  return <h1>Товар {productId}</h1>;
}

страница примера

Сначала предположите, что выведет код

Файлы not-found.tsx и error.tsx, которые подхватывают такой обрыв, разбирает последняя статья главы. Здесь важнее другое: решение о том, что считать несуществующим товаром, принимает страница, а не маршрутизатор.

Есть и обратный ход — заранее перечислить допустимые значения. Функция generateStaticParams рядом со страницей отдаёт список сегментов, для которых Next соберёт готовые страницы на сборке.

ts

// эту функцию Next вызывает на сборке: она перечисляет значения сегмента [id]
async function generateStaticParams(): Promise<{ id: string }[]> {
  const ids = [1, 2, 3];
  // ключ — имя сегмента, значение всегда строка: адрес состоит из строк
  return ids.map((id) => ({ id: String(id) }));
}

generateStaticParams().then((list) => console.log(list));

страница примера

Сначала предположите, что выведет код

Форма ответа та же, что у params: массив объектов, где ключ — имя сегмента, а значение — строка. Для каталога из трёх товаров это три собранных заранее страницы; всё остальное по-прежнему обрабатывается на лету — или отвечает 404, если вы это запретили. Подробности статической сборки и кеширования ждут в главе про кеш и отдачу.

Квадратные скобки в имени папки делают сегмент переменной: [id] подходит под любое значение, а имя внутри скобок становится ключом в params.
Обычный динамический сегмент занимает ровно один кусок пути; буквальная папка рядом с ним всегда точнее и выигрывает спор за адрес.
[...slug] забирает весь остаток адреса массивом, но требует хотя бы один сегмент; [[...slug]] ловит и родительский адрес, отдавая slug: undefined.
С Next.js 15 params и searchParams — промисы: в серверном компоненте их ждут через await, в клиентском разворачивают через use().
У searchParams тип string | string[] | undefined: ключ мог повториться или не прийти вовсе, поэтому перед использованием его сужают.
Маршрутизатор не проверяет значения — всё приезжает строками; разбор, отказ через notFound() и список заранее собираемых адресов в generateStaticParams пишет сама страница.

1/4В проекте есть app/products/[id]/page.tsx и больше ничего внутри products. По каким адресам откроется эта страница?

2/4В компоненте объявлено params: Promise<{ id: string }>, а внутри написано console.log(params.id). Что увидит читатель после запуска?

3/4Папка называется app/docs/[[...slug]]. Что придёт в params по адресу /docs?

4/4Открыт адрес /list?tag=react&tag=next. Что окажется в searchParams.tag?

Хлебные крошки падают на корне

Папка документации называется [[...slug]], поэтому адрес /docs тоже её. Функция breadcrumbs собирает путь из сегментов, но на корне ломается — и компилятор об этом честно предупреждает. Почините её так, чтобы для корня возвращалось слово «Документация».

ts

type Params = { slug?: string[] };

// адрес /docs существует: папка называется [[...slug]]
function breadcrumbs(params: Params): string {
  return params.slug.join(" / ");
}

console.log(breadcrumbs({ slug: ["react", "hooks"] })); // react / hooks
console.log(breadcrumbs({ slug: undefined })); // а здесь всё ломается

страница примера

Сначала предположите, что выведет код

Тип string[] | undefined надо разобрать до обращения к массиву. Пустой список — это и есть корень раздела.

tsлистинг · не запускается

function breadcrumbs(params: Params): string {
  // корню документации соответствует пустой список сегментов
  const parts = params.slug ?? [];
  return parts.length > 0 ? parts.join(" / ") : "Документация";
}

console.log(breadcrumbs({ slug: ["react", "hooks"] })); // react / hooks
console.log(breadcrumbs({ slug: undefined })); // Документация

function breadcrumbs(params: Params): string {
  // корню документации соответствует пустой список сегментов
  const parts = params.slug ?? [];
  return parts.length > 0 ? parts.join(" / ") : "Документация";
}

console.log(breadcrumbs({ slug: ["react", "hooks"] })); // react / hooks
console.log(breadcrumbs({ slug: undefined })); // Документация

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

Прочитать оба пропа страницы

Компонент получает params и searchParams — оба промисами. Напишите тело describe: она должна вернуть строку «товар <id>, вкладка <tab>». Вкладка приходит из строки запроса, может оказаться массивом (тогда берём первое значение) или не прийти вовсе — тогда подставляем about.

ts

type PageProps = {
  params: Promise<{ id: string }>;
  searchParams: Promise<{ [key: string]: string | string[] | undefined }>;
};

async function describe(props: PageProps): Promise<string> {
  // ваш код: вернуть строку вида «товар 42, вкладка reviews»
  return "";
}

describe({
  params: Promise.resolve({ id: "42" }),
  searchParams: Promise.resolve({ tab: "reviews" })
}).then((line) => console.log(line)); // нужно: товар 42, вкладка reviews

describe({
  params: Promise.resolve({ id: "7" }),
  searchParams: Promise.resolve({ tab: ["a", "b"] })
}).then((line) => console.log(line)); // нужно: товар 7, вкладка a

describe({
  params: Promise.resolve({ id: "7" }),
  searchParams: Promise.resolve({})
}).then((line) => console.log(line)); // нужно: товар 7, вкладка about

страница примера

Сначала предположите, что выведет код

Два независимых промиса ждут разом — Promise.all экономит один такт по сравнению с двумя await подряд. Дальше обычное сужение из части III.

jsлистинг · не запускается

async function describe(props: PageProps): Promise<string> {
  // промисы независимы, поэтому их ждут разом, а не по очереди
  const [{ id }, query] = await Promise.all([props.params, props.searchParams]);
  const raw = query.tab;
  const tab = raw === undefined ? "about" : Array.isArray(raw) ? raw[0] : raw;
  return "товар " + id + ", вкладка " + tab;
}

async function describe(props: PageProps): Promise<string> {
  // промисы независимы, поэтому их ждут разом, а не по очереди
  const [{ id }, query] = await Promise.all([props.params, props.searchParams]);
  const raw = query.tab;
  const tab = raw === undefined ? "about" : Array.isArray(raw) ? raw[0] : raw;
  return "товар " + id + ", вкладка " + tab;
}

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

Научить сопоставление съедающему сегменту

Функция fits знает про буквальные и обычные динамические сегменты, но не знает про [...rest]: она сравнивает количество кусков и потому отбрасывает длинные адреса. Доработайте её так, чтобы съедающий сегмент подходил под любой непустой остаток пути.

ts

const patterns = ["/blog/new", "/blog/[slug]", "/blog/[...rest]"];

function fits(pattern: string, url: string): boolean {
  const parts = pattern.split("/");
  const segments = url.split("/");
  if (parts.length !== segments.length) return false;
  return parts.every((part, i) => part.startsWith("[") || part === segments[i]);
}

function pick(url: string): string {
  return patterns.find((pattern) => fits(pattern, url)) ?? "404";
}

console.log(pick("/blog/new")); // /blog/new
console.log(pick("/blog/react")); // /blog/[slug]
console.log(pick("/blog/react/hooks")); // сейчас 404, а нужно /blog/[...rest]

страница примера

Сначала предположите, что выведет код

Меняется только проверка длины: у съедающего шаблона адрес может быть длиннее, но не короче — хотя бы один кусок ему нужен.

tsлистинг · не запускается

function fits(pattern: string, url: string): boolean {
  const parts = pattern.split("/");
  const segments = url.split("/");
  const greedy = parts[parts.length - 1].startsWith("[...");
  // съедающий сегмент подходит под один кусок адреса или под несколько,
  // обычный — ровно под один
  if (greedy ? segments.length < parts.length : segments.length !== parts.length) return false;
  return parts.every((part, i) => part.startsWith("[") || part === segments[i]);
}

console.log(pick("/blog/react/hooks")); // /blog/[...rest]
console.log(pick("/blog")); // 404

function fits(pattern: string, url: string): boolean {
  const parts = pattern.split("/");
  const segments = url.split("/");
  const greedy = parts[parts.length - 1].startsWith("[...");
  // съедающий сегмент подходит под один кусок адреса или под несколько,
  // обычный — ровно под один
  if (greedy ? segments.length < parts.length : segments.length !== parts.length) return false;
  return parts.every((part, i) => part.startsWith("[") || part === segments[i]);
}

console.log(pick("/blog/react/hooks")); // /blog/[...rest]
console.log(pick("/blog")); // 404

Порядок в массиве шаблонов при этом остаётся значимым: /blog/new стоит первым и выигрывает у [slug], а [...rest] — последним, как и в самом Next.

Динамические сегменты и асинхронные params

Видеоразбор темы за 5–7 минут

[id]Папка, чьё имя — переменная

params приезжает промисомПочему без await ничего не читается

[...slug] и [[...slug]]Сегмент, который забирает весь остаток пути

searchParamsСтрока запроса не живёт в дереве папок

Сегмент принимает всёПроверка значения — ваша работа, а не маршрутизатора

Итогошпаргалка по теме

Проверьте себявопросы по теме

Задачизадачи с решениями

Хлебные крошки падают на корне

Прочитать оба пропа страницы

Научить сопоставление съедающему сегменту