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

cookies هي وظيفة غير متزامنة (async) تتيح لك قراءة ملفات تعريف الارتباط (cookies) الواردة في طلب HTTP في مكونات الخادم (Server Components)، وقراءة/كتابة ملفات تعريف الارتباط الصادرة في إجراءات الخادم (Server Actions) أو معالجات المسارات (Route Handlers).

import { cookies } from 'next/headers'

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

import { cookies } from 'next/headers'

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

المرجع

الطرق

الطرق التالية متاحة:

الطريقة	نوع الإرجاع	الوصف
`get('name')`	كائن	يقبل اسم ملف تعريف الارتباط ويعيد كائنًا يحتوي على الاسم والقيمة.
`getAll()`	مصفوفة من الكائنات	يعيد قائمة بجميع ملفات تعريف الارتباط التي تطابق الاسم.
`has('name')`	قيمة منطقية	يقبل اسم ملف تعريف الارتباط ويعيد قيمة منطقية بناءً على وجود الملف.
`set(name, value, options)`	-	يقبل اسم ملف تعريف الارتباط، القيمة، والخيارات ويضبط ملف تعريف الارتباط الصادر.
`delete(name)`	-	يقبل اسم ملف تعريف الارتباط ويحذفه.
`clear()`	-	يحذف جميع ملفات تعريف الارتباط.
`toString()`	سلسلة	يعيد تمثيلًا نصيًا لملفات تعريف الارتباط.

الخيارات

عند تعيين ملف تعريف الارتباط، الخصائص التالية مدعومة في كائن options:

الخيار	النوع	الوصف
`name`	سلسلة	يحدد اسم ملف تعريف الارتباط.
`value`	سلسلة	يحدد القيمة التي سيتم تخزينها في ملف تعريف الارتباط.
`expires`	تاريخ	يحدد التاريخ المحدد لانتهاء صلاحية ملف تعريف الارتباط.
`maxAge`	رقم	يحدد عمر ملف تعريف الارتباط بالثواني.
`domain`	سلسلة	يحدد النطاق الذي يتوفر فيه ملف تعريف الارتباط.
`path`	سلسلة، افتراضي: `'/'`	يحدد نطاق ملف تعريف الارتباط لمسار محدد ضمن النطاق.
`secure`	قيمة منطقية	يضمن إرسال ملف تعريف الارتباط فقط عبر اتصالات HTTPS لأمان إضافي.
`httpOnly`	قيمة منطقية	يقتصر ملف تعريف الارتباط على طلبات HTTP، مما يمنع الوصول من جانب العميل.
`sameSite`	قيمة منطقية، `'lax'`، `'strict'`، `'none'`	يتحكم في سلوك ملف تعريف الارتباط في الطلبات عبر المواقع.
`priority`	سلسلة (`"low"`، `"medium"`، `"high"`)	يحدد أولوية ملف تعريف الارتباط
`encode('value')`	دالة	يحدد دالة ستستخدم لتشفير قيمة ملف تعريف الارتباط.
`partitioned`	قيمة منطقية	يشير إلى ما إذا كان ملف تعريف الارتباط مقسمًا (partitioned).

الخيار الوحيد الذي له قيمة افتراضية هو path.

لمعرفة المزيد عن هذه الخيارات، راجع وثائق MDN.

معلومات مفيدة

cookies هي وظيفة غير متزامنة (async) تعيد وعدًا (promise). يجب استخدام async/await أو دالة use في React للوصول إلى ملفات تعريف الارتباط.
- في الإصدار 14 وما قبله، كانت cookies وظيفة متزامنة. لدعم التوافق مع الإصدارات السابقة، يمكنك الوصول إليها بشكل متزامن في Next.js 15، ولكن هذا السلوك سيتم إهماله في المستقبل.
cookies هي واجهة برمجة تطبيقات ديناميكية (Dynamic API) لا يمكن معرفة قيمها مسبقًا. استخدامها في تخطيط أو صفحة سيحول المسار إلى عرض ديناميكي (dynamic rendering).
يمكن استدعاء طريقة .delete فقط:
- في إجراء خادم (Server Action) أو معالج مسار (Route Handler).
- إذا كانت تنتمي إلى نفس النطاق الذي تم استدعاء .set منه. بالنسبة للنطاقات العامة (wildcard domains)، يجب أن يتطابق النطاق الفرعي تمامًا. بالإضافة إلى ذلك، يجب تنفيذ الكود على نفس البروتوكول (HTTP أو HTTPS) مثل ملف تعريف الارتباط الذي تريد حذفه.
لا يسمح HTTP بتعيين ملفات تعريف الارتباط بعد بدء البث (streaming)، لذا يجب استخدام .set في إجراء خادم (Server Action) أو معالج مسار (Route Handler).

فهم سلوك ملفات تعريف الارتباط في مكونات الخادم

عند العمل مع ملفات تعريف الارتباط في مكونات الخادم، من المهم فهم أن ملفات تعريف الارتباط هي في الأساس آلية تخزين من جانب العميل:

قراءة ملفات تعريف الارتباط تعمل في مكونات الخادم لأنك تصل إلى بيانات ملفات تعريف الارتباط التي يرسلها متصفح العميل إلى الخادم في رؤوس طلب HTTP.
تعيين ملفات تعريف الارتباط لا يمكن القيام به مباشرة في مكون الخادم، حتى عند استخدام معالج مسار أو إجراء خادم. وذلك لأن ملفات تعريف الارتباط يتم تخزينها فعليًا بواسطة المتصفح، وليس الخادم.

يمكن للخادم فقط إرسال تعليمات (عبر رؤوس Set-Cookie) لإخبار المتصفح بتخزين ملفات تعريف الارتباط - التخزين الفعلي يحدث على جانب العميل. لهذا السبب يجب تنفيذ العمليات التي تعدل الحالة (.set، .delete، .clear) في معالج مسار أو إجراء خادم حيث يمكن تعيين رؤوس الاستجابة بشكل صحيح.

أمثلة

الحصول على ملف تعريف الارتباط

يمكنك استخدام طريقة (await cookies()).get('name') للحصول على ملف تعريف ارتباط واحد:

import { cookies } from 'next/headers'

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

import { cookies } from 'next/headers'

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

الحصول على جميع ملفات تعريف الارتباط

يمكنك استخدام طريقة (await cookies()).getAll() للحصول على جميع ملفات تعريف الارتباط التي تطابق الاسم. إذا لم يتم تحديد name، فإنها تعيد جميع ملفات تعريف الارتباط المتاحة.

import { cookies } from 'next/headers'

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

import { cookies } from 'next/headers'

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

تعيين ملف تعريف الارتباط

يمكنك استخدام طريقة (await cookies()).set(name, value, options) في إجراء خادم (Server Action) أو معالج مسار (Route Handler) لتعيين ملف تعريف ارتباط. كائن options اختياري.

'use server'

import { cookies } from 'next/headers'

export async function create(data) {
  const cookieStore = await cookies()

  cookieStore.set('name', 'lee')
  // أو
  cookieStore.set('name', 'lee', { secure: true })
  // أو
  cookieStore.set({
    name: 'name',
    value: 'lee',
    httpOnly: true,
    path: '/',
  })
}

'use server'

import { cookies } from 'next/headers'

export async function create(data) {
  const cookieStore = await cookies()

  cookieStore.set('name', 'lee')
  // أو
  cookieStore.set('name', 'lee', { secure: true })
  // أو
  cookieStore.set({
    name: 'name',
    value: 'lee',
    httpOnly: true,
    path: '/',
  })
}

التحقق من وجود ملف تعريف الارتباط

يمكنك استخدام طريقة (await cookies()).has(name) للتحقق من وجود ملف تعريف ارتباط:

import { cookies } from 'next/headers'

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

import { cookies } from 'next/headers'

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

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

هناك ثلاث طرق يمكنك من خلالها حذف ملف تعريف ارتباط.

باستخدام طريقة delete():

'use server'

import { cookies } from 'next/headers'

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

'use server'

import { cookies } from 'next/headers'

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

تعيين ملف تعريف ارتباط جديد بنفس الاسم وقيمة فارغة:

'use server'

import { cookies } from 'next/headers'

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

'use server'

import { cookies } from 'next/headers'

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

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

'use server'

import { cookies } from 'next/headers'

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

'use server'

import { cookies } from 'next/headers'

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

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

الإصدار	التغييرات
`v15.0.0-RC`	أصبحت `cookies` وظيفة غير متزامنة. يتوفر أداة تحويل الشفرة (codemod).
`v13.0.0`	تم تقديم `cookies`.

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

On this page