الوصف
استخدِم واجهة برمجة التطبيقات chrome.contentSettings لتغيير الإعدادات التي تتحكّم في ما إذا كان بإمكان المواقع الإلكترونية استخدام ميزات مثل ملفات تعريف الارتباط وجافا سكريبت والمكوّنات الإضافية. بشكل عام، تتيح لك إعدادات المحتوى تخصيص سلوك Chrome على أساس كل موقع إلكتروني على حدة بدلاً من تخصيصه على مستوى العالم.
الأذونات
contentSettingsيجب الإفصاح عن الإذن "contentSettings" في بيان الإضافة لاستخدام واجهة برمجة التطبيقات. على سبيل المثال:
{ "name": "My extension", ... "permissions": [ "contentSettings" ], ... } المفاهيم والاستخدام
أنماط إعدادات المحتوى
يمكنك استخدام الأنماط لتحديد المواقع الإلكترونية التي يؤثر فيها كل إعداد من إعدادات المحتوى. على سبيل المثال، https://*.youtube.com/* تحدّد youtube.com وجميع نطاقاتها الفرعية. إنّ بنية أنماط إعدادات المحتوى هي نفسها بنية أنماط المطابقة، مع بعض الاختلافات:
- بالنسبة إلى عناوين URL التي تبدأ بـ
httpوhttpsوftp، يجب أن يكون المسار حرف بدل (/*). أما بالنسبة إلى عناوين URL التي تبدأ بـfile، فيجب تحديد المسار بالكامل ويجب ألا يحتوي على أحرف بدل. - على عكس أنماط المطابقة، يمكن أن تحدّد أنماط إعدادات المحتوى رقم منفذ. في حال تحديد رقم منفذ، لن يتطابق النمط إلا مع المواقع الإلكترونية التي تستخدم هذا المنفذ. في حال عدم تحديد رقم منفذ، يتطابق النمط مع جميع المنافذ.
أولوية النمط
عندما تنطبق أكثر من قاعدة واحدة لإعدادات المحتوى على موقع إلكتروني معيّن، تكون الأولوية للقاعدة التي تتضمّن النمط الأكثر تحديدًا.
على سبيل المثال، يتم ترتيب الأنماط التالية حسب الأولوية:
https://www.example.com/*https://*.example.com/*(مطابقة example.com وجميع النطاقات الفرعية)<all_urls>(مطابقة كل عنوان URL)
تؤثر ثلاثة أنواع من أحرف البدل في مدى دقة النمط:
- أحرف البدل في المنفذ (على سبيل المثال
https://www.example.com:*/*) - أحرف البدل في المخطط (مثل
*://www.example.com:123/*) - أحرف البدل في اسم المضيف (مثل
https://*.example.com:123/*)
إذا كان أحد الأنماط أكثر تحديدًا من نمط آخر في جزء معيّن، ولكن أقل تحديدًا في جزء آخر، يتم التحقّق من الأجزاء المختلفة بالترتيب التالي: اسم المضيف، والمخطط، والمنفذ. على سبيل المثال، يتم ترتيب الأنماط التالية حسب الأولوية:
https://www.example.com:*/*تحدّد هذه السمة اسم المضيف والمخطط.*:/www.example.com:123/*ليس بالقدر نفسه، لأنّه على الرغم من أنّه يحدّد اسم المضيف، لا يحدّد المخطط.https://*.example.com:123/*أقلّ لأنّه يحدّد المنفذ والمخطط، ولكنّه يتضمّن حرف بدل في اسم المضيف.
الأنماط الأساسية والثانوية
يعتمد عنوان URL الذي يتم أخذه في الاعتبار عند تحديد إعدادات المحتوى التي يجب تطبيقها على نوع المحتوى. على سبيل المثال، تستند إعدادات contentSettings.notifications إلى عنوان URL المعروض في شريط العناوين. ويُطلق على عنوان URL هذا اسم عنوان URL "أساسي".
يمكن أن تأخذ بعض أنواع المحتوى عناوين URL إضافية في الاعتبار. على سبيل المثال، يتم تحديد ما إذا كان مسموحًا لموقع إلكتروني بضبط contentSettings.cookies استنادًا إلى عنوان URL لطلب HTTP (وهو عنوان URL الأساسي في هذه الحالة) بالإضافة إلى عنوان URL المعروض في المربّع المتعدد الاستخدامات (ويُطلق عليه عنوان URL "الثانوي").
إذا كانت قواعد متعدّدة تتضمّن أنماطًا أساسية وثانوية، تكون الأولوية للقاعدة التي تتضمّن النمط الأساسي الأكثر تحديدًا. إذا كانت هناك قواعد متعددة تتضمّن النمط الأساسي نفسه، تكون الأولوية للقاعدة التي تتضمّن النمط الثانوي الأكثر تحديدًا. على سبيل المثال، يتم ترتيب القائمة التالية من أزواج الأنماط الأساسية/الثانوية حسب الأولوية:
| الأولوية | النمط الأساسي | النمط الثانوي |
|---|---|---|
| 1 | https://www.moose.com/*، | https://www.wombat.com/* |
| 2 | https://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
Enum
"allow"
"block"
CameraContentSetting
Enum
"allow"
"block"
"ask"
ClipboardContentSetting
Enum
"allow"
"block"
"ask"
ContentSetting
الخصائص
- محو
void
محو جميع قواعد إعداد المحتوى التي تم ضبطها بواسطة هذه الإضافة
تبدو الدالة
clearعلى النحو التالي:(details: object) => {...}
- التفاصيل
عنصر
- نطاق
النطاق اختياري
مكان محو الإعداد (الإعداد التلقائي: عادي)
-
- returns
Promise<void>
الإصدار 96 من Chrome والإصدارات الأحدث
-
- الحصول على
void
تعرض هذه الطريقة إعدادات المحتوى الحالية لزوج معيّن من عناوين URL.
تبدو الدالة
getعلى النحو التالي:(details: object) => {...}
- التفاصيل
عنصر
- incognito
boolean اختياري
تحديد ما إذا كان سيتم التحقّق من إعدادات المحتوى لجلسة التصفّح المتخفي (القيمة التلقائية هي false)
- primaryUrl
سلسلة
عنوان URL الأساسي الذي يجب استرداد إعدادات المحتوى له. يُرجى العِلم أنّ معنى عنوان URL الأساسي يعتمد على نوع المحتوى.
- resourceIdentifier
ResourceIdentifier اختياري
معرّف أكثر تحديدًا لنوع المحتوى الذي يجب استرداد الإعدادات له
- secondaryUrl
سلسلة اختيارية
عنوان URL الثانوي الذي يجب استرداد إعدادات المحتوى له. القيمة التلقائية هي عنوان URL الأساسي. يُرجى العِلم أنّ معنى عنوان URL الثانوي يعتمد على نوع المحتوى، ولا تستخدم جميع أنواع المحتوى عناوين URL ثانوية.
-
- returns
Promise<object>
الإصدار 96 من Chrome والإصدارات الأحدث
-
- getResourceIdentifiers
void
تبدو الدالة
getResourceIdentifiersعلى النحو التالي:() => {...}- returns
Promise<ResourceIdentifier[]>
الإصدار 96 من Chrome والإصدارات الأحدث
-
- محدّدة
void
تطبيق قاعدة جديدة لإعدادات المحتوى
تبدو الدالة
setعلى النحو التالي:(details: object) => {...}
- التفاصيل
عنصر
- primaryPattern
سلسلة
نمط عنوان URL الأساسي لمعرفة تفاصيل حول تنسيق النمط، يُرجى الاطّلاع على أنماط إعدادات المحتوى.
- resourceIdentifier
ResourceIdentifier اختياري
المعرّف الخاص بنوع المحتوى
- نطاق
النطاق اختياري
مكان ضبط الإعداد (القيمة التلقائية: عادي).
- secondaryPattern
سلسلة اختيارية
نمط عنوان URL الثانوي يكون الإعداد التلقائي هو مطابقة جميع عناوين URL. للحصول على تفاصيل حول تنسيق النمط، يُرجى الاطّلاع على أنماط إعدادات المحتوى.
- الإعداد
أي واحد
الإعداد الذي تطبّقه هذه القاعدة راجِع وصف عناصر ContentSetting الفردية للاطّلاع على القيم المحتملة.
-
- returns
Promise<void>
الإصدار 96 من Chrome والإصدارات الأحدث
-
CookiesContentSetting
Enum
"allow"
"block"
"session_only"
FullscreenContentSetting
القيمة
"allow"
ImagesContentSetting
Enum
"allow"
"block"
JavascriptContentSetting
Enum
"allow"
"block"
LocationContentSetting
Enum
"allow"
"block"
"ask"
MicrophoneContentSetting
Enum
"allow"
"block"
"ask"
MouselockContentSetting
القيمة
"allow"
MultipleAutomaticDownloadsContentSetting
Enum
"allow"
"block"
"ask"
NotificationsContentSetting
Enum
"allow"
"block"
"ask"
PluginsContentSetting
القيمة
"block"
PopupsContentSetting
Enum
"allow"
"block"
PpapiBrokerContentSetting
القيمة
"block"
ResourceIdentifier
نوع المحتوى الوحيد الذي يستخدم معرّفات الموارد هو contentSettings.plugins. لمزيد من المعلومات، يُرجى الاطّلاع على معرّفات الموارد.
الخصائص
- الوصف
سلسلة اختيارية
وصف للمورد يمكن للمستخدم قراءته.
- id
سلسلة
معرّف المورد لنوع المحتوى المحدّد
Scope
نطاق ContentSetting أحد الخيارَينregular: إعداد للملف الشخصي العادي (الذي يرثه ملف التصفّح المتخفي إذا لم يتم إلغاء تحديده في مكان آخر)،incognito\_session\_only: إعداد لملف التصفّح المتخفي لا يمكن ضبطه إلا أثناء جلسة تصفّح متخفي ويتم حذفه عند انتهاء جلسة التصفّح المتخفي (يلغي الإعدادات العادية).
Enum
"regular"
"incognito_session_only"
الخصائص
automaticDownloads
تحديد ما إذا كان سيتم السماح للمواقع الإلكترونية بتنزيل عدّة ملفات تلقائيًا إحدى القيم التالية: allow: السماح للمواقع الإلكترونية بتنزيل عدّة ملفات تلقائيًا block: عدم السماح للمواقع الإلكترونية بتنزيل عدّة ملفات تلقائيًا ask: السؤال عمّا إذا كان سيتم السماح للموقع الإلكتروني بتنزيل الملفات تلقائيًا بعد الملف الأول القيمة التلقائية هي ask. عنوان URL الأساسي هو عنوان URL للإطار ذي المستوى الأعلى. لا يتم استخدام عنوان URL الثانوي.
autoVerify
تحديد ما إذا كان مسموحًا للمواقع الإلكترونية باستخدام Private State Tokens API أحد الخيارَين التاليَين allow: السماح للمواقع الإلكترونية باستخدام Private State Tokens API block: حظر المواقع الإلكترونية من استخدام Private State Tokens API القيمة التلقائية هي allow. عند طلب set()، يجب أن يكون نمط عنوان URL الأساسي <all_urls>. لا يتم استخدام عنوان URL الثانوي.
camera
يحدّد هذا الخيار ما إذا كان يُسمح للمواقع الإلكترونية بالوصول إلى الكاميرا. أحد الخيارات التالية: allow: السماح للمواقع الإلكترونية بالوصول إلى الكاميرا block: عدم السماح للمواقع الإلكترونية بالوصول إلى الكاميرا ask: السؤال عند طلب موقع إلكتروني الوصول إلى الكاميرا القيمة التلقائية هي ask. عنوان URL الأساسي هو عنوان URL للمستند الذي طلب الوصول إلى الكاميرا. لا يتم استخدام عنوان URL الثانوي. ملاحظة: لا يكون الإعداد "سماح" صالحًا إذا كان كلا النمطين "<all_urls>".
clipboard
تحدّد هذه السياسة ما إذا كان سيتم السماح للمواقع الإلكترونية بالوصول إلى الحافظة من خلال الإمكانات المتقدّمة لواجهة Async Clipboard API. تشمل إمكانات "المتقدّمة" أي شيء آخر غير كتابة التنسيقات المضمّنة بعد إجراء المستخدم، أي القدرة على القراءة، والقدرة على كتابة تنسيقات مخصّصة، والقدرة على الكتابة بدون إجراء المستخدم. أحد الخيارات التالية allow: السماح للمواقع الإلكترونية باستخدام إمكانات الحافظة المتقدّمة block: عدم السماح للمواقع الإلكترونية باستخدام إمكانات الحافظة المتقدّمة ask: السؤال عمّا إذا كان الموقع الإلكتروني يريد استخدام إمكانات الحافظة المتقدّمة القيمة التلقائية هي ask. عنوان URL الأساسي هو عنوان URL للمستند الذي طلب الوصول إلى الحافظة. لا يتم استخدام عنوان URL الثانوي.
cookies
تحديد ما إذا كان يُسمح للمواقع الإلكترونية بضبط ملفات تعريف الارتباط والبيانات المحلية الأخرى أحد الخيارات التالية allow: قبول ملفات تعريف الارتباط block: حظر ملفات تعريف الارتباط session\_only: قبول ملفات تعريف الارتباط للجلسة الحالية فقط القيمة التلقائية هي allow. عنوان URL الأساسي هو عنوان URL الذي يمثّل مصدر ملف تعريف الارتباط. عنوان URL الثانوي هو عنوان URL للإطار ذي المستوى الأعلى.
fullscreen
تمّت إزالة هذا العمود. لم يعُد له أي تأثير. يتم الآن منح إذن ملء الشاشة تلقائيًا لجميع المواقع الإلكترونية. القيمة هي allow دائمًا.
images
تحديد ما إذا كان سيتم عرض الصور إحدى القيمتين allow: عرض الصور block: عدم عرض الصور القيمة التلقائية هي allow. عنوان URL الأساسي هو عنوان URL للإطار ذي المستوى الأعلى. عنوان URL الثانوي هو عنوان URL الخاص بالصورة.
javascript
تحديد ما إذا كان سيتم تشغيل JavaScript إحدى القيمتين allow: تشغيل JavaScript block: عدم تشغيل JavaScript القيمة التلقائية هي allow. عنوان URL الأساسي هو عنوان URL للإطار ذي المستوى الأعلى. لا يتم استخدام عنوان URL الثانوي.
location
تحديد ما إذا كان سيتم السماح بخدمة "رصد الموقع الجغرافي" إحدى الخيارات التالية: allow: السماح للمواقع الإلكترونية بتتبُّع موقعك الجغرافي، block: عدم السماح للمواقع الإلكترونية بتتبُّع موقعك الجغرافي، ask: طلب الإذن قبل السماح للمواقع الإلكترونية بتتبُّع موقعك الجغرافي القيمة التلقائية هي ask. عنوان URL الأساسي هو عنوان URL للمستند الذي طلب بيانات الموقع الجغرافي. عنوان URL الثانوي هو عنوان URL للإطار ذي المستوى الأعلى (الذي قد يختلف أو لا يختلف عن عنوان URL المطلوب).
microphone
يحدّد هذا الخيار ما إذا كان يُسمح للمواقع الإلكترونية بالوصول إلى الميكروفون. أحد الخيارات التالية allow: السماح للمواقع الإلكترونية بالوصول إلى الميكروفون block: عدم السماح للمواقع الإلكترونية بالوصول إلى الميكروفون ask: السؤال عند طلب موقع إلكتروني الوصول إلى الميكروفون القيمة التلقائية هي ask. عنوان URL الأساسي هو عنوان URL للمستند الذي طلب الوصول إلى الميكروفون. لا يتم استخدام عنوان URL الثانوي. ملاحظة: لا يكون الإعداد "سماح" صالحًا إذا كان كلا النمطين "<all_urls>".
mouselock
تمّت إزالة هذا العمود. لم يعُد له أي تأثير. يتم الآن منح إذن قفل المؤشر تلقائيًا لجميع المواقع الإلكترونية. القيمة هي allow دائمًا.
notifications
يحدّد هذا الإعداد ما إذا كان يُسمح للمواقع الإلكترونية بعرض إشعارات على سطح المكتب. أحد الخيارات التالية: allow: السماح للمواقع الإلكترونية بعرض إشعارات على سطح المكتب block: عدم السماح للمواقع الإلكترونية بعرض إشعارات على سطح المكتب ask: السؤال عندما يريد أحد المواقع الإلكترونية عرض إشعارات على سطح المكتب القيمة التلقائية هي ask. عنوان URL الأساسي هو عنوان URL للمستند الذي يريد عرض الإشعار. لا يتم استخدام عنوان URL الثانوي.
plugins
تمّت إزالة هذا العمود. بعد إزالة إمكانية استخدام Flash في الإصدار 88 من Chrome، لم يعُد لهذا الإذن أي تأثير. القيمة هي block دائمًا. سيتم تجاهل المكالمات الواردة إلى set() وclear().
popups
يحدّد هذا الإعداد ما إذا كان يُسمح للمواقع الإلكترونية بعرض النوافذ المنبثقة. إحدى القيمتين allow: السماح للمواقع الإلكترونية بعرض النوافذ المنبثقة block: عدم السماح للمواقع الإلكترونية بعرض النوافذ المنبثقة القيمة التلقائية هي block. عنوان URL الأساسي هو عنوان URL للإطار ذي المستوى الأعلى. لا يتم استخدام عنوان URL الثانوي.
unsandboxedPlugins
تمّت إزالة هذا العمود. في السابق، كان هذا الإعداد يتحكّم في ما إذا كان سيتم السماح للمواقع الإلكترونية بتشغيل المكوّنات الإضافية بدون وضع الحماية، ولكن بعد إزالة عملية وسيط Flash في الإصدار 88 من Chrome، لم يعُد لهذا الإذن أي تأثير. القيمة هي block دائمًا. سيتم تجاهل المكالمات الواردة إلى set() وclear().