chrome.cookies

refresh date: 2026-09-25 robots: noindex

الوصف

استخدِم واجهة برمجة التطبيقات chrome.cookies للاستعلام عن ملفات تعريف الارتباط وتعديلها، ولتلقّي إشعارات عند تغييرها.

الأذونات

cookies

البيان

لاستخدام واجهة برمجة التطبيقات الخاصة بملفات تعريف الارتباط، يجب تضمين الإذن "cookies" في ملف البيان، بالإضافة إلى أذونات المضيف لأي مضيفين تريد الوصول إلى ملفات تعريف الارتباط الخاصة بهم. على سبيل المثال:

{
  "name": "My extension",
  ...
  "host_permissions": [
    "*://*.google.com/"
  ],
  "permissions": [
    "cookies"
  ],
  ...
}

التقسيم

تسمح ملفات تعريف الارتباط المقسَّمة لأحد المواقع الإلكترونية بالإشارة إلى أنّه يجب ربط ملفات تعريف ارتباط معيّنة بمصدر الإطار ذي المستوى الأعلى. وهذا يعني أنّه إذا تم تضمين الموقع الإلكتروني (أ) باستخدام إطار iframe في الموقع الإلكتروني (ب) والموقع الإلكتروني (ج)، يمكن أن تتضمّن ملفات تعريف الارتباط المقسّمة قيمة مختلفة في كلّ موقع إلكتروني.

لا يتيح chrome.cookies التقسيم، ما يعني أنّ جميع الطرق تقرأ ملفات تعريف الارتباط وتكتبها من جميع الأقسام. تخزّن طريقة cookies.set() ملفات تعريف الارتباط في القسم التلقائي.

للحصول على تفاصيل حول التأثير العام لتقسيم مساحة التخزين على الإضافات، يُرجى الاطّلاع على مساحة التخزين وملفات تعريف الارتباط.

أمثلة

يمكنك العثور على مثال بسيط لاستخدام واجهة برمجة التطبيقات الخاصة بملفات تعريف الارتباط في الدليل examples/api/cookies. للاطّلاع على أمثلة أخرى وللحصول على مساعدة في عرض الرمز المصدر، يُرجى الاطّلاع على النماذج.

الأنواع

تمثّل هذه السمة معلومات عن ملف تعريف ارتباط HTTP.

الخصائص

  • نطاق

    سلسلة

    نطاق ملف تعريف الارتباط (مثل "www.google.com" أو "example.com")

  • expirationDate

    number اختياري

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

  • hostOnly

    قيمة منطقية

    تكون القيمة صحيحة إذا كان ملف تعريف الارتباط مخصّصًا للمضيف فقط (أي يجب أن يتطابق مضيف الطلب تمامًا مع نطاق ملف تعريف الارتباط).

  • httpOnly

    قيمة منطقية

    القيمة "صحيح" إذا تم وضع علامة HttpOnly على ملف تعريف الارتباط (أي لا يمكن الوصول إلى ملف تعريف الارتباط من خلال النصوص البرمجية من جهة العميل).

  • الاسم

    سلسلة

    تمثّل هذه السمة اسم ملف تعريف الارتباط.

  • partitionKey

    ‫CookiePartitionKey اختياري

    الإصدار 119 من Chrome والإصدارات الأحدث

    مفتاح التقسيم لقراءة ملفات تعريف الارتباط أو تعديلها باستخدام السمة Partitioned

  • المسار

    سلسلة

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

  • sameSite

    SameSiteStatus

    الإصدار 51 من Chrome والإصدارات الأحدث

    حالة ملف تعريف الارتباط على الموقع الإلكتروني نفسه (أي ما إذا كان يتم إرسال ملف تعريف الارتباط مع الطلبات المُرسَلة من مواقع إلكترونية مختلفة)

  • آمن

    قيمة منطقية

    تكون القيمة صحيحة إذا تم وضع علامة "آمن" على ملف تعريف الارتباط (أي إذا كان نطاقه يقتصر على القنوات الآمنة، مثل HTTPS عادةً).

  • جلسة

    قيمة منطقية

    تعرض القيمة "صحيح" إذا كان ملف تعريف الارتباط هو ملف تعريف ارتباط للجلسة، وليس ملف تعريف ارتباط دائمًا له تاريخ انتهاء صلاحية.

  • storeId

    سلسلة

    معرّف متجر ملفات تعريف الارتباط الذي يحتوي على ملف تعريف الارتباط هذا، كما هو موضّح في getAllCookieStores().

  • القيمة

    سلسلة

    تمثّل هذه السمة قيمة ملف تعريف الارتباط.

