ملفات تعريف الارتباط (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 cookiesList = cookies()
  const hasCookie = cookiesList.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 create(data) {
  cookies().delete('name')
}

cookies().set(name, '')

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

'use server'

import { cookies } from 'next/headers'

async function create(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 create(data) {
  cookies().set('name', 'value', { maxAge: 0 })
}

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

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

'use server'

import { cookies } from 'next/headers'

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

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

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