chrome.permissions

refresh date: 2026-09-25 robots: noindex

شرح

از chrome.permissions API برای درخواست اجازه‌های اختیاری اعلام‌شده در زمان اجرا به‌جای زمان نصب استفاده کنید تا کاربران متوجه شوند چرا این اجازه‌ها لازم است و فقط اجازه‌های ضروری را اعطا کنند.

نمای کلی

هشدارهای اجازه برای توصیف قابلیت‌های اعطاشده توسط میانای برنامه‌سازی کاربردی (API) وجود دارند، اما برخی‌از این هشدارها ممکن است واضح نباشند. «میانای برنامه‌سازی کاربردی اجازه‌ها» به توسعه‌دهندگان اجازه می‌دهد هشدارهای اجازه را توضیح دهند و ویژگی‌های جدید را به‌تدریج معرفی کنند که این امر باعث می‌شود کاربران بدون ریسک با افزونه آشنا شوند. به‌این‌ترتیب، کاربران می‌توانند مشخص کنند که مایلند چه مقدار دسترسی اعطا کنند و کدام ویژگی‌ها را می‌خواهند فعال کنند.

برای مثال، عملکرد اصلی افزونه اجازه‌های اختیاری لغو کردن صفحه زبانه جدید است. یکی از ویژگی‌ها نمایش هدف روزانه کاربر است. این ویژگی فقط به اجازه فضای ذخیره‌سازی نیاز دارد که شامل هشدار نمی‌شود. این افزونه ویژگی دیگری دارد که کاربران می‌توانند با کلیک کردن روی دکمه زیر آن را فعال کنند:

دکمه افزونه که ویژگی‌های اضافی را فعال می‌کند

نمایش سایت‌های برتر کاربر به اجازه topSites نیاز دارد که هشدار زیر را دارد.

هشدار افزونه برای topSites API

پیاده‌سازی اجازه‌های اختیاری

مرحله ۱: تصمیم بگیرید کدام اجازه‌ها الزامی و کدام اختیاری هستند

افزونه می‌تواند هم اجازه‌های الزامی و هم اجازه‌های اختیاری را اعلام کند. به‌طورکلی، باید:

  • از اجازه‌های لازم زمانی استفاده کنید که برای عملکرد اصلی افزونه‌تان موردنیاز باشند.
  • از اجازه‌های اختیاری زمانی استفاده کنید که برای ویژگی‌های اختیاری در افزونه‌تان لازم باشد.

مزایای اجازه‌های موردنیاز:

  • پیام‌واره‌های کمتر: افزونه می‌تواند یک‌بار از کاربر بخواهد همه اجازه‌ها را بپذیرد.
  • توسعه ساده‌تر: تضمین می‌شود که اجازه‌های لازم وجود داشته باشند.

مزایای اجازه‌های اختیاری:

  • امنیت بهتر: افزونه‌ها با اجازه‌های کمتری اجرا می‌شوند زیرا کاربران فقط اجازه‌هایی را فعال می‌کنند که لازم است.
  • اطلاعات بهتر برای کاربران: افزونه می‌تواند توضیح دهد که چرا به اجازه خاصی نیاز دارد وقتی کاربر ویژگی مربوطه را فعال می‌کند.
  • ارتقای آسان‌تر: وقتی افزونه‌تان را ارتقا می‌دهید، اگر ارتقا اجازه‌های اختیاری را به‌جای اجازه‌های الزامی اضافه کند، Chrome آن را برای کاربران غیرفعال نخواهد کرد.

مرحله ۲: اعلام اجازه‌های اختیاری در مانیفست

اجازه‌های اختیاری را در مانیفست افزونه با کلید 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 API به‌عنوان انتقال جایگزین برای پروتکل اشکال‌زدایی ازراه‌دور Chrome عمل می‌کند.
"declarativeNetRequest" به افزونه اجازه می‌دهد به میانای برنامه‌سازی کاربردی chrome.declarativeNetRequest دسترسی داشته باشد.
"devtools" به افزونه اجازه می‌دهد عملکرد Chrome DevTools را گسترش دهد.
"experimental" فقطCanary و کانال برنامه‌نویس‌ها. به افزونه اجازه می‌دهد به میاناهای برنامه‌سازی کاربردی chrome.experimental دسترسی داشته باشد.
"geolocation" به افزونه اجازه می‌دهد از میانای برنامه‌سازی کاربردی مکان‌یابی جغرافیایی HTML5 استفاده کند.
"mdns" به افزونه اجازه می‌دهد به chrome.mdns API دسترسی داشته باشد.
"proxy" به افزونه اجازه می‌دهد به میانای برنامه‌سازی کاربردی chrome.proxy دسترسی داشته باشد تا تنظیمات پراکسی Chrome را مدیریت کند.
"tts" chrome.tts API نوشتار به گفتار (TTS) ترکیبی را پخش می‌کند.
"ttsEngine" chrome.ttsEngine API موتور نوشتار به گفتار (TTS) را بااستفاده از افزونه پیاده‌سازی می‌کند.
"wallpaper" فقط ChromeOS. از chrome.wallpaper API برای تغییر کاغذدیواری ChromeOS استفاده کنید.

برای اطلاعات بیشتر درباره اجازه‌های دردسترس و هشدارهای آن‌ها، اعلام اجازه‌ها و هشدار به کاربران را مشاهده کنید.

مرحله ۳: درخواست اجازه‌های اختیاری

اجازه‌ها را از درون اشاره کاربر بااستفاده از 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 از کاربر درخواست می‌کند. برای مثال، کد قبلی ممکن است منجر به پیام‌واره‌ای مانند این شود:

پیام‌واره نمونه تأیید اجازه

