chrome.contentSettings

الوصف

استخدِم واجهة برمجة التطبيقات 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 من مستودع chrome-extension-pattern.

الأنواع

AutoVerifyContentSetting

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

التعداد

CameraContentSetting

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

التعداد

ClipboardContentSetting

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

التعداد

ContentSetting

أماكن إقامة

  • محو

    void

    وعد

    يمكنك محو كل قواعد إعداد المحتوى التي حدّدتها هذه الإضافة.

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

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

    • التفاصيل

      كائن

      • نطاق

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

        الموضع المطلوب لمحوه (الإعداد التلقائي: عادي)

    • معاودة الاتصال

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

      تبدو معلَمة callback على النحو التالي: 

      ()=>void

    • returns

      Promise<void>

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

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

  • الحصول على

    void

    وعد

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

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

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

    • التفاصيل

      كائن

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

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

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

      • primaryUrl

        سلسلة

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

      • resourceIdentifier

        ResourceIdentifier اختياري

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

      • secondaryUrl

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

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

    • معاودة الاتصال

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

      تبدو معلَمة callback على النحو التالي: 

      (details: object)=>void

      • التفاصيل

        كائن

        • الإعداد

          T

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

    • returns

      Promise<object>

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

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

  • getResourceIdentifiers

    void

    وعد

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

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

    • معاودة الاتصال

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

      تبدو معلَمة callback على النحو التالي: 

      (resourceIdentifiers?: ResourceIdentifier[])=>void

      • resourceIdentifiers

        ResourceIdentifier[] اختيارية

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

    • returns

      Promise<ResourceIdentifier[]>

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

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

  • ضبط

    void

    وعد

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

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

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

    • التفاصيل

      كائن

      • primaryPattern

        سلسلة

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

      • resourceIdentifier

        ResourceIdentifier اختياري

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

      • نطاق

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

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

      • secondaryPattern

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

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

      • الإعداد

        أي فلتر

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

    • معاودة الاتصال

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

      تبدو معلَمة callback على النحو التالي: 

      ()=>void

    • returns

      Promise<void>

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

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

CookiesContentSetting

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

التعداد

"session_only"

FullscreenContentSetting

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

القيمة

ImagesContentSetting

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

التعداد

JavascriptContentSetting

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

التعداد

LocationContentSetting

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

التعداد

MicrophoneContentSetting

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

التعداد

MouselockContentSetting

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

القيمة

MultipleAutomaticDownloadsContentSetting

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

التعداد

NotificationsContentSetting

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

التعداد

PluginsContentSetting

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

القيمة

PopupsContentSetting

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

التعداد

PpapiBrokerContentSetting

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

القيمة

ResourceIdentifier

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

أماكن إقامة

  • الوصف

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

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

  • id

    سلسلة

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

Scope

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

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

التعداد

أماكن إقامة

automaticDownloads

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

النوع

ContentSetting<MultipleAutomaticDownloadsContentSetting>

autoVerify

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

يمكنك اختيار ما إذا كنت تريد السماح للمواقع الإلكترونية باستخدام واجهة برمجة التطبيقات للرموز المميّزة للحالة الخاصة. أحد 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 في الإصدار Chrome 88. القيمة هي block دائمًا. سيتم تجاهل المكالمات إلى set() وclear().

النوع

ContentSetting<PpapiBrokerContentSetting>