Next.js: Navegação: Link e API Programática

// Navegação Otimizada na Página de Lista de Produtos
<Link
  href={`/products/${product.id}`}
  prefetch={true}
  scroll={false}
  className="block p-4 border rounded hover:shadow"
>
  {product.title}
</Link>

Diagrama da navegação no lado do cliente usando o componente Link.

// ============================================
// Uso Básico do Componente Link
// ============================================

import Link from "next/link";

export default function Navigation() {
  return (
    <nav className="flex gap-6 p-4 bg-white shadow-sm">
      {/* Navegação Básica */}
      <Link href="/" className="text-blue-600 hover:underline">
        Início
      </Link>

      {/* Roteamento Dinâmico */}
      <Link href="/products/42" className="text-blue-600 hover:underline">
        Produto 42
      </Link>

      {/* Com parâmetros de consulta */}
      <Link
        href="/products?category=electronics&sort=price"
        className="text-blue-600 hover:underline"
      >
        Eletrônicos
      </Link>

      {/* URL Completa */}
      <Link
        href="https://help.example.com"
        className="text-blue-600 hover:underline"
      >
        Central de Ajuda
      </Link>
    </nav>
  );
}

Renderiza: Links de navegação usando o componente Link do Next.js para roteamento no lado do cliente.

O navegador exibe 4 links azuis:
Início → / 
Produto 42 → /products/42
Eletrônicos → /products?category=electronics&sort=price
Central de Ajuda → https://help.example.com (Link Externo)

A página renderiza conforme descrito acima, com a UI atualizando com base no comportamento descrito.

// ============================================
// Controlar o Comportamento de Prefetch do Link
// ============================================

import Link from "next/link";

export default function ProductList() {
  const products = [
    { id: 1, name: "Mouse Sem Fio" },
    { id: 2, name: "Teclado" },
    { id: 3, name: "Monitor" },
  ];

  return (
    <div className="p-8">
      <h1 className="text-2xl font-bold mb-4">Produtos</h1>

      {/* prefetch padrão: pré-carrega automaticamente links dentro da viewport */}
      {products.map(p => (
        <Link
          key={p.id}
          href={`/products/${p.id}`}
          className="block p-4 border-b hover:bg-gray-50"
        >
          {p.name}
        </Link>
      ))}

      {/* Desativar prefetch: Adequado para páginas não usadas com frequência */}
      <Link
        href="/archive"
        prefetch={false}
        className="block mt-4 text-gray-500"
      >
        Ver Arquivo (produtos antigos)
      </Link>

      {/* Prefetch Forçado: Adequado para a próxima página que você está prestes a visitar */}
      <Link
        href="/checkout"
        prefetch={true}
        className="block mt-4 px-6 py-2 bg-blue-600 text-white text-center rounded"
      >
        Ir para o Checkout
      </Link>
    </div>
  );
}

Mapeia os produtos para renderizar a lista.
Conteúdo: Produtos

Após o carregamento da página, isso pode ser observado no console de rede:
1. /products/1, /products/2, /products/3 Pré-buscados (dentro da viewport)
2. /archive Não pré-buscado (prefetch={false})
3. /checkout Pré-buscado (prefetch={true}, mesmo não estando na viewport)

Quando um usuário clica no link:
- Páginas pré-buscadas → Exibição em Tempo Real (lidas do cache)
- Páginas Não Pré-buscadas → Exibidas após a requisição de rede

Diagrama: Gatilho de Navegação; Rolar para o topo da nova página; Manter a posição de rolagem atual.

// ============================================
// Lista de Produtos + Janela Modal: scroll=false Mantém a lista no lugar
// Usuários clicam em um produto para ver seus detalhes, a lista não rola ao retornar
// ============================================

import Link from "next/link";