مرحله ۴: اجازه‌های فعلی افزونه را بررسی کنید

برای بررسی اینکه آیا افزونه شما اجازه یا مجموعه‌ای از اجازه‌های خاص را دارد، از 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.
  }
});

مرحله ۵: برداشتن اجازه‌ها

وقتی دیگر به اجازه‌ها نیاز ندارید، باید آن‌ها را بردارید. پس‌از برداشته شدن اجازه، فراخوانی 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

مشخصات

  • مبدأها

    رشته[] اختیاری

    فهرست اجازه‌های میزبان، ازجمله اجازه‌های مشخص‌شده در کلیدهای optional_permissions یا permissions در مانیفست، و اجازه‌های مرتبط با اسکریپت‌های محتوا.

  • اجازه‌ها

    رشته[] اختیاری

    فهرست اجازه‌های نام‌گذاری‌شده (شامل میزبان‌ها یا مبدأها نمی‌شود).

روش‌ها

contains()

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

بررسی می‌کند که آیا افزونه اجازه‌های مشخص‌شده را دارد یا نه.

پارامترها

  • اجازه‌ها

    اجازه‌ها

  • تماس برگشتی

    تابع اختیاری

    پارامتر callback به‌صورت زیر است: 

    (result: boolean) => void

    • نتیجه

      بولی

      اگر افزونه اجازه‌های مشخص‌شده را داشته باشد، درست است. اگر مبدأ هم به‌عنوان اجازه اختیاری و هم به‌عنوان الگوی مطابقت اسکریپت محتوا مشخص شده باشد، این مورد false را برمی‌گرداند مگراینکه هر دو اجازه اعطا شده باشد.

بازگشتی‌ها

  • Promise<boolean>

    Chrome نسخه ۹۶ به بالا

    ‫Promises فقط برای «مانیفست نسخه ۳» و نسخه‌های جدیدتر پشتیبانی می‌شود، پلاتفرم‌های دیگر باید از callbacks استفاده کنند.

getAll()

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

مجموعه اجازه‌های فعلی افزونه را دریافت می‌کند.

پارامترها

  • تماس برگشتی

    تابع اختیاری

    پارامتر callback به‌صورت زیر است: 

    (permissions: Permissions) => void

    • اجازه‌ها

      اجازه‌ها

      اجازه‌های فعال افزونه. توجه داشته باشید که ویژگی origins حاوی مبدأهای اعطاشده از موارد مشخص‌شده در کلیدهای permissions و optional_permissions در مانیفست و موارد مرتبط با Content Scripts خواهد بود.

بازگشتی‌ها

  • Promise<Permissions>

    Chrome نسخه ۹۶ به بالا

    ‫Promises فقط برای «مانیفست نسخه ۳» و نسخه‌های جدیدتر پشتیبانی می‌شود، پلاتفرم‌های دیگر باید از callbacks استفاده کنند.

remove()

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

دسترسی به اجازه‌های مشخص‌شده را برمی‌دارد. اگر مشکلی در برداشتن اجازه‌ها وجود داشته باشد، وعده رد خواهد شد.

پارامترها

  • اجازه‌ها

    اجازه‌ها

  • تماس برگشتی

    تابع اختیاری

    پارامتر callback به‌صورت زیر است: 

    (removed: boolean) => void

    • حذف شد

      بولی

      اگر اجازه‌ها برداشته شده باشد، True (درست) است.

بازگشتی‌ها

  • Promise<boolean>

    Chrome نسخه ۹۶ به بالا

    ‫Promises فقط برای «مانیفست نسخه ۳» و نسخه‌های جدیدتر پشتیبانی می‌شود، پلاتفرم‌های دیگر باید از callbacks استفاده کنند.

request()

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

دسترسی به اجازه‌های مشخص‌شده را درخواست می‌کند و درصورت لزوم، پیام‌واره‌ای به کاربر نمایش می‌دهد. این اجازه‌ها باید در فیلد optional_permissions مانیفست تعریف شده باشند یا اجازه‌های الزامی باشند که کاربر از اعطای آن‌ها خودداری کرده است. مسیرهای الگوهای مبدأ نادیده گرفته خواهند شد. می‌توانید زیرمجموعه‌هایی از اجازه‌های اختیاری مبدأ را درخواست کنید؛ برای مثال، اگر *://*\/* را در بخش optional_permissions مانیفست مشخص کنید، می‌توانید http://example.com/ را درخواست کنید. اگر مشکلی در درخواست اجازه‌ها وجود داشته باشد، وعده رد خواهد شد.

پارامترها

  • اجازه‌ها

    اجازه‌ها

  • تماس برگشتی

    تابع اختیاری

    پارامتر callback به‌صورت زیر است: 

    (granted: boolean) => void

    • اعطاشده

      بولی

      اگر کاربر اجازه‌های مشخص‌شده را اعطا کرده باشد، مقدار True است.

بازگشتی‌ها

  • Promise<boolean>

    Chrome نسخه ۹۶ به بالا

    ‫Promises فقط برای «مانیفست نسخه ۳» و نسخه‌های جدیدتر پشتیبانی می‌شود، پلاتفرم‌های دیگر باید از callbacks استفاده کنند.

رویدادها

onAdded

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

وقتی افزونه اجازه‌های جدیدی دریافت می‌کند، فعال می‌شود.

پارامترها

  • تماس برگشتی

    عملکرد

    پارامتر callback به‌صورت زیر است: 

    (permissions: Permissions) => void

onRemoved

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

وقتی دسترسی به اجازه‌ها از افزونه برداشته شود، فعال می‌شود.

پارامترها

  • تماس برگشتی

    عملکرد

    پارامتر callback به‌صورت زیر است: 

    (permissions: Permissions) => void