chrome.contentSettings

الوصف

استخدِم واجهة برمجة التطبيقات chrome.contentSettings لتغيير الإعدادات التي تتحكّم في إمكانية استخدام المواقع الإلكترونية لميزات مثل ملفات تعريف الارتباط وجافا سكريبت والمكونات الإضافية. بشكل عام، تتيح لك إعدادات المحتوى تخصيص سلوك 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

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

Enum

"allow"

"block"

"ask"

ClipboardContentSetting

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

Enum

"allow"

"block"

"ask"

ContentSetting

أماكن إقامة

  • محو

    غير صالح

    الوعد

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

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

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

    • التفاصيل

      عنصر

      • نطاق

        النطاق اختياري

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

    • ردّ الاتصال

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

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

      () => void

    • returns

      Promise<void>

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

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

  • الحصول على

    غير صالح

    الوعد

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

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

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

    • التفاصيل

      عنصر

      • وضع التصفّح المتخفي

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

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

      • primaryUrl

        سلسلة

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

      • resourceIdentifier

        ‫ResourceIdentifier اختياري

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

      • secondaryUrl

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

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

    • ردّ الاتصال

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

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

      (details: object) => void

      • التفاصيل

        عنصر

        • الإعداد

          T

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

    • returns

      Promise<object>

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

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

  • getResourceIdentifiers

    غير صالح

    الوعد

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

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

    • ردّ الاتصال

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

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

      (resourceIdentifiers?: ResourceIdentifier[]) => void

      • resourceIdentifiers

        ResourceIdentifier[] اختياري

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

    • returns

      Promise<ResourceIdentifier[]>

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

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

  • محدّدة

    غير صالح

    الوعد

    تُطبِّق قاعدة إعدادات محتوى جديدة.

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

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

    • التفاصيل

      عنصر

      • primaryPattern

        سلسلة

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

      • resourceIdentifier

        ‫ResourceIdentifier اختياري

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

      • نطاق

        النطاق اختياري

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

      • secondaryPattern

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

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

      • الإعداد

        أي واحد

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

    • ردّ الاتصال

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

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

      () => void

    • returns

      Promise<void>

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

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

CookiesContentSetting

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

Enum

"allow"

"block"

"session_only"

FullscreenContentSetting

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

القيمة

"allow"

ImagesContentSetting

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

Enum

"allow"

"block"

JavascriptContentSetting

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

Enum

"allow"

"block"

LocationContentSetting

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

Enum

"allow"

"block"

"ask"

MicrophoneContentSetting

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

Enum

"allow"

"block"

"ask"

MouselockContentSetting

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

القيمة

"allow"

MultipleAutomaticDownloadsContentSetting

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

Enum

"allow"

"block"

"ask"

NotificationsContentSetting

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

Enum

"allow"

"block"

"ask"

PluginsContentSetting

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

القيمة

"block"

PopupsContentSetting

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

Enum

"allow"

"block"

PpapiBrokerContentSetting

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

القيمة

"block"

ResourceIdentifier

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

أماكن إقامة

  • الوصف

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

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

  • id

    سلسلة

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

Scope

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

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

Enum

"regular"

"incognito_session_only"

أماكن إقامة

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. عنوان URL الأساسي هو عنوان URL للإطار ذي المستوى الأعلى. عدم استخدام عنوان URL الثانوي ملاحظة: عند الاتصال بالرقم set()، يجب أن يكون النمط الأساسي .

النوع

ContentSetting<AutoVerifyContentSetting>

camera

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

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

النوع

ContentSetting<CameraContentSetting>

clipboard

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

يحدد هذا الخيار ما إذا كان سيتم السماح للمواقع الإلكترونية بالوصول إلى الحافظة من خلال الإمكانات المتقدّمة لواجهة برمجة التطبيقات 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

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

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

النوع

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>