chrome.contentSettings

refresh date: 2026-09-25 robots: noindex

الوصف

استخدِم واجهة برمجة التطبيقات chrome.contentSettings لتغيير الإعدادات التي تتحكّم في إمكانية استخدام المواقع الإلكترونية لميزات مثل ملفات تعريف الارتباط وJavaScript والمكوّنات الإضافية. بشكل عام، تتيح لك إعدادات المحتوى تخصيص سلوك Chrome لكل موقع إلكتروني على حدة بدلاً من تخصيصه بشكل عام.

الأذونات

contentSettings

البيان

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

{
  "name": "My extension",
  ...
  "permissions": [
    "contentSettings"
  ],
  ...
}

أنماط إعدادات المحتوى

يمكنك استخدام الأنماط لتحديد المواقع الإلكترونية التي يؤثر فيها كل إعداد من إعدادات المحتوى. على سبيل المثال، يحدّد https://*.youtube.com/* النطاق youtube.com وجميع نطاقاته الفرعية. إنّ بنية أنماط إعدادات المحتوى هي نفسها بنية أنماط المطابقة، مع بعض الاختلافات:

  • بالنسبة إلى عناوين URL التي تستخدم http وhttps وftp، يجب أن يكون المسار عبارة عن حرف بدل (/*). بالنسبة إلى عناوين URL التي تستخدم file، يجب تحديد المسار بالكامل ويجب ألا يحتوي على أحرف بدل.
  • على عكس أنماط المطابقة، يمكن لأنماط إعدادات المحتوى تحديد رقم منفذ. في حال تحديد رقم منفذ، يتطابق النمط مع المواقع الإلكترونية التي تستخدم هذا المنفذ فقط. وفي حال عدم تحديد رقم منفذ، يتطابق النمط مع جميع المنافذ.

أولوية النمط

عندما تنطبق أكثر من قاعدة واحدة لإعدادات المحتوى على موقع إلكتروني معيّن، تكون الأولوية للقاعدة التي تتضمّن نمطًا أكثر تحديدًا.

على سبيل المثال، يتم ترتيب الأنماط التالية حسب الأولوية:

  1. https://www.example.com/*
  2. https://*.example.com/* (مطابقة example.com وجميع النطاقات الفرعية)
  3. ‫<all_urls> (تطابق كل عناوين URL)

تؤثر ثلاثة أنواع من أحرف البدل في مدى تحديد النمط:

  • أحرف البدل في المنفذ (مثلاً https://www.example.com:*/*)
  • أحرف البدل في المخطط (مثل *://www.example.com:123/*)
  • أحرف البدل في اسم المضيف (مثل https://*.example.com:123/*)

إذا كان أحد الأنماط أكثر تحديدًا من نمط آخر في جزء معيّن ولكنّه أقل تحديدًا في جزء آخر، يتم التحقّق من الأجزاء المختلفة بالترتيب التالي: اسم المضيف، والمخطط، والمنفذ. على سبيل المثال، يتم ترتيب الأنماط التالية حسب الأولوية:

  1. https://www.example.com:*/* تحدّد اسم المضيف والمخطط.
  2. *:/www.example.com:123/* ليست عالية، لأنّه على الرغم من تحديد اسم المضيف، لا يتم تحديد المخطط.
  3. https://*.example.com:123/* أقلّ لأنّه يحدّد المنفذ والمخطط، ولكنّه يحتوي على حرف بدل في اسم المضيف.

الأنماط الأساسية والثانوية

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

يمكن لبعض أنواع المحتوى أن تأخذ في الاعتبار عناوين URL إضافية. على سبيل المثال، يتم تحديد ما إذا كان يُسمح لموقع إلكتروني بضبط contentSettings.cookies استنادًا إلى عنوان URL لطلب HTTP (وهو عنوان URL الأساسي في هذه الحالة) بالإضافة إلى عنوان URL المعروض في المربّع المتعدّد الاستخدامات (والذي يُسمى عنوان URL "الثانوي").

إذا كانت هناك قواعد متعدّدة تتضمّن أنماطًا أساسية وثانوية، تكون الأولوية للقاعدة التي تتضمّن نمطًا أساسيًا أكثر تحديدًا. إذا كانت هناك قواعد متعددة لها النمط الأساسي نفسه، تكون الأولوية للقاعدة التي تتضمّن النمط الثانوي الأكثر تحديدًا. على سبيل المثال، يتم ترتيب القائمة التالية لأزواج الأنماط الأساسية/الثانوية حسب الأولوية:

الأولويةالنمط الأساسيالنمط الثانوي
1https://www.moose.com/*،https://www.wombat.com/*
2https://www.moose.com/*،<all_urls>
3<all_urls>،https://www.wombat.com/*
4<all_urls>،<all_urls>

معرّفات الموارد

تتيح لك معرّفات الموارد تحديد إعدادات المحتوى لأنواع فرعية معيّنة من نوع المحتوى. في الوقت الحالي، نوع المحتوى الوحيد الذي يتيح استخدام معرّفات الموارد هو contentSettings.plugins، حيث يحدّد معرّف المورد مكوّنًا إضافيًا معيّنًا. عند تطبيق إعدادات المحتوى، يتم أولاً التحقّق من إعدادات المكوّن الإضافي المحدّد. في حال عدم العثور على إعدادات للمكوّن الإضافي المحدّد، يتم التحقّق من إعدادات المحتوى العامة للمكوّنات الإضافية.

على سبيل المثال، إذا كانت قاعدة إعدادات المحتوى تتضمّن معرّف المورد adobe-flash-player والنمط <all_urls>، تكون لها الأولوية على قاعدة لا تتضمّن معرّف مورد والنمط https://www.example.com/*، حتى إذا كان هذا النمط أكثر تحديدًا.

يمكنك الحصول على قائمة بمعرّفات الموارد لنوع محتوى معيّن من خلال طلب طريقة contentSettings.ContentSetting.getResourceIdentifiers. يمكن أن تتغيّر القائمة التي يتم عرضها مع مجموعة المكوّنات الإضافية المثبّتة على جهاز المستخدم، ولكن يحاول Chrome الحفاظ على ثبات المعرّفات في جميع تحديثات المكوّنات الإضافية.

أمثلة

لتجربة واجهة برمجة التطبيقات هذه، ثبِّت مثال contentSettings API من مستودع chrome-extension-samples.

الأنواع

AutoVerifyContentSetting

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

Enum

"allow"

"block"

CameraContentSetting

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

Enum

"allow"

"block"

"ask"

ClipboardContentSetting

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

Enum

"allow"

"block"

"ask"

ContentSetting

الخصائص

  • محو

    void

    Promise

    محو جميع قواعد إعدادات المحتوى التي تم ضبطها من خلال هذه الإضافة

    تبدو الدالة clear على النحو التالي: 

    (details: object, callback?: function) => {...}

    • التفاصيل

      عنصر

      • نطاق

        Scope اختياري

        مكان محو الإعداد (الإعداد التلقائي: عادي)

    • callback

      function اختياري

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

      () => void

    • returns

      وعد<فراغ>

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

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

  • الحصول على

    void

    Promise

    للحصول على إعداد المحتوى الحالي لزوج معيّن من عناوين URL

    تبدو الدالة get على النحو التالي: 

    (details: object, callback?: function) => {...}

    • التفاصيل

      عنصر

      • incognito

        قيمة منطقية اختيارية

        تحدّد هذه السياسة ما إذا كان سيتم التحقّق من إعدادات المحتوى في جلسة التصفّح المتخفي. (القيمة التلقائية هي false)

      • primaryUrl

        سلسلة

        عنوان URL الأساسي الذي يجب استرداد إعدادات المحتوى له يُرجى العِلم أنّ معنى عنوان URL الأساسي يعتمد على نوع المحتوى.

      • resourceIdentifier

        ResourceIdentifier اختياري

        معرّف أكثر تحديدًا لنوع المحتوى الذي يجب استرداد الإعدادات له

      • secondaryUrl

        string اختياري

        عنوان URL الثانوي الذي يجب استرداد إعداد المحتوى له يتم ضبطه تلقائيًا على عنوان URL الأساسي. يُرجى العِلم أنّ معنى عنوان URL الثانوي يعتمد على نوع المحتوى، ولا تستخدم بعض أنواع المحتوى عناوين URL ثانوية.

    • callback

      function اختياري

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

      (details: object) => void

      • التفاصيل

        عنصر

        • الإعداد

          T

          إعدادات المحتوى يمكنك الاطّلاع على وصف عناصر ContentSetting الفردية لمعرفة القيم المحتمَلة.

    • returns

      وعد<كائن>

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

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

  • getResourceIdentifiers

    void

    Promise

    تبدو الدالة getResourceIdentifiers على النحو التالي: 

    (callback?: function) => {...}

    • callback

      function اختياري

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

      (resourceIdentifiers?: ResourceIdentifier[]) => void

      • resourceIdentifiers

        ResourceIdentifier[] اختياري

        قائمة بمعرّفات الموارد لنوع المحتوى هذا، أو undefined إذا كان نوع المحتوى هذا لا يستخدم معرّفات الموارد.

    • returns

      Promise<ResourceIdentifier[]>

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

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

  • محدّدة

    void

    Promise

    لتطبيق قاعدة جديدة لإعدادات المحتوى

    تبدو الدالة set على النحو التالي: 

    (details: object, callback?: function) => {...}

    • التفاصيل

      عنصر

      • primaryPattern

        سلسلة

        نمط عنوان URL الأساسي لمعرفة تفاصيل حول تنسيق النمط، يُرجى الاطّلاع على أنماط إعدادات المحتوى.

      • resourceIdentifier

        ResourceIdentifier اختياري

        معرّف المورد لنوع المحتوى

      • نطاق

        Scope اختياري

        مكان ضبط الإعداد (الإعداد التلقائي: عادي)

      • secondaryPattern

        string اختياري

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

      • الإعداد

        أي واحد

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

    • callback

      function اختياري

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

      () => void

    • returns

      وعد<فراغ>

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

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

CookiesContentSetting

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

Enum

"allow"

"block"

"session_only"

FullscreenContentSetting

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

القيمة

"allow"

ImagesContentSetting

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

Enum

"allow"

"block"

JavascriptContentSetting

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

Enum

"allow"

"block"

LocationContentSetting

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

Enum

"allow"

"block"

"ask"

MicrophoneContentSetting

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

Enum

"allow"

"block"

"ask"

MouselockContentSetting

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

القيمة

"allow"

MultipleAutomaticDownloadsContentSetting

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

Enum

"allow"

"block"

"ask"

NotificationsContentSetting

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

Enum

"allow"

"block"

"ask"

PluginsContentSetting

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

القيمة

"block"

PopupsContentSetting

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

Enum

"allow"

"block"

PpapiBrokerContentSetting

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

القيمة

"block"

ResourceIdentifier

نوع المحتوى الوحيد الذي يستخدم معرّفات الموارد هو contentSettings.plugins. لمزيد من المعلومات، يُرجى الاطّلاع على معرّفات الموارد.

الخصائص

  • الوصف

    string اختياري

    وصف للمورد يمكن لشخص عادي قراءته

  • id

    سلسلة

    معرّف المورد لنوع المحتوى المحدّد

Scope

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

نطاق ContentSetting. أحد الخيارات التالية: regular: إعداد للملف الشخصي العادي (يتم تطبيقه على الملف الشخصي للتصفّح المتخفي إذا لم يتم تجاوزه في مكان آخر) incognito\_session\_only: إعداد للملف الشخصي للتصفّح المتخفي لا يمكن ضبطه إلا أثناء جلسة التصفّح المتخفي ويتم حذفه عند انتهاء جلسة التصفّح المتخفي (يتجاوز الإعدادات العادية)

Enum

"regular"

"incognito_session_only"

SoundContentSetting

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

Enum

"allow"

"block"

الخصائص

automaticDownloads

تحدّد هذه السياسة ما إذا كان يُسمح للمواقع الإلكترونية بتنزيل عدة ملفات تلقائيًا. يجب اختيار إحدى القيم التالية: allow: للسماح للمواقع الإلكترونية بتنزيل ملفات متعددة تلقائيًا block: لعدم السماح للمواقع الإلكترونية بتنزيل ملفات متعددة تلقائيًا ask: لطلب الإذن عندما يريد موقع إلكتروني تنزيل ملفات تلقائيًا بعد الملف الأول القيمة التلقائية هي ask. عنوان URL الأساسي هو عنوان URL للإطار ذي المستوى الأعلى. ولا يتم استخدام عنوان URL الثانوي.

النوع

ContentSetting<MultipleAutomaticDownloadsContentSetting>

autoVerify

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

يحدّد هذا الإعداد ما إذا كان يُسمح للمواقع الإلكترونية باستخدام Private State Tokens API. ‫allow: السماح للمواقع الإلكترونية باستخدام واجهة برمجة التطبيقات Private State Tokens API block: حظر المواقع الإلكترونية من استخدام واجهة برمجة التطبيقات Private State Tokens API القيمة التلقائية هي allow. عند طلب set()، يجب أن يكون نمط عنوان URL الأساسي هو <all_urls>. ولا يتم استخدام عنوان URL الثانوي.

النوع

ContentSetting<AutoVerifyContentSetting>

camera

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

يحدّد هذا الإعداد ما إذا كان يُسمح للمواقع الإلكترونية بالوصول إلى الكاميرا. أحد الخيارات التالية: allow: السماح للمواقع الإلكترونية بالوصول إلى الكاميرا block: عدم السماح للمواقع الإلكترونية بالوصول إلى الكاميرا ask: طلب الإذن عندما يريد موقع إلكتروني الوصول إلى الكاميرا القيمة التلقائية هي ask. عنوان URL الأساسي هو عنوان URL للمستند الذي طلب الوصول إلى الكاميرا. ولا يتم استخدام عنوان URL الثانوي. ملاحظة: لا يكون الإعداد "السماح" صالحًا إذا كان كلا النمطين "<all_urls>".

النوع

ContentSetting<CameraContentSetting>

clipboard

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

تحدّد هذه السياسة ما إذا كان سيتم السماح للمواقع الإلكترونية بالوصول إلى الحافظة من خلال الإمكانات المتقدّمة لواجهة Async Clipboard API. تشمل الإمكانات "المتقدّمة" أي شيء بخلاف كتابة التنسيقات المضمّنة بعد إجراء تفاعلي من المستخدم، أي إمكانية القراءة وإمكانية كتابة تنسيقات مخصّصة وإمكانية الكتابة بدون إجراء تفاعلي من المستخدم. إحدى القيم التالية: allow: السماح للمواقع الإلكترونية باستخدام إمكانات الحافظة المتقدّمة block: عدم السماح للمواقع الإلكترونية باستخدام إمكانات الحافظة المتقدّمة ask: طلب الإذن عندما يريد موقع إلكتروني استخدام إمكانات الحافظة المتقدّمة القيمة التلقائية هي ask. عنوان URL الأساسي هو عنوان URL للمستند الذي طلب الوصول إلى الحافظة. ولا يتم استخدام عنوان URL الثانوي.

النوع

ContentSetting<ClipboardContentSetting>

cookies

يحدّد هذا الإعداد ما إذا كان سيتم السماح للمواقع الإلكترونية بضبط ملفات تعريف الارتباط والبيانات المحلية الأخرى. ‫allow: قبول ملفات تعريف الارتباط block: حظر ملفات تعريف الارتباط session\_only: قبول ملفات تعريف الارتباط للجلسة الحالية فقط القيمة التلقائية هي allow. عنوان URL الأساسي هو عنوان URL الذي يمثّل مصدر ملف تعريف الارتباط. عنوان URL الثانوي هو عنوان URL الخاص بالإطار ذي المستوى الأعلى.

النوع

ContentSetting<CookiesContentSetting>

fullscreen

تمّت إزالة هذا العمود. لم يعُد له أي تأثير. يتم الآن منح إذن ملء الشاشة تلقائيًا لجميع المواقع الإلكترونية. القيمة هي دائمًا allow.

النوع

ContentSetting<FullscreenContentSetting>

images

ما إذا كان سيتم عرض الصور أم لا إحدى القيم التالية: allow: عرض الصور block: عدم عرض الصور القيمة التلقائية هي allow. عنوان URL الأساسي هو عنوان URL للإطار ذي المستوى الأعلى. عنوان URL الثانوي هو عنوان URL للصورة.

النوع

ContentSetting<ImagesContentSetting>

javascript

ما إذا كان سيتم تشغيل JavaScript إحدى القيم التالية: allow: تشغيل JavaScript block: عدم تشغيل JavaScript القيمة التلقائية هي allow. عنوان URL الأساسي هو عنوان URL للإطار ذي المستوى الأعلى. ولا يتم استخدام عنوان URL الثانوي.

النوع

ContentSetting<JavascriptContentSetting>

location

تحديد ما إذا كان سيتم السماح بتحديد الموقع الجغرافي أحد الخيارات التالية: allow: السماح للمواقع الإلكترونية بتتبُّع موقعك الجغرافي block: عدم السماح للمواقع الإلكترونية بتتبُّع موقعك الجغرافي ask: السؤال قبل السماح للمواقع الإلكترونية بتتبُّع موقعك الجغرافي القيمة التلقائية هي ask. عنوان URL الأساسي هو عنوان URL للمستند الذي طلب بيانات الموقع الجغرافي. عنوان URL الثانوي هو عنوان URL للإطار ذي المستوى الأعلى (الذي قد يختلف أو لا يختلف عن عنوان URL الخاص بالطلب).

النوع

ContentSetting<LocationContentSetting>

microphone

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

يحدّد هذا الإعداد ما إذا كان يُسمح للمواقع الإلكترونية بالوصول إلى الميكروفون. يمكنك اختيار أحد الإعدادات التالية: allow: السماح للمواقع الإلكترونية بالوصول إلى الميكروفون block: عدم السماح للمواقع الإلكترونية بالوصول إلى الميكروفون ask: طلب الإذن عندما يريد موقع إلكتروني الوصول إلى الميكروفون القيمة التلقائية هي ask. عنوان URL الأساسي هو عنوان URL للمستند الذي طلب الوصول إلى الميكروفون. ولا يتم استخدام عنوان URL الثانوي. ملاحظة: لا يكون الإعداد "السماح" صالحًا إذا كان كلا النمطين "<all_urls>".

النوع

ContentSetting<MicrophoneContentSetting>

mouselock

تمّت إزالة هذا العمود. لم يعُد له أي تأثير. يتم الآن منح إذن قفل الماوس تلقائيًا لجميع المواقع الإلكترونية. القيمة هي دائمًا allow.

النوع

ContentSetting<MouselockContentSetting>

notifications

يحدّد هذا الإعداد ما إذا كان يُسمح للمواقع الإلكترونية بعرض إشعارات على سطح المكتب. إحدى القيم التالية: allow: السماح للمواقع الإلكترونية بعرض إشعارات على سطح المكتب block: عدم السماح للمواقع الإلكترونية بعرض إشعارات على سطح المكتب ask: طلب الإذن عندما يريد موقع إلكتروني عرض إشعارات على سطح المكتب القيمة التلقائية هي ask. عنوان URL الأساسي هو عنوان URL للمستند الذي يريد عرض الإشعار. ولا يتم استخدام عنوان URL الثانوي.

النوع

ContentSetting<NotificationsContentSetting>

plugins

تمّت إزالة هذا العمود. بعد إزالة توافق Flash في الإصدار 88 من Chrome، لم يعُد لهذا الإذن أي تأثير. القيمة هي دائمًا block. سيتم تجاهل المكالمات الواردة إلى set() وclear().

النوع

ContentSetting<PluginsContentSetting>

popups

يحدّد هذا الإعداد ما إذا كان سيتم السماح للمواقع الإلكترونية بعرض النوافذ المنبثقة. إحدى القيم التالية: allow: السماح للمواقع الإلكترونية بعرض النوافذ المنبثقة block: عدم السماح للمواقع الإلكترونية بعرض النوافذ المنبثقة القيمة التلقائية هي block. عنوان URL الأساسي هو عنوان URL للإطار ذي المستوى الأعلى. ولا يتم استخدام عنوان URL الثانوي.

النوع

ContentSetting<PopupsContentSetting>

unsandboxedPlugins

تمّت إزالة هذا العمود. في السابق، كانت هذه السياسة تتحكّم في ما إذا كان سيتم السماح للمواقع الإلكترونية بتشغيل المكوّنات الإضافية خارج وضع الحماية، ولكن بعد إزالة عملية وسيط Flash في الإصدار 88 من Chrome، لم يعُد لهذا الإذن أي تأثير. القيمة هي دائمًا block. سيتم تجاهل المكالمات الواردة إلى set() وclear().

النوع

ContentSetting<PpapiBrokerContentSetting>