chrome.permissions

refresh date: 2026-09-25 robots: noindex

الوصف

استخدِم واجهة برمجة التطبيقات chrome.permissions لطلب الأذونات الاختيارية المُعلَن عنها في وقت التشغيل بدلاً من وقت التثبيت، لكي يفهم المستخدمون سبب الحاجة إلى الأذونات ويمنحوا الأذونات الضرورية فقط.

نظرة عامة

تتوفّر تحذيرات بشأن الأذونات لوصف الإمكانات التي تمنحها واجهة برمجة التطبيقات، ولكن قد لا تكون بعض هذه التحذيرات واضحة. تتيح واجهة Permissions API للمطوّرين شرح تحذيرات الأذونات وتقديم ميزات جديدة تدريجيًا، ما يمنح المستخدمين مقدمة خالية من المخاطر حول الإضافة. بهذه الطريقة، يمكن للمستخدمين تحديد مستوى الوصول الذي يريدون منحه والميزات التي يريدون تفعيلها.

على سبيل المثال، الوظيفة الأساسية لإضافة الأذونات الاختيارية هي إلغاء صفحة علامة التبويب الجديدة. إحدى الميزات هي عرض هدف المستخدم لليوم. تتطلّب هذه الميزة إذن مساحة التخزين فقط، والذي لا يتضمّن تحذيرًا. تتضمّن الإضافة ميزة إضافية يمكن للمستخدمين تفعيلها من خلال النقر على الزر التالي:

زر الإضافة الذي يتيح ميزات إضافية

يتطلّب عرض أهم المواقع الإلكترونية للمستخدم الحصول على إذن topSites، والذي يتضمّن التحذير التالي.

تحذير بشأن الإضافة لواجهة برمجة التطبيقات topSites API

تنفيذ الأذونات الاختيارية

الخطوة 1: تحديد الأذونات المطلوبة والأذونات الاختيارية

يمكن أن تطلب الإضافة أذونات مطلوبة واختيارية. بشكل عام، عليك إجراء ما يلي:

  • استخدِم الأذونات المطلوبة عندما تكون ضرورية لوظائف الإضافة الأساسية.
  • استخدِم الأذونات الاختيارية عندما تكون مطلوبة للميزات الاختيارية في الإضافة.

مزايا الأذونات المطلوبة:

  • طلبات أقل: يمكن أن تطلب الإضافة من المستخدم مرة واحدة قبول جميع الأذونات.
  • تطوير أبسط: نضمن لك توفُّر الأذونات المطلوبة.

مزايا الأذونات الاختيارية:

  • أمان أفضل: يتم تشغيل الإضافات بأذونات أقل لأنّ المستخدمين يفعّلون الأذونات المطلوبة فقط.
  • توفير معلومات أفضل للمستخدمين: يمكن أن توضّح الإضافة سبب حاجتها إلى إذن معيّن عندما يفعّل المستخدم الميزة ذات الصلة.
  • ترقيات أسهل: عند ترقية الإضافة، لن يوقف Chrome الإضافة للمستخدمين إذا كانت الترقية تضيف أذونات اختيارية بدلاً من الأذونات المطلوبة.

الخطوة 2: الإعلان عن الأذونات الاختيارية في ملف البيان

يمكنك الإعلان عن الأذونات الاختيارية في ملف بيان الإضافة باستخدام المفتاح optional_permissions، مع استخدام التنسيق نفسه المستخدَم في حقل الأذونات:

{
  "name": "My extension",
  ...
  "optional_permissions": ["tabs"],
  "optional_host_permissions": ["https://www.google.com/"],
  ...
}

إذا أردت طلب مضيفين تكتشفهم فقط في وقت التشغيل، يمكنك تضمين "https://*/*" في حقل optional_host_permissions الخاص بالإضافة. يتيح لك ذلك تحديد أي مصدر في Permissions.origins طالما أنّه يتضمّن مخططًا مطابقًا.

الأذونات التي لا يمكن تحديدها على أنّها اختيارية

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

الإذن الوصف
"debugger" تُستخدم واجهة برمجة التطبيقات chrome.debugger كبديل لنقل بروتوكول تصحيح الأخطاء عن بُعد في Chrome.
"declarativeNetRequest" يمنح الإضافة إذن الوصول إلى واجهة برمجة التطبيقات chrome.declarativeNetRequest.
"devtools" تسمح هذه الإضافة بتوسيع وظائف أدوات مطوّري البرامج في Chrome.
"experimental" قناة Canary وقناة مطوّري البرامج فقط يمنح الإضافة إذن الوصول إلى واجهات برمجة التطبيقات chrome.experimental.
"geolocation" يسمح هذا الإذن للإضافة باستخدام واجهة برمجة التطبيقات الموقع الجغرافي في HTML5.
"mdns" يمنح الإضافة إذن الوصول إلى واجهة برمجة التطبيقات chrome.mdns.
"proxy" يمنح الإضافة إذن الوصول إلى واجهة برمجة التطبيقات chrome.proxy لإدارة إعدادات الخادم الوكيل في Chrome.
"tts" تُشغِّل واجهة برمجة التطبيقات chrome.tts ميزة تحويل النص إلى كلام (TTS) الاصطناعية.
"ttsEngine" تنفِّذ واجهة برمجة التطبيقات chrome.ttsEngine محرّك تحويل النص إلى كلام (TTS) باستخدام إضافة.
"wallpaper" نظام التشغيل Chrome فقط: استخدِم واجهة برمجة التطبيقات chrome.wallpaper لتغيير خلفية نظام التشغيل ChromeOS.

يمكنك الاطّلاع على الإفصاح عن الأذونات وتحذير المستخدمين لمزيد من المعلومات حول الأذونات المتاحة وتحذيراتها.

الخطوة 3: طلب الأذونات الاختيارية

اطلب الأذونات من خلال إجراء تفاعلي من المستخدم باستخدام permissions.request():

document.querySelector('#my-button').addEventListener('click', (event) => {
  // Permissions must be requested from inside a user gesture, like a button's
  // click handler.
  chrome.permissions.request({
    permissions: ['tabs'],
    origins: ['https://www.google.com/']
  }, (granted) => {
    // The callback argument will be true if the user granted the permissions.
    if (granted) {
      doSomething();
    } else {
      doSomethingElse();
    }
  });
});

يطلب Chrome من المستخدم إذا كانت إضافة الأذونات تؤدي إلى ظهور رسائل تحذير مختلفة عن تلك التي رآها المستخدم وقبلها من قبل. على سبيل المثال، قد ينتج عن الرمز السابق طلب مثل هذا:

مثال على طلب تأكيد الإذن

الخطوة 4: التحقّق من الأذونات الحالية للإضافة

للتحقّق مما إذا كانت الإضافة تتضمّن إذنًا معيّنًا أو مجموعة من الأذونات، استخدِم permission.contains():

chrome.permissions.contains({
  permissions: ['tabs'],
  origins: ['https://www.google.com/']
}, (result) => {
  if (result) {
    // The extension has the permissions.
  } else {
    // The extension doesn't have the permissions.
  }
});

الخطوة 5: إزالة الأذونات

يجب إزالة الأذونات عندما لا تعود بحاجة إليها. بعد إزالة أحد الأذونات، يؤدي استدعاء permissions.request() عادةً إلى إعادة إضافة الإذن بدون مطالبة المستخدم بذلك.

chrome.permissions.remove({
  permissions: ['tabs'],
  origins: ['https://www.google.com/']
}, (removed) => {
  if (removed) {
    // The permissions have been removed.
  } else {
    // The permissions have not been removed (e.g., you tried to remove
    // required permissions).
  }
});

الأنواع

Permissions

الخصائص

  • المصادر

    string[] اختياري

    قائمة أذونات المضيف، بما في ذلك الأذونات المحدّدة في مفتاحَي optional_permissions أو permissions في البيان، وتلك المرتبطة بنصوص المحتوى البرمجية.

  • أذونات

    string[] اختياري

    قائمة بالأذونات المُسمّاة (لا تتضمّن المضيفين أو المصادر).

الطُرق

contains()

Promise 
chrome.permissions.contains(
  permissions: Permissions,
  callback?: function,
): Promise<boolean>

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

المعلمات

  • أذونات

    الأذونات

  • callback

    function اختياري

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

    (result: boolean) => void

    • نتيجة

      قيمة منطقية

      تكون القيمة "صحيح" إذا كانت الإضافة تتضمّن الأذونات المحدّدة. إذا تم تحديد مصدر كإذن اختياري ونمط مطابقة نص برمجي للمحتوى، سيؤدي ذلك إلى عرض القيمة false ما لم يتم منح كلا الإذنَين.

المرتجعات

  • Promise<boolean>

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

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

getAll()

Promise 
chrome.permissions.getAll(
  callback?: function,
): Promise<Permissions>

للحصول على مجموعة الأذونات الحالية للإضافة

المعلمات

  • callback

    function اختياري

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

    (permissions: Permissions) => void

    • أذونات

      الأذونات

      الأذونات النشطة للإضافة يُرجى العِلم أنّ السمة origins ستحتوي على المصادر الممنوحة من تلك المحدّدة في المفتاحَين permissions وoptional_permissions في البيان وتلك المرتبطة بنصوص المحتوى البرمجية.

المرتجعات

  • Promise<Permissions>

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

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

remove()

Promise 
chrome.permissions.remove(
  permissions: Permissions,
  callback?: function,
): Promise<boolean>

لإزالة إمكانية الوصول إلى الأذونات المحدّدة إذا كانت هناك أي مشاكل في إزالة الأذونات، سيتم رفض الوعد.

المعلمات

  • أذونات

    الأذونات

  • callback

    function اختياري

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

    (removed: boolean) => void

    • تمت الإزالة

      قيمة منطقية

      صحيح إذا تمت إزالة الأذونات.

المرتجعات

  • Promise<boolean>

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

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

request()

Promise 
chrome.permissions.request(
  permissions: Permissions,
  callback?: function,
): Promise<boolean>

يطلب هذا الإجراء الوصول إلى الأذونات المحدّدة، ويعرض رسالة للمستخدم إذا لزم الأمر. يجب تحديد هذه الأذونات في حقل optional_permissions في ملف البيان أو أن تكون أذونات مطلوبة حجبها المستخدم. وسيتم تجاهل المسارات في أنماط المصدر. يمكنك طلب مجموعات فرعية من أذونات المصدر الاختيارية، على سبيل المثال، إذا حدّدت *://*\/* في قسم optional_permissions من البيان، يمكنك طلب http://example.com/. في حال حدوث أي مشاكل في طلب الأذونات، سيتم رفض الوعد.

المعلمات

  • أذونات

    الأذونات

  • callback

    function اختياري

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

    (granted: boolean) => void

    • تم منح الموافقة

      قيمة منطقية

      تكون القيمة "صحيح" إذا منح المستخدم الأذونات المحدّدة.

المرتجعات

  • Promise<boolean>

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

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

الفعاليات

onAdded

chrome.permissions.onAdded.addListener(
  callback: function,
)

يتم تنشيط هذا الحدث عندما تحصل الإضافة على أذونات جديدة.

المعلمات

  • callback

    دالة

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

    (permissions: Permissions) => void

onRemoved

chrome.permissions.onRemoved.addListener(
  callback: function,
)

يتم تنشيطه عند إزالة إذن الوصول إلى الأذونات من الإضافة.

المعلمات

  • callback

    دالة

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

    (permissions: Permissions) => void