Next.js: التنقل: Link وواجهة برمجة التطبيقات البرمجية

// تنقل محسّن في صفحة قائمة المنتجات
<Link
  href={`/products/${product.id}`}
  prefetch={true}
  scroll={false}
  className="block p-4 border rounded hover:shadow"
>
  {product.title}
</Link>

رسم توضيحي للتنقل من جانب العميل باستخدام مكوّن Link.

// ============================================
// الاستخدام الأساسي لمكوّنات Link
// ============================================

import Link from "next/link";

export default function Navigation() {
  return (
    <nav className="flex gap-6 p-4 bg-white shadow-sm">
      {/* تنقل أساسي */}
      <Link href="/" className="text-blue-600 hover:underline">
        الرئيسية
      </Link>

      {/* توجيه ديناميكي */}
      <Link href="/products/42" className="text-blue-600 hover:underline">
        المنتج 42
      </Link>

      {/* مع معاملات الاستعلام */}
      <Link
        href="/products?category=electronics&sort=price"
        className="text-blue-600 hover:underline"
      >
        إلكترونيات
      </Link>

      {/* رابط كامل */}
      <Link
        href="https://help.example.com"
        className="text-blue-600 hover:underline"
      >
        مركز المساعدة
      </Link>
    </nav>
  );
}

يعرض: روابط تنقل باستخدام مكوّن Link في Next.js للتوجيه من جانب العميل.

يعرض المتصفح 4 روابط زرقاء:
الرئيسية → / 
المنتج 42 → /products/42
إلكترونيات → /products?category=electronics&sort=price
مركز المساعدة → https://help.example.com(رابط خارجي)

يتم تصيير الصفحة كما هو موصوف أعلاه، مع تحديث واجهة المستخدم بناءً على السلوك الموصوف.

// ============================================
// التحكم في سلوك التحميل المسبق لـ Link
// ============================================

import Link from "next/link";

export default function ProductList() {
  const products = [
    { id: 1, name: "فأرة لاسلكية" },
    { id: 2, name: "لوحة مفاتيح" },
    { id: 3, name: "شاشة" },
  ];

  return (
    <div className="p-8">
      <h1 className="text-2xl font-bold mb-4">المنتجات</h1>

      {/* prefetch الافتراضي: تحميل مسبق تلقائي للروابط داخل نطاق العرض */}
      {products.map(p => (
        <Link
          key={p.id}
          href={`/products/${p.id}`}
          className="block p-4 border-b hover:bg-gray-50"
        >
          {p.name}
        </Link>
      ))}

      {/* إيقاف التحميل المسبق: مناسب للصفحات التي لا تُستخدم كثيرًا */}
      <Link
        href="/archive"
        prefetch={false}
        className="block mt-4 text-gray-500"
      >
        عرض الأرشيف (منتجات أقدم)
      </Link>

      {/* تحميل مسبق إجباري: مناسب للصفحة التالية التي أنت على وشك زيارتها */}
      <Link
        href="/checkout"
        prefetch={true}
        className="block mt-4 px-6 py-2 bg-blue-600 text-white text-center rounded"
      >
        متابعة إلى الدفع
      </Link>
    </div>
  );
}

يعرض قائمة المنتجات عبر التكرار.
المحتوى: المنتجات

بعد تحميل الصفحة، يمكن ملاحظة ذلك في وحدة تحكم الشبكة:
1. /products/1، /products/2، /products/3 تم جلبها مسبقًا (داخل نطاق العرض)
2. /archive لم يتم جلبها مسبقًا(prefetch={false})
3. /checkout تم جلبها مسبقًا(prefetch={true}، حتى لو لم تكن ضمن نطاق العرض)

عندما ينقر المستخدم على الرابط:
- الصفحات التي تم جلبها مسبقًا → عرض فوري(قراءة من ذاكرة التخزين المؤقت)
- الصفحات التي لم يتم جلبها مسبقًا → تُعرض بعد طلب الشبكة

رسم توضيحي: تشغيل التنقل؛ التمرير إلى أعلى الصفحة الجديدة؛ الحفاظ على موضع التمرير الحالي.

// ============================================
// قائمة المنتجات + نافذة منبثقة: scroll=false للحفاظ على القائمة في مكانها
// ينقر المستخدم على منتج لعرض تفاصيله، لا يتم التمرير عند العودة
// ============================================

import Link from "next/link";

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

  return (
    <div className="p-8">
      <h1 className="text-2xl font-bold mb-6">كتالوج المنتجات</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>
  );
}

يعرض قائمة المنتجات عبر التكرار.
المحتوى: كتالوج المنتجات

1. قام المستخدم بالتمرير إلى الصف الثالث(تم التمرير للأسفل 2000px)
2. النقر على المنتج 15 للانتقال إلى صفحة تفاصيل المنتج
3. النقر على زر الرجوع في المتصفح
4. العودة إلى صفحة القائمة، مع الحفاظ على موضع التمرير عند 2000px(لا يوجد "عودة إلى الأعلى")
5. للمقارنة: إذا لم يتم استخدام scroll={false}، سيتم العودة إلى الأعلى في كل مرة

يقوم المكوّن بتصيير واجهة المستخدم الموصوفة في المتصفح.

// ============================================
// replace استبدال السجل: لا يمكن العودة إلى صفحة النموذج بعد الإرسال
// ============================================

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">الدفع</h1>

      <div className="space-y-4">
        <input placeholder="رقم البطاقة" className="w-full p-3 border rounded" />
        <input placeholder="تاريخ الانتهاء" className="w-full p-3 border rounded" />
        <input placeholder="CVV" className="w-full p-3 border rounded" />
      </div>

      {/* استخدام replace: بمجرد الإرسال، لا يمكن العودة إلى هذه الصفحة */}
      <Link
        href="/order-confirmation"
        replace
        className="block mt-6 w-full p-3 bg-blue-600 text-white text-center rounded"
      >
        تقديم الطلب
      </Link>

      <p className="text-sm text-gray-500 mt-2 text-center">
        بعد تقديم الطلب، سيتجاوز زر الرجوع هذه الصفحة
      </p>
    </div>
  );
}

المحتوى: الدفع | تقديم الطلب | بعد تقديم الطلب، سيتجاوز زر الرجوع

تدفق المستخدم:
1. الرئيسية → سلة التسوق → الدفع → صفحة التأكيد
2. النقر على "تقديم الطلب" في صفحة الدفع
3. يتغير عنوان المتصفح إلى /order-confirmation
4. ينقر المستخدم على زر الرجوع
5. يتجاوز صفحة الدفع، وينتقل مباشرة إلى صفحة سلة التسوق
6. يمنع المستخدمين من العودة بطريق الخطأ إلى صفحة الدفع وإعادة تقديم الطلب

رسم توضيحي للتنقل من جانب العميل باستخدام مكوّن Link.

// ============================================
// 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: الانتقال إلى الصفحة الرئيسية */}
        <button
          onClick={() => router.push("/")}
          className="px-4 py-2 bg-blue-600 text-white rounded"
        >
          الرئيسية
        </button>

        {/* push: توجيه ديناميكي */}
        <button
          onClick={() => router.push(`/users/${userId}`)}
          className="px-4 py-2 bg-gray-600 text-white rounded"
        >
          الملف الشخصي
        </button>

        {/* replace: استبدال الصفحة الحالية */}
        <button
          onClick={() => router.replace("/login")}
          className="px-4 py-2 bg-red-600 text-white rounded"
        >
          تسجيل الخروج
        </button>

        {/* back/forward: سجل التصفح */}
        <button
          onClick={() => router.back()}
          className="px-4 py-2 border rounded"
        >
          ← رجوع
        </button>
        <button
          onClick={() => router.forward()}
          className="px-4 py-2 border rounded"
        >
          تقدم →
        </button>

        {/* refresh: تحديث هذه الصفحة(إعادة تصيير من جانب الخادم) */}
        <button
          onClick={() => router.refresh()}
          className="px-4 py-2 border rounded"
        >
          تحديث ↻
        </button>
      </div>
    </div>
  );
}

يقوم NavigationBar بتصيير واجهة المستخدم الخاصة به.

النقر على كل زر:
[الرئيسية]    → الانتقال إلى /
[الملف الشخصي] → الانتقال إلى /users/123
[تسجيل الخروج]  → استبدال السجل الحالي بـ /login(لا يمكن الرجوع)
[← رجوع]  → زر الرجوع في المتصفح
[تقدم] → زر التقدم في المتصفح
[تحديث] → تحديث هذه الصفحة(إعادة تصيير RSC، لا يتسبب في إعادة تحميل الصفحة بالكامل)

يتم تصيير الصفحة كما هو موصوف أعلاه، مع تحديث واجهة المستخدم بناءً على السلوك الموصوف.

// ============================================
// إرسال النموذج: التحقق → الحفظ → التنقل البرمجي
// ============================================

'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 {
      // محاكاة استدعاء API
      await new Promise(resolve => setTimeout(resolve, 1500));
      // بعد الانتهاء بنجاح، الانتقال إلى صفحة المشروع الجديد
      router.push("/projects/42");
      // وتحديث ذاكرة التخزين المؤقت للبيانات
      router.refresh();
    } catch (err) {
      console.error("فشل إنشاء المشروع:", err);
      alert("فشل إنشاء المشروع. يرجى المحاولة مرة أخرى.");
    } finally {
      setSaving(false);
    }
  }

  return (
    <form onSubmit={handleSubmit} className="max-w-lg mx-auto p-8 space-y-4">
      <h1 className="text-2xl font-bold">إنشاء مشروع</h1>
      <input
        name="name"
        placeholder="اسم المشروع"
        className="w-full p-3 border rounded"
        required
      />
      <textarea
        name="description"
        placeholder="الوصف"
        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 ? "جارٍ الإنشاء..." : "إنشاء مشروع"}
      </button>
    </form>
  );
}

نموذج يحتوي على: name.
المحتوى: إنشاء مشروع

1. يقوم المستخدم بإدخال اسم المشروع والوصف
2. النقر على زر "إنشاء مشروع"
3. يتغير الزر إلى "جارٍ الإنشاء..."(معطل)
4. بعد 1.5 ثانية (محاكاة تأخير API)
5. انتقال الصفحة إلى /projects/42
6. تحديث بيانات قائمة المشاريع(تشمل المشروع المنشأ حديثًا)

// ============================================
// مثال شامل: نظام تنقل متكامل للتجارة الإلكترونية
// يغطي Link وuseRouter وredirect وحالة تحميل التنقل
// ============================================

// src/app/layout.tsx — شريط تنقل عام
import Link from "next/link";
import { CartCount } from "./CartCount";

export default function RootLayout({ children }) {
  return (
    <html lang="en">
      <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">
                المنتجات
              </Link>
              <Link href="/categories" className="hover:text-blue-600">
                الفئات
              </Link>
              <Link href="/deals" prefetch={false} className="hover:text-blue-600">
                العروض
              </Link>
              <Link href="/about" className="hover:text-blue-600">
                حول
              </Link>
            </nav>

            <div className="flex items-center gap-4">
              <Link href="/search" className="text-gray-600 hover:text-blue-600">
                بحث
              </Link>
              <Link href="/cart" className="relative text-gray-600 hover:text-blue-600">
                السلة
                <CartCount />
              </Link>
              <Link
                href="/account"
                className="px-4 py-2 bg-blue-600 text-white rounded-lg text-sm"
              >
                تسجيل الدخول
              </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 — تفاصيل المنتج(تشمل منطق التنقل)
'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 }),
    });
    // تحديث العدد في سلة التسوق بعد إضافة عنصر
    router.refresh();
  }

  async function handleBuyNow() {
    await fetch("/api/cart", {
      method: "POST",
      body: JSON.stringify({ productId: params.id, quantity: 1 }),
    });
    // شراء الآن → متابعة إلى الدفع (استخدام replace لتجنب العودة إلى صفحة المنتج)
    router.replace("/checkout");
  }

  return (
    <div>
      {/* تنقل تسلسلي */}
      <nav className="text-sm text-gray-500 mb-6">
        <Link href="/" className="hover:text-blue-600">الرئيسية</Link>
        <span className="mx-2">/</span>
        <Link href="/products" className="hover:text-blue-600">المنتجات</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="المنتج"
            className="w-full rounded-lg"
          />
        </div>
        <div className="w-1/2">
          <h1 className="text-3xl font-bold">المنتج #{params.id}</h1>
          <p className="text-2xl text-green-600 font-bold mt-4">$49.99</p>
          <p className="text-gray-600 mt-4">
            منتج عالي الجودة بميزات متميزة.
          </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"
            >
              أضف إلى السلة
            </button>
            <button
              onClick={handleBuyNow}
              className="flex-1 px-6 py-3 bg-blue-600 text-white rounded-lg hover:bg-blue-700"
            >
              شراء الآن
            </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"
            >
              ← المنتج السابق
            </Link>
            <Link
              href={`/products/${Number(params.id) + 1}`}
              scroll={false}
              className="text-blue-600 hover:underline float-right"
            >
              المنتج التالي →
            </Link>
          </div>
        </div>
      </div>
    </div>
  );
}

// src/app/CartCount.tsx — عرض عدد عناصر سلة التسوق
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>
  );
}

شريط التنقل(مثبت في الأعلى):
[ShopHub]  المنتجات  الفئات  العروض  حول  [بحث]  السلة(3)  [تسجيل الدخول]

صفحة تفاصيل المنتج(/products/1):
الرئيسية / المنتجات / 1
[صورة المنتج]  [تفاصيل المنتج]
            المنتج #1
            $49.99
            [أضف إلى السلة] [شراء الآن]
            ← المنتج السابق | المنتج التالي →

سلوك التنقل:
- النقر على المنتجات → Soft Nav، تبديل فوري للصفحات
- النقر على العروض → لا يوجد جلب مسبق(prefetch=false)، لكن التنقل لا يزال سريعًا
- إضافة إلى السلة → router.refresh()، تحديث رمز سلة التسوق
- شراء الآن → router.replace("/checkout")، استبدال السجل