الوصف
استخدِم واجهة برمجة التطبيقات chrome.contentSettings
لتغيير الإعدادات التي تتحكّم في ما إذا كان بإمكان المواقع الإلكترونية استخدام ميزات، مثل ملفات تعريف الارتباط وJavaScript والمكوّنات الإضافية. وبشكل أكثر عمومية، تتيح لك إعدادات المحتوى تخصيص سلوك 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 من مستودع chrome-extension-pattern.
الأنواع
AutoVerifyContentSetting
التعداد
CameraContentSetting
التعداد
ClipboardContentSetting
التعداد
ContentSetting
أماكن إقامة
-
محو
void
وعديمكنك محو كل قواعد إعداد المحتوى التي حدّدتها هذه الإضافة.
تبدو الدالة
clear
على النحو التالي:(details: object, callback?: function) => {...}
-
التفاصيل
كائن
-
نطاق
النطاق اختياري
الموضع المطلوب لمحوه (الإعداد التلقائي: عادي)
-
-
معاودة الاتصال
الدالة اختيارية
تبدو معلَمة
callback
على النحو التالي:() => void
-
returns
Promise<void>
Chrome 96 والإصدارات الأحدثلا تتوفّر الوعود إلا في الإصدار 3 من 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 والإصدارات الأحدثلا تتوفّر الوعود إلا في الإصدار 3 من Manifest V3 والإصدارات الأحدث، وتحتاج الأنظمة الأساسية الأخرى إلى استخدام عمليات معاودة الاتصال.
-
-
getResourceIdentifiers
void
وعدتبدو الدالة
getResourceIdentifiers
على النحو التالي:(callback?: function) => {...}
-
معاودة الاتصال
الدالة اختيارية
تبدو معلَمة
callback
على النحو التالي:(resourceIdentifiers?: ResourceIdentifier[]) => void
-
resourceIdentifiers
ResourceIdentifier[] اختيارية
قائمة بمعرّفات الموارد لهذا النوع من المحتوى أو
undefined
إذا كان هذا النوع من المحتوى لا يستخدم معرّفات موارد.
-
-
returns
Promise<ResourceIdentifier[]>
Chrome 96 والإصدارات الأحدثلا تتوفّر الوعود إلا في الإصدار 3 من Manifest V3 والإصدارات الأحدث، وتحتاج الأنظمة الأساسية الأخرى إلى استخدام عمليات معاودة الاتصال.
-
-
ضبط
void
وعدتطبيق قاعدة جديدة لإعدادات المحتوى.
تبدو الدالة
set
على النحو التالي:(details: object, callback?: function) => {...}
-
التفاصيل
كائن
-
primaryPattern
سلسلة
نمط عنوان URL الأساسي. ولمزيد من التفاصيل عن تنسيق النمط، يُرجى الاطّلاع على أنماط إعدادات المحتوى.
-
resourceIdentifier
ResourceIdentifier اختياري
معرِّف المورد لنوع المحتوى.
-
نطاق
النطاق اختياري
مكان ضبط الإعداد (التلقائي: عادي)
-
secondaryPattern
سلسلة اختيارية
نمط عنوان URL الثانوي. الإعداد التلقائي لمطابقة جميع عناوين URL. للحصول على تفاصيل عن تنسيق النمط، راجع أنماط إعدادات المحتوى.
-
الإعداد
أي فلتر
تمثّل هذه السمة الإعداد الذي تطبّقه هذه القاعدة. يمكنك الاطّلاع على وصف كائنات ContentUsers الفردية للقيم المحتملة.
-
-
معاودة الاتصال
الدالة اختيارية
تبدو معلَمة
callback
على النحو التالي:() => void
-
returns
Promise<void>
Chrome 96 والإصدارات الأحدثلا تتوفّر الوعود إلا في الإصدار 3 من Manifest V3 والإصدارات الأحدث، وتحتاج الأنظمة الأساسية الأخرى إلى استخدام عمليات معاودة الاتصال.
-
CookiesContentSetting
التعداد
"session_only"
FullscreenContentSetting
القيمة
ImagesContentSetting
التعداد
JavascriptContentSetting
التعداد
LocationContentSetting
التعداد
MicrophoneContentSetting
التعداد
MouselockContentSetting
القيمة
MultipleAutomaticDownloadsContentSetting
التعداد
NotificationsContentSetting
التعداد
PluginsContentSetting
القيمة
PopupsContentSetting
التعداد
PpapiBrokerContentSetting
القيمة
ResourceIdentifier
إنّ نوع المحتوى الوحيد الذي يستخدم معرّفات الموارد هو contentSettings.plugins
. لمزيد من المعلومات، يُرجى الاطّلاع على معرِّفات الموارد.
أماكن إقامة
-
الوصف
سلسلة اختيارية
وصف مورد يمكن لشخص عادي قراءته.
-
id
سلسلة
معرِّف المورد لنوع المحتوى المحدّد.
Scope
نطاق Contentإعداد أحد الخيارات التالية:
regular
: إعداد للملف الشخصي العادي (الذي يكتسبه الملف الشخصي في وضع التصفّح المتخفي إذا لم يتم إلغاؤه في مكان آخر)
incognito\_session\_only
: إعداد للملف الشخصي في وضع التصفّح المتخفي الذي لا يمكن ضبطه إلا أثناء جلسة التصفّح المتخفي ويتم حذفه عند انتهاء جلسة التصفّح المتخفي (يتم إلغاء الإعدادات العادية)
التعداد
أماكن إقامة
automaticDownloads
ما إذا كنت تريد السماح للمواقع الإلكترونية بتنزيل عدّة ملفات تلقائيًا. أحد
allow
: السماح للمواقع الإلكترونية بتنزيل عدة ملفات تلقائيًا،
block
: عدم السماح للمواقع الإلكترونية بتنزيل عدة ملفات تلقائيًا،
ask
: السؤال عندما يريد أحد المواقع الإلكترونية تنزيل الملفات تلقائيًا بعد الملف الأول.
الإعداد التلقائي هو ask
.
عنوان URL الأساسي هو عنوان URL لإطار المستوى الأعلى. لم يتم استخدام عنوان URL الثانوي.
autoVerify
يمكنك اختيار ما إذا كنت تريد السماح للمواقع الإلكترونية باستخدام واجهة برمجة التطبيقات للرموز المميّزة للحالة الخاصة. أحد
allow
: السماح للمواقع الإلكترونية باستخدام واجهة برمجة التطبيقات Private State Tokens API
block
: يمكنك منع المواقع الإلكترونية من استخدام واجهة برمجة التطبيقات Private State Tokens API.
الإعداد التلقائي هو allow
.
عنوان URL الأساسي هو عنوان URL لإطار المستوى الأعلى. لم يتم استخدام عنوان URL الثانوي. ملاحظة: عند طلب الرقم set()
، يجب أن يكون النمط الأساسي هو .
camera
ما إذا كان سيتم السماح للمواقع الإلكترونية بالوصول إلى الكاميرا أم لا. أحد
allow
: السماح للمواقع الإلكترونية بالوصول إلى الكاميرا
block
: عدم السماح للمواقع الإلكترونية بالوصول إلى الكاميرا
ask
: طلب الإذن عندما يطلب موقع إلكتروني الوصول إلى الكاميرا
الإعداد التلقائي هو ask
.
عنوان URL الأساسي هو عنوان URL للمستند الذي طلب الوصول إلى الكاميرا. لم يتم استخدام عنوان URL الثانوي.
ملاحظة: إعداد "السماح" غير صالح إذا كان كلا النمطين "'.
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 الثانوي.
ملاحظة: إعداد "السماح" غير صالح إذا كان كلا النمطين "'.
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 في الإصدار Chrome 88. القيمة هي block
دائمًا. سيتم تجاهل المكالمات إلى set()
وclear()
.