chrome.contentSettings

الوصف

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

الأذونات

contentSettings

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

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

المفاهيم والاستخدام

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

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

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

أولوية النمط

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

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

  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

"السماح"

"حظر"

CameraContentSetting

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

Enum

"السماح"

"حظر"

"السؤال"

ClipboardContentSetting

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

Enum

"السماح"

"حظر"

"السؤال"

ContentSetting

أماكن إقامة

  • محو

    فراغ

    وعود

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

    تبدو دالة clear كما يلي: 

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

    • التفاصيل

      كائن

      • نطاق

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

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

    • رد الاتصال

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

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

      () => void

    • returns

      وعود <باطلة>

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

      تتوفّر الوعود في الإصدار 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&lt;object&gt;

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

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

  • getResourceIdentifiers

    فراغ

    وعود

    تبدو دالة getResourceIdentifiers كما يلي: 

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

    • رد الاتصال

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

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

      (resourceIdentifiers?: ResourceIdentifier[]) => void

      • resourceIdentifiers

        ResourceIdentifier[] اختياري

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

    • returns

      الوعد<ResourceIdentifier[]>

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

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

  • محدّدة

    فراغ

    وعود

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

    تبدو دالة set كما يلي: 

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

    • التفاصيل

      كائن

      • primaryPattern

        سلسلة

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

      • resourceIdentifier

        ResourceIdentifier اختياري

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

      • نطاق

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

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

      • secondaryPattern

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

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

      • الإعداد

        أي واحد

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

    • رد الاتصال

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

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

      () => void

    • returns

      وعود <باطلة>

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

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

CookiesContentSetting

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

Enum

"السماح"

"حظر"

&quot;session_only&quot;

FullscreenContentSetting

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

القيمة

"السماح"

ImagesContentSetting

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

Enum

"السماح"

"حظر"

JavascriptContentSetting

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

Enum

"السماح"

"حظر"

LocationContentSetting

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

Enum

"السماح"

"حظر"

"السؤال"

MicrophoneContentSetting

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

Enum

"السماح"

"حظر"

"السؤال"

MouselockContentSetting

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

القيمة

"السماح"

MultipleAutomaticDownloadsContentSetting

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

Enum

"السماح"

"حظر"

"السؤال"

NotificationsContentSetting

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

Enum

"السماح"

"حظر"

"السؤال"

PluginsContentSetting

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

القيمة

"حظر"

PopupsContentSetting

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

Enum

"السماح"

"حظر"

PpapiBrokerContentSetting

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

القيمة

"حظر"

ResourceIdentifier

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

أماكن إقامة

  • الوصف

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

    تمثّل هذه السمة وصف المورد سهل القراءة للمستخدم.

  • id

    سلسلة

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

Scope

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

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

Enum

"عادي"

"التصفّح_الجلسة_فقط"

أماكن إقامة

automaticDownloads

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

النوع

ContentSetting&lt;MultipleAutomaticDownloadsContentSetting&gt;

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

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

تحديد ما إذا كان سيتم السماح للمواقع الإلكترونية بالوصول إلى الكاميرا أحد 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&lt;ClipboardContentSetting&gt;

cookies

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

النوع

ContentSetting&lt;CookiesContentSetting&gt;

fullscreen

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

النوع

ContentSetting&lt;FullscreenContentSetting&gt;

images

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

النوع

ContentSetting&lt;ImagesContentSetting&gt;

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

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

تحديد ما إذا كان سيتم السماح للمواقع الإلكترونية بالوصول إلى الميكروفون أحد 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&lt;NotificationsContentSetting&gt;

plugins

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

النوع

ContentSetting&lt;PluginsContentSetting&gt;

popups

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

النوع

ContentSetting&lt;PopupsContentSetting&gt;

unsandboxedPlugins

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

النوع

ContentSetting&lt;PpapiBrokerContentSetting&gt;