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 والإصدارات الأحدث

تعداد

allow

"block"

CameraContentSetting

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

تعداد

allow

"block"

"ask"

ClipboardContentSetting

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

تعداد

allow

"block"

"ask"

ContentSetting

الخصائص

  • محو

    void

    وعد

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

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

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

    • التفاصيل

      عنصر

      • نطاق

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

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

    • callback

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

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

      () => void

    • returns

      Promise<void>

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

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

  • الحصول على

    void

    وعد

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

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

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

    • التفاصيل

      عنصر

      • الدردشة المتخفية

        boolean اختياري

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

      • primaryUrl

        سلسلة

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

      • resourceIdentifier

        ‫ResourceIdentifier اختياري

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

      • secondaryUrl

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

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

    • callback

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

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

      (details: object) => void

      • التفاصيل

        عنصر

        • الإعداد

          T

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

    • returns

      Promise<object>

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

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

  • getResourceIdentifiers

    void

    وعد

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

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

    • callback

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

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

      (resourceIdentifiers?: ResourceIdentifier[]) => void

      • resourceIdentifiers

        ResourceIdentifier[] اختياري

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

    • returns

      Promise<ResourceIdentifier[]>

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

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

  • محدّدة

    void

    وعد

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

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

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

    • التفاصيل

      عنصر

      • primaryPattern

        سلسلة

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

      • resourceIdentifier

        ‫ResourceIdentifier اختياري

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

      • نطاق

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

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

      • secondaryPattern

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

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

      • الإعداد

        أي واحد

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

    • callback

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

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

      () => void

    • returns

      Promise<void>

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

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

CookiesContentSetting

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

تعداد

allow

"block"

"session_only"

FullscreenContentSetting

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

القيمة

allow

ImagesContentSetting

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

تعداد

allow

"block"

JavascriptContentSetting

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

تعداد

allow

"block"

LocationContentSetting

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

تعداد

allow

"block"

"ask"

MicrophoneContentSetting

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

تعداد

allow

"block"

"ask"

MouselockContentSetting

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

القيمة

allow

MultipleAutomaticDownloadsContentSetting

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

تعداد

allow

"block"

"ask"

NotificationsContentSetting

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

تعداد

allow

"block"

"ask"

PluginsContentSetting

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

القيمة

"block"

PopupsContentSetting

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

تعداد

allow

"block"

PpapiBrokerContentSetting

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

القيمة

"block"

ResourceIdentifier

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

الخصائص

  • الوصف

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

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

  • id

    سلسلة

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

Scope

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

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

تعداد

"regular"

"incognito_session_only"

SoundContentSetting

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

تعداد

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

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

يحدّد هذا الإعداد ما إذا كان يُسمح للمواقع الإلكترونية بالوصول إلى الكاميرا. أحد الخيارات التالية: 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

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

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