export default function ProductGrid() {
  const products = Array.from({ length: 20 }, (_, i) => ({
    id: i + 1,
    name: `Produto ${i + 1}`,
  }));

  return (
    <div className="p-8">
      <h1 className="text-2xl font-bold mb-6">Catálogo de Produtos</h1>
      <div className="grid grid-cols-4 gap-4">
        {products.map(p => (
          <Link
            key={p.id}
            href={`/products/${p.id}`}
            scroll={false}
            className="border p-4 rounded hover:shadow-lg"
          >
            <div className="h-32 bg-gray-100 rounded" />
            <p className="mt-2 font-medium">{p.name}</p>
          </Link>
        ))}
      </div>
    </div>
  );
}

Mapeia os produtos para renderizar a lista.
Conteúdo: Catálogo de Produtos

1. O usuário rolou até o 3º item por página (Rolou 2000px para baixo)
2. Clica no 15º produto para ir à página de detalhes
3. Clica no botão Voltar do navegador
4. Volta para a página de lista, mantém a posição de rolagem em 2000px (Sem "Voltar ao Topo")
5. Comparação: Sem scroll={false}, retorna ao topo toda vez

O componente renderiza a UI descrita no navegador.

// ============================================
// replace Substituição de Histórico: Você não pode retornar à página do formulário após enviar.
// ============================================

import Link from "next/link";

export default function CheckoutPage() {
  return (
    <div className="max-w-md mx-auto p-8">
      <h1 className="text-2xl font-bold mb-6">Checkout</h1>

      <div className="space-y-4">
        <input placeholder="Número do cartão" className="w-full p-3 border rounded" />
        <input placeholder="Data de validade" className="w-full p-3 border rounded" />
        <input placeholder="CVV" className="w-full p-3 border rounded" />
      </div>

      {/* Usando replace: Uma vez enviado, você não pode retornar a esta página. */}
      <Link
        href="/order-confirmation"
        replace
        className="block mt-6 w-full p-3 bg-blue-600 text-white text-center rounded"
      >
        Finalizar Pedido
      </Link>

      <p className="text-sm text-gray-500 mt-2 text-center">
        Após finalizar o pedido, o botão voltar pulará esta página
      </p>
    </div>
  );
}

Conteúdo: Checkout | Finalizar Pedido | Após finalizar o pedido, o botão voltar pu

Fluxo do Usuário:
1. Início → Carrinho de Compras → Checkout → Página de Confirmação
2. Toque em "Finalizar Pedido" na página de checkout
3. O endereço do navegador muda para /order-confirmation
4. O usuário clica no botão Voltar
5. Pula a página de checkout, vai diretamente para o carrinho de compras
6. Evita que usuários retornem acidentalmente à página de checkout e enviem o pedido novamente

Diagrama da navegação no lado do cliente usando o componente Link.

// ============================================
// Exemplo Completo de Navegação Programática com useRouter
// ============================================

'use client';

import { useRouter } from "next/navigation";

export default function NavigationBar({ userId }: { userId: string }) {
  const router = useRouter();

  return (
    <div className="p-4 bg-white shadow-sm">
      <div className="flex gap-4 max-w-4xl mx-auto">
        {/* push: Ir para a Página Inicial */}
        <button
          onClick={() => router.push("/")}
          className="px-4 py-2 bg-blue-600 text-white rounded"
        >
          Início
        </button>

        {/* push: Roteamento Dinâmico */}
        <button
          onClick={() => router.push(`/users/${userId}`)}
          className="px-4 py-2 bg-gray-600 text-white rounded"
        >
          Perfil
        </button>

        {/* replace: Substituir a página atual */}
        <button
          onClick={() => router.replace("/login")}
          className="px-4 py-2 bg-red-600 text-white rounded"
        >
          Sair
        </button>

        {/* back/forward: Histórico de Navegação */}
        <button
          onClick={() => router.back()}
          className="px-4 py-2 border rounded"
        >
          ← Voltar
        </button>
        <button
          onClick={() => router.forward()}
          className="px-4 py-2 border rounded"
        >
          Avançar →
        </button>

        {/* refresh: Atualizar esta página (Re-renderização no Servidor) */}
        <button
          onClick={() => router.refresh()}
          className="px-4 py-2 border rounded"
        >
          Atualizar ↻
        </button>
      </div>
    </div>
  );
}

NavigationBar renderiza sua UI.

Clique em cada botão:
[Início]    → Navega para /
[Perfil]    → Navega para /users/123
[Sair]      → Substitui o histórico atual por /login (Sem Retorno)
[← Voltar]  → Botão Voltar do Navegador
[Avançar]   → Botão Avançar do Navegador
[Atualizar] → Atualiza esta página (RSC Renderiza Novamente, Não causa recarregamento completo da página)

A página renderiza conforme descrito acima, com a UI atualizando com base no comportamento descrito.

// ============================================
// Envio de Formulário: Verificação → salvar → Navegação Programática
// ============================================

'use client';

import { useRouter } from "next/navigation";
import { useState } from "react";

export default function CreateProjectForm() {
  const router = useRouter();
  const [saving, setSaving] = useState(false);

  async function handleSubmit(e: React.FormEvent) {
    e.preventDefault();
    setSaving(true);

    try {
      // Simulação de Chamada API
      await new Promise(resolve => setTimeout(resolve, 1500));
      // Após conclusão bem-sucedida, navega para a página do novo projeto
      router.push("/projects/42");
      // e atualiza o cache de dados
      router.refresh();
    } catch (err) {
      console.error("Falha ao criar projeto:", err);
      alert("Falha ao criar projeto. Por favor, tente novamente.");
    } finally {
      setSaving(false);
    }
  }

  return (
    <form onSubmit={handleSubmit} className="max-w-lg mx-auto p-8 space-y-4">
      <h1 className="text-2xl font-bold">Criar Projeto</h1>
      <input
        name="name"
        placeholder="Nome do projeto"
        className="w-full p-3 border rounded"
        required
      />
      <textarea
        name="description"
        placeholder="Descrição"
        className="w-full p-3 border rounded h-32"
      />
      <button
        type="submit"
        disabled={saving}
        className="w-full p-3 bg-blue-600 text-white rounded disabled:opacity-50"
      >
        {saving ? "Criando..." : "Criar Projeto"}
      </button>
    </form>
  );
}

Formulário com: name.
Conteúdo: Criar Projeto

1. O usuário insere o nome e a descrição do projeto
2. Clica no botão "Criar Projeto"
3. O botão muda para "Criando..." (Desabilitado)
4. Após 1,5s (atraso simulado da API)
5. Navegação da Página para /projects/42
6. Atualiza os Dados da Lista de Projetos (Inclui projetos recém-criados)

// ============================================
// Exemplo Abrangente: Um Sistema de Navegação Completo para E-commerce
// Cobrindo Link, useRouter, redirect, Estado de Carregamento de Navegação
// ============================================

// src/app/layout.tsx — Barra de Navegação Global
import Link from "next/link";
import { CartCount } from "./CartCount";

export default function RootLayout({ children }) {
  return (
    <html lang="pt-BR">
      <body>
        <header className="bg-white shadow-sm sticky top-0 z-40">
          <div className="max-w-6xl mx-auto px-4 py-3 flex items-center justify-between">
            <Link href="/" className="text-2xl font-bold text-blue-600">
              ShopHub
            </Link>

            <nav className="hidden md:flex gap-6">
              <Link href="/products" className="hover:text-blue-600">
                Produtos
              </Link>
              <Link href="/categories" className="hover:text-blue-600">
                Categorias
              </Link>
              <Link href="/deals" prefetch={false} className="hover:text-blue-600">
                Ofertas
              </Link>
              <Link href="/about" className="hover:text-blue-600">
                Sobre
              </Link>
            </nav>

            <div className="flex items-center gap-4">
              <Link href="/search" className="text-gray-600 hover:text-blue-600">
                Buscar
              </Link>
              <Link href="/cart" className="relative text-gray-600 hover:text-blue-600">
                Carrinho
                <CartCount />
              </Link>
              <Link
                href="/account"
                className="px-4 py-2 bg-blue-600 text-white rounded-lg text-sm"
              >
                Entrar
              </Link>
            </div>
          </div>
        </header>

        <main className="max-w-6xl mx-auto px-4 py-8">
          {children}
        </main>
      </body>
    </html>
  );
}

// src/app/products/[id]/page.tsx — Detalhes do Produto (Inclui lógica de navegação)
'use client';
import { useRouter } from "next/navigation";
import Link from "next/link";

export default function ProductDetail({ params }) {
  const router = useRouter();

  async function handleAddToCart() {
    await fetch("/api/cart", {
      method: "POST",
      body: JSON.stringify({ productId: params.id }),
    });
    // Atualiza a quantidade no carrinho de compras após adicionar um item
    router.refresh();
  }

  async function handleBuyNow() {
    await fetch("/api/cart", {
      method: "POST",
      body: JSON.stringify({ productId: params.id, quantity: 1 }),
    });
    // Comprar Agora → Ir para o Checkout (usa replace para evitar retornar à página do produto)
    router.replace("/checkout");
  }

  return (
    <div>
      {/* Navegação Breadcrumb */}
      <nav className="text-sm text-gray-500 mb-6">
        <Link href="/" className="hover:text-blue-600">Início</Link>
        <span className="mx-2">/</span>
        <Link href="/products" className="hover:text-blue-600">Produtos</Link>
        <span className="mx-2">/</span>
        <span className="text-gray-900">{params.id}</span>
      </nav>

      <div className="flex gap-8">
        <div className="w-1/2">
          <img
            src={`https://picsum.photos/seed/${params.id}/400/400`}
            alt="Produto"
            className="w-full rounded-lg"
          />
        </div>
        <div className="w-1/2">
          <h1 className="text-3xl font-bold">Produto #{params.id}</h1>
          <p className="text-2xl text-green-600 font-bold mt-4">R$ 49,99</p>
          <p className="text-gray-600 mt-4">
            Produto de alta qualidade com recursos premium.
          </p>

          <div className="flex gap-4 mt-8">
            <button
              onClick={handleAddToCart}
              className="flex-1 px-6 py-3 border-2 border-blue-600 text-blue-600 rounded-lg hover:bg-blue-50"
            >
              Adicionar ao Carrinho
            </button>
            <button
              onClick={handleBuyNow}
              className="flex-1 px-6 py-3 bg-blue-600 text-white rounded-lg hover:bg-blue-700"
            >
              Comprar Agora
            </button>
          </div>

          <div className="mt-8 border-t pt-6">
            <Link
              href={`/products/${Number(params.id) - 1}`}
              scroll={false}
              className="text-blue-600 hover:underline"
            >
              ← Produto Anterior
            </Link>
            <Link
              href={`/products/${Number(params.id) + 1}`}
              scroll={false}
              className="text-blue-600 hover:underline float-right"
            >
              Próximo Produto →
            </Link>
          </div>
        </div>
      </div>
    </div>
  );
}

// src/app/CartCount.tsx — Exibição da Quantidade no Carrinho de Compras
export async function CartCount() {
  const cart = await fetch("https://api.example.com/cart");
  const itemCount = cart?.items?.length ?? 0;

  if (itemCount === 0) return null;

  return (
    <span className="absolute -top-2 -right-2 bg-red-500 text-white text-xs w-5 h-5 rounded-full flex items-center justify-center">
      {itemCount}
    </span>
  );
}

Barra de Navegação (Fixada no topo):
[ShopHub]  Produtos  Categorias  Ofertas  Sobre  [Buscar]  Carrinho(3)  [Entrar]

Página de Detalhes do Produto (/products/1):
Início / Produtos / 1
[Imagens do Produto]  [Detalhes do Produto]
            Produto #1
            R$ 49,99
            [Adicionar ao Carrinho] [Comprar Agora]
            ← Produto Anterior | Próximo Produto →

Comportamento de Navegação:
- Clicar em Produtos → Soft Nav, Troca Instantânea de Página
- Clicar em Ofertas → Sem pré-busca (prefetch=false), Mas a navegação ainda é rápida
- Adicionar ao Carrinho → router.refresh(), Atualização do Ícone do Carrinho
- Comprar Agora → router.replace("/checkout"), Substituição de Histórico