CookieDetails

الإصدار 88 من Chrome والإصدارات الأحدث

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

الخصائص

  • الاسم

    سلسلة

    اسم ملف تعريف الارتباط الذي سيتم الوصول إليه

  • partitionKey

    ‫CookiePartitionKey اختياري

    الإصدار 119 من Chrome والإصدارات الأحدث

    مفتاح التقسيم لقراءة ملفات تعريف الارتباط أو تعديلها باستخدام السمة Partitioned

  • storeId

    سلسلة اختيارية

    معرّف متجر ملفات تعريف الارتباط الذي سيتم البحث فيه عن ملف تعريف الارتباط. سيتم تلقائيًا استخدام متجر ملفات تعريف الارتباط لسياق التنفيذ الحالي.

  • url

    سلسلة

    عنوان URL المرتبط بملف تعريف الارتباط الذي سيتم الوصول إليه يمكن أن تكون هذه الوسيطة عنوان URL كاملاً، وفي هذه الحالة يتم تجاهل أي بيانات تلي مسار عنوان URL (مثل سلسلة طلب البحث). إذا لم يتم تحديد أذونات المضيف لعنوان URL هذا في ملف البيان، سيتعذّر تنفيذ طلب البيانات من واجهة برمجة التطبيقات.

CookiePartitionKey

الإصدار 119 من Chrome والإصدارات الأحدث

تمثّل هذه السمة مفتاح تقسيم ملف تعريف ارتباط مُقسَّم.

الخصائص

  • hasCrossSiteAncestor

    boolean اختياري

    الإصدار 130 من Chrome والإصدارات الأحدث

    تشير إلى ما إذا تم ضبط ملف تعريف الارتباط في سياق موقع إلكتروني متعدد المصادر. يمنع ذلك موقعًا إلكترونيًا في المستوى الأعلى مضمَّنًا في سياق على جميع المواقع الإلكترونية من الوصول إلى ملفات تعريف الارتباط التي يضبطها الموقع الإلكتروني في المستوى الأعلى في سياق على الموقع الإلكتروني نفسه.

  • topLevelSite

    سلسلة اختيارية

    الموقع الإلكتروني ذو المستوى الأعلى الذي يتوفّر فيه ملف تعريف الارتباط المُقسَّم

CookieStore

تمثّل هذه السمة مخزنًا لملفات تعريف الارتباط في المتصفّح. على سبيل المثال، تستخدم نافذة وضع التصفّح المتخفي مساحة تخزين منفصلة لملفات تعريف الارتباط عن نافذة غير متخفية.

الخصائص

  • id

    سلسلة

    المعرّف الفريد لمخزن ملفات تعريف الارتباط.

  • tabIds

    number[]

    معرّفات جميع علامات تبويب المتصفّح التي تشارك متجر ملفات تعريف الارتباط هذا

FrameDetails

‫Chrome 132 والإصدارات الأحدث

تفاصيل لتحديد الإطار

الخصائص

  • documentId

    سلسلة اختيارية

    المعرّف الفريد للمستند. في حال توفير frameId و/أو tabId، سيتم التحقّق من صحتهما للتأكّد من تطابقهما مع المستند الذي تم العثور عليه باستخدام رقم تعريف المستند المقدَّم.

  • frameId

    number اختياري

    المعرّف الفريد للإطار داخل علامة التبويب.

  • tabId

    number اختياري

    المعرّف الفريد للعلامة التي تحتوي على الإطار

OnChangedCause

Chrome 44 والإصدارات الأحدث

السبب الأساسي وراء تغيير ملف تعريف الارتباط إذا تم إدراج ملف تعريف ارتباط أو إزالته من خلال طلب صريح إلى "chrome.cookies.remove"، ستكون "السبب" هو "صريح". إذا تمت إزالة ملف تعريف ارتباط تلقائيًا بسبب انتهاء صلاحيته، ستكون "السبب" هي "انتهت صلاحيته". إذا تمت إزالة ملف تعريف ارتباط بسبب الكتابة فوقه بتاريخ انتهاء صلاحية منتهي، سيتم ضبط "السبب" على "expired_overwrite". إذا تمت إزالة ملف تعريف ارتباط تلقائيًا بسبب جمع البيانات المُهمَلة، ستكون "السبب" هي "تمت إزالته". إذا تمت إزالة ملف تعريف ارتباط تلقائيًا بسبب طلب "set" استبدله، ستكون "السبب" هي "overwrite". خطِّط لردّك وفقًا لذلك.

تعداد

"evicted"

"منتهية الصلاحية"

"explicit"

"expired_overwrite"

"overwrite"

SameSiteStatus

الإصدار 51 من Chrome والإصدارات الأحدث

حالة SameSite لملف تعريف الارتباط (https://tools.ietf.org/html/draft-west-first-party-cookies) تتوافق القيمة no_restriction مع ملف تعريف ارتباط تم ضبطه باستخدام SameSite=None، وتتوافق القيمة lax مع SameSite=Lax، وتتوافق القيمة strict مع SameSite=Strict. تشير القيمة "unspecified" إلى ملف تعريف ارتباط تم ضبطه بدون السمة SameSite.

تعداد

"no_restriction"

"lax"

"strict"

"unspecified"

الطُرق

get()

وعد 
chrome.cookies.get(
  details: CookieDetails,
  callback?: function,
): Promise<Cookie | undefined>

تُستخدَم لاسترداد معلومات عن ملف تعريف ارتباط واحد. إذا كان هناك أكثر من ملف تعريف ارتباط واحد بالاسم نفسه لعنوان URL معيّن، سيتم عرض ملف تعريف الارتباط الذي يتضمّن أطول مسار. بالنسبة إلى ملفات تعريف الارتباط التي لها طول المسار نفسه، سيتم عرض ملف تعريف الارتباط الذي تم إنشاؤه في أقرب وقت.

المعلمات

  • التفاصيل

    CookieDetails

  • callback

    الدالة اختيارية

    تظهر المَعلمة callback على النحو التالي: 

    (cookie?: Cookie) => void

    • كعكة محلاة

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

      تحتوي على تفاصيل حول ملف تعريف الارتباط. تكون قيمة هذه المَعلمة فارغة في حال عدم العثور على ملف تعريف ارتباط من هذا النوع.

المرتجعات

  • Promise<Cookie | undefined>

    الإصدار 88 من Chrome والإصدارات الأحدث

    لا تتوفّر الوعود إلا في الإصدار Manifest V3 والإصدارات الأحدث، بينما تحتاج المنصات الأخرى إلى استخدام عمليات معاودة الاتصال.

getAll()

وعد 
chrome.cookies.getAll(
  details: object,
  callback?: function,
): Promise<Cookie[]>

تسترجع جميع ملفات تعريف الارتباط من متجر ملفات تعريف ارتباط واحد يتطابق مع المعلومات المقدَّمة. سيتم ترتيب ملفات تعريف الارتباط التي تم إرجاعها، مع عرض تلك التي تتضمّن أطول مسار أولاً. إذا كانت ملفات تعريف الارتباط المتعددة تتضمّن طول المسار نفسه، ستكون ملفات تعريف الارتباط التي تم إنشاؤها في وقت مبكر هي الأولى. لا تستردّ هذه الطريقة ملفات تعريف الارتباط إلا للنطاقات التي تملك الإضافة أذونات المضيف لها.

المعلمات

  • التفاصيل

    عنصر

    معلومات لفلترة ملفات تعريف الارتباط التي يتم استردادها

    • نطاق

      سلسلة اختيارية

      يقصر ملفات تعريف الارتباط التي تم استرجاعها على تلك التي تتطابق نطاقاتها مع هذا النطاق أو هي نطاقات فرعية منه.

    • الاسم

      سلسلة اختيارية

      تتم فلترة ملفات تعريف الارتباط حسب الاسم.

    • partitionKey

      ‫CookiePartitionKey اختياري

      الإصدار 119 من Chrome والإصدارات الأحدث

      مفتاح التقسيم لقراءة ملفات تعريف الارتباط أو تعديلها باستخدام السمة Partitioned

    • المسار

      سلسلة اختيارية

      يقتصر على ملفات تعريف الارتباط التي يتطابق مسارها تمامًا مع هذه السلسلة.

    • آمن

      boolean اختياري

      تتم فلترة ملفات تعريف الارتباط حسب السمة Secure.

    • جلسة

      boolean اختياري

      تستبعد هذه السمة ملفات تعريف الارتباط الخاصة بالجلسة وملفات تعريف الارتباط الدائمة.

    • storeId

      سلسلة اختيارية

      متجر ملفات تعريف الارتباط الذي سيتم استرداد ملفات تعريف الارتباط منه في حال حذفها، سيتم استخدام متجر ملفات تعريف الارتباط في سياق التنفيذ الحالي.

    • url

      سلسلة اختيارية

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

  • callback

    الدالة اختيارية

    تظهر المَعلمة callback على النحو التالي: 

    (cookies: Cookie[]) => void

    • البسكويت

      Cookie[]

      جميع ملفات تعريف الارتباط الحالية وغير المنتهية الصلاحية التي تتطابق مع معلومات ملف تعريف الارتباط المقدَّمة

المرتجعات

  • Promise<Cookie[]>

    الإصدار 88 من Chrome والإصدارات الأحدث

    لا تتوفّر الوعود إلا في الإصدار Manifest V3 والإصدارات الأحدث، بينما تحتاج المنصات الأخرى إلى استخدام عمليات معاودة الاتصال.

getAllCookieStores()

وعد 
chrome.cookies.getAllCookieStores(
  callback?: function,
): Promise<CookieStore[]>

تعرض هذه السمة جميع مستودعات ملفات تعريف الارتباط الحالية.

المعلمات

  • callback

    الدالة اختيارية

    تظهر المَعلمة callback على النحو التالي: 

    (cookieStores: CookieStore[]) => void

    • cookieStores

      CookieStore[]

      جميع متاجر ملفات تعريف الارتباط الحالية

المرتجعات

  • Promise<CookieStore[]>

    الإصدار 88 من Chrome والإصدارات الأحدث

    لا تتوفّر الوعود إلا في الإصدار Manifest V3 والإصدارات الأحدث، بينما تحتاج المنصات الأخرى إلى استخدام عمليات معاودة الاتصال.

getPartitionKey()

Promise الإصدار 132 من Chrome والإصدارات الأحدث 
chrome.cookies.getPartitionKey(
  details: FrameDetails,
  callback?: function,
): Promise<object>

تمثّل هذه السمة مفتاح التقسيم للإطار المحدّد.

المعلمات

  • التفاصيل

    FrameDetails

  • callback

    الدالة اختيارية

    تظهر المَعلمة callback على النحو التالي: 

    (details: object) => void

    • التفاصيل

      عنصر

      تحتوي على تفاصيل حول مفتاح القسم الذي تم استرداده.

      • partitionKey

        CookiePartitionKey

        مفتاح التقسيم لقراءة ملفات تعريف الارتباط أو تعديلها باستخدام السمة Partitioned

المرتجعات

  • Promise<object>

    لا تتوفّر الوعود إلا في الإصدار Manifest V3 والإصدارات الأحدث، بينما تحتاج المنصات الأخرى إلى استخدام عمليات معاودة الاتصال.

remove()

وعد 
chrome.cookies.remove(
  details: CookieDetails,
  callback?: function,
): Promise<object | undefined>

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

المعلمات

  • التفاصيل

    CookieDetails

  • callback

    الدالة اختيارية

    تظهر المَعلمة callback على النحو التالي: 

    (details?: object) => void

    • التفاصيل

      كائن اختياري

      تحتوي على تفاصيل حول ملف تعريف الارتباط الذي تمت إزالته. إذا تعذّرت الإزالة لأي سبب، سيتم رفض الوعد.

      • الاسم

        سلسلة

        اسم ملف تعريف الارتباط الذي تمت إزالته

      • partitionKey

        ‫CookiePartitionKey اختياري

        الإصدار 119 من Chrome والإصدارات الأحدث

        مفتاح التقسيم لقراءة ملفات تعريف الارتباط أو تعديلها باستخدام السمة Partitioned

      • storeId

        سلسلة

        معرّف متجر ملفات تعريف الارتباط الذي تمت إزالة ملف تعريف الارتباط منه.

      • url

        سلسلة

        عنوان URL المرتبط بملف تعريف الارتباط الذي تمت إزالته

المرتجعات

  • Promise<object | undefined>

    الإصدار 88 من Chrome والإصدارات الأحدث

    لا تتوفّر الوعود إلا في الإصدار Manifest V3 والإصدارات الأحدث، بينما تحتاج المنصات الأخرى إلى استخدام عمليات معاودة الاتصال.

set()

وعد 
chrome.cookies.set(
  details: object,
  callback?: function,
): Promise<Cookie | undefined>

تضبط هذه السمة ملف تعريف ارتباط ببيانات ملفات تعريف الارتباط المحدّدة، وقد تستبدل ملفات تعريف الارتباط المشابهة إذا كانت متوفّرة.

المعلمات

  • التفاصيل

    عنصر

    تفاصيل حول ملف تعريف الارتباط الذي يتم ضبطه

    • نطاق

      سلسلة اختيارية

      تمثّل هذه السمة نطاق ملف تعريف الارتباط. في حال عدم تضمينها، يصبح ملف تعريف الارتباط متاحًا للمضيف فقط.

    • expirationDate

      number اختياري

      تمثّل هذه السمة تاريخ انتهاء صلاحية ملف تعريف الارتباط ويتم احتسابه بعدد الثواني منذ بداية حقبة يونكس. في حال عدم إدخال قيمة، يصبح ملف تعريف الارتباط ملف تعريف ارتباط للجلسة.

    • httpOnly

      boolean اختياري

      لتحديد ما إذا كان يجب وضع علامة HttpOnly على ملف تعريف الارتباط. القيمة التلقائية هي "خطأ".

    • الاسم

      سلسلة اختيارية

      تمثّل هذه السمة اسم ملف تعريف الارتباط. يكون فارغًا تلقائيًا في حال عدم إدخال قيمة.

    • partitionKey

      ‫CookiePartitionKey اختياري

      الإصدار 119 من Chrome والإصدارات الأحدث

      مفتاح التقسيم لقراءة ملفات تعريف الارتباط أو تعديلها باستخدام السمة Partitioned

    • المسار

      سلسلة اختيارية

      مسار ملف تعريف الارتباط يتم ضبط القيمة التلقائية على جزء المسار من مَعلمة عنوان URL.

    • sameSite

      SameSiteStatus اختياري

      الإصدار 51 من Chrome والإصدارات الأحدث

      حالة ملف تعريف الارتباط على الموقع الإلكتروني نفسه القيمة التلقائية هي "unspecified"، أي أنّه في حال حذفها، يتم ضبط ملف تعريف الارتباط بدون تحديد سمة SameSite.

    • آمن

      boolean اختياري

      لتحديد ما إذا كان يجب تمييز ملف تعريف الارتباط على أنّه آمن. القيمة التلقائية هي "خطأ".

    • storeId

      سلسلة اختيارية

      معرّف متجر ملفات تعريف الارتباط الذي سيتم ضبط ملف تعريف الارتباط فيه. يتم تلقائيًا ضبط ملف تعريف الارتباط في متجر ملفات تعريف الارتباط الخاص بسياق التنفيذ الحالي.

    • url

      سلسلة

      تمثّل هذه السمة معرّف الموارد الموحّد (URI) المطلوب ربطه بإعداد ملف تعريف الارتباط. يمكن أن تؤثّر هذه القيمة في قيم النطاق والمسار التلقائية لملف تعريف الارتباط الذي تم إنشاؤه. إذا لم يتم تحديد أذونات المضيف لعنوان URL هذا في ملف البيان، سيتعذّر تنفيذ طلب البيانات من واجهة برمجة التطبيقات.

    • القيمة

      سلسلة اختيارية

      تمثّل هذه السمة قيمة ملف تعريف الارتباط. يكون فارغًا تلقائيًا في حال عدم إدخال قيمة.

  • callback

    الدالة اختيارية

    تظهر المَعلمة callback على النحو التالي: 

    (cookie?: Cookie) => void

    • كعكة محلاة

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

      تحتوي على تفاصيل حول ملف تعريف الارتباط الذي تم ضبطه. إذا تعذّر ضبط الإعداد لأي سبب، سيتم رفض الوعد.

المرتجعات

  • Promise<Cookie | undefined>

    الإصدار 88 من Chrome والإصدارات الأحدث

    لا تتوفّر الوعود إلا في الإصدار Manifest V3 والإصدارات الأحدث، بينما تحتاج المنصات الأخرى إلى استخدام عمليات معاودة الاتصال.

الفعاليات

onChanged

chrome.cookies.onChanged.addListener(
  callback: function,
)

يتم تنشيط هذا الحدث عند ضبط ملف تعريف ارتباط أو إزالته. في حالة خاصة، يُرجى العِلم أنّه يتم تنفيذ تعديل خصائص ملف تعريف الارتباط على خطوتَين: تتم أولاً إزالة ملف تعريف الارتباط المراد تعديله بالكامل، ما يؤدي إلى إنشاء إشعار يتضمّن "السبب" "overwrite" . بعد ذلك، تتم كتابة ملف تعريف ارتباط جديد بالقيم المعدَّلة، ما يؤدي إلى إنشاء إشعار ثانٍ يتضمّن "السبب" "صريح".

المعلمات

  • callback

    دالة

    تظهر المَعلمة callback على النحو التالي: 

    (changeInfo: object) => void

    • changeInfo

      عنصر

      • السبب

        OnChangedCause

        السبب الأساسي وراء تغيير ملف تعريف الارتباط

      • معلومات عن ملف تعريف الارتباط الذي تم ضبطه أو إزالته

      • تمت الإزالة

        قيمة منطقية

        قيمة منطقية صحيحة إذا تمت إزالة ملف تعريف ارتباط.