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 إضافية في الاعتبار. على سبيل المثال، يتم تحديد ما إذا كان الموقع الإلكتروني مسموحًا له بضبط 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-samples.

الأنواع

AutoVerifyContentSetting

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

التعداد

"allow"

"block"

CameraContentSetting

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

Enum

"allow"

"block"

"ask"

ClipboardContentSetting

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

Enum

"allow"

"block"

"ask"

ContentSetting

أماكن إقامة

  • محو

    غير صالح

    الوعد

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

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

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

    • التفاصيل

      عنصر

      • نطاق

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

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

    • رد الاتصال

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

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

      () => void

    • returns

      وعود <باطلة>

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

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

  • الحصول على

    غير صالح

    وعد بذلك

    يحصل على إعداد المحتوى الحالي لزوجَين محدّدَين من عناوين 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

        معرّف_المورد[] اختياري

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

    • returns

      Promise&lt;ResourceIdentifier[]&gt;

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

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

  • محدّدة

    غير صالح

    الوعد

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

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

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

    • التفاصيل

      عنصر

      • primaryPattern

        سلسلة

        نمط عنوان URL الأساسي. للاطلاع على تفاصيل حول تنسيق النمط، يمكنك الاطلاع على أنماط إعدادات المحتوى.

      • resourceIdentifier

        ResourceIdentifier اختياري

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

      • نطاق

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

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

      • secondaryPattern

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

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

      • الإعداد

        أي واحد

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

    • ردّ الاتصال

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

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

      () => void

    • returns

      وعود <باطلة>

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

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

CookiesContentSetting

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

Enum

"allow"

FullscreenContentSetting

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

القيمة

ImagesContentSetting

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

Enum

"allow"

"block"

JavascriptContentSetting

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

التعداد

"allow"

"block"

LocationContentSetting

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

التعداد

"allow"

"block"

"ask"

MicrophoneContentSetting

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

التعداد

"allow"

"block"

"ask"

MouselockContentSetting

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

القيمة

MultipleAutomaticDownloadsContentSetting

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

التعداد

"allow"

"block"

"ask"

NotificationsContentSetting

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

التعداد

"allow"

"block"

"ask"

PluginsContentSetting

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

القيمة

PopupsContentSetting

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

Enum

"allow"

"block"

PpapiBrokerContentSetting

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

القيمة

ResourceIdentifier

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

أماكن إقامة

  • الوصف

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

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

  • id

    سلسلة

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

Scope

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

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

Enum

"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&lt;AutoVerifyContentSetting&gt;

camera

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

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

النوع

ContentSetting&lt;CameraContentSetting&gt;

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&lt;FullscreenContentSetting&gt;

images

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

النوع

ContentSetting<ImagesContentSetting>

javascript

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

النوع

ContentSetting&lt;JavascriptContentSetting&gt;

location

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

النوع

ContentSetting&lt;LocationContentSetting&gt;

microphone

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

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

النوع

ContentSetting&lt;MicrophoneContentSetting&gt;

mouselock

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

النوع

ContentSetting&lt;MouselockContentSetting&gt;

notifications

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

النوع

ContentSetting<NotificationsContentSetting>

plugins

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

النوع

ContentSetting&lt;PluginsContentSetting&gt;

popups

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

النوع

ContentSetting<PopupsContentSetting>

unsandboxedPlugins

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

النوع

ContentSetting&lt;PpapiBrokerContentSetting&gt;