ملفات تعريف الارتباط (cookies)

تتيح لك وظيفة cookies قراءة ملفات تعريف الارتباط (cookies) الواردة في طلب HTTP من مكون الخادم (Server Component) أو كتابة ملفات تعريف الارتباط الصادرة في إجراء الخادم (Server Action) أو معالج المسار (Route Handler).

معلومة مفيدة: cookies() هي وظيفة ديناميكية (Dynamic Function) لا يمكن معرفة قيمها مسبقًا. استخدامها في تخطيط أو صفحة سيؤدي إلى تحويل المسار إلى عرض ديناميكي (dynamic rendering) عند وقت الطلب.

cookies().get(name)

طريقة تأخذ اسم ملف تعريف الارتباط وتُرجع كائنًا يحتوي على الاسم والقيمة. إذا لم يتم العثور على ملف تعريف الارتباط بالاسم المحدد، تُرجع undefined. إذا وجدت عدة ملفات مطابقة، ستُرجع أول تطابق فقط.

import { cookies } from 'next/headers'

export default function Page() {
  const cookieStore = cookies()
  const theme = cookieStore.get('theme')
  return '...'
}

cookies().getAll()

طريقة مشابهة لـ get، ولكنها تُرجع قائمة بجميع ملفات تعريف الارتباط المطابقة للاسم. إذا لم يتم تحديد الاسم، تُرجع جميع ملفات تعريف الارتباط المتاحة.

import { cookies } from 'next/headers'

export default function Page() {
  const cookieStore = cookies()
  return cookieStore.getAll().map((cookie) => (
    <div key={cookie.name}>
      <p>Name: {cookie.name}</p>
      <p>Value: {cookie.value}</p>
    </div>
  ))
}

cookies().has(name)

طريقة تأخذ اسم ملف تعريف الارتباط وتُرجع قيمة boolean بناءً على وجود الملف (true) أو عدم وجوده (false).

import { cookies } from 'next/headers'

export default function Page() {
  const cookieStore = cookies()
  const hasCookie = cookieStore.has('theme')
  return '...'
}

cookies().set(name, value, options)

طريقة تأخذ اسم ملف تعريف الارتباط وقيمة وخيارات وتقوم بتعيين ملف تعريف الارتباط الصادر.

معلومة مفيدة: لا يسمح HTTP بتعيين ملفات تعريف الارتباط بعد بدء البث، لذا يجب استخدام .set() في إجراء الخادم (Server Action) أو معالج المسار (Route Handler).

'use server'

import { cookies } from 'next/headers'

async function create(data) {
  cookies().set('name', 'lee')
  // أو
  cookies().set('name', 'lee', { secure: true })
  // أو
  cookies().set({
    name: 'name',
    value: 'lee',
    httpOnly: true,
    path: '/',
  })
}

حذف ملفات تعريف الارتباط

معلومة مفيدة: يمكنك فقط حذف ملفات تعريف الارتباط في إجراء الخادم (Server Action) أو معالج المسار (Route Handler).

هناك عدة خيارات لحذف ملف تعريف الارتباط:

cookies().delete(name)

يمكنك حذف ملف تعريف الارتباط صراحةً بالاسم المحدد.

'use server'

import { cookies } from 'next/headers'

async function delete(data) {
  cookies().delete('name')
}

cookies().set(name, '')

بدلاً من ذلك، يمكنك تعيين ملف تعريف ارتباط جديد بنفس الاسم وقيمة فارغة.

'use server'

import { cookies } from 'next/headers'

async function delete(data) {
  cookies().set('name', '')
}

معلومة مفيدة: .set() متاح فقط في إجراء الخادم (Server Action) أو معالج المسار (Route Handler).

cookies().set(name, value, { maxAge: 0 })

تعيين maxAge إلى 0 سينتهي صلاحية ملف تعريف الارتباط فورًا.

'use server'

import { cookies } from 'next/headers'

async function delete(data) {
  cookies().set('name', 'value', { maxAge: 0 })
}

cookies().set(name, value, { expires: timestamp })

تعيين expires إلى أي قيمة في الماضي سينتهي صلاحية ملف تعريف الارتباط فورًا.

'use server'

import { cookies } from 'next/headers'

async function delete(data) {
  const oneDay = 24 * 60 * 60 * 1000
  cookies().set('name', 'value', { expires: Date.now() - oneDay })
}

معلومة مفيدة: يمكنك فقط حذف ملفات تعريف الارتباط التي تنتمي إلى نفس النطاق الذي يتم منه استدعاء .set(). بالإضافة إلى ذلك، يجب تنفيذ الكود على نفس البروتوكول (HTTP أو HTTPS) مثل ملف تعريف الارتباط الذي تريد حذفه.

سجل الإصدارات