chrome.permissions

refresh date: 2026-09-25 robots: noindex

شرح

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

نمای کلی

هشدارهای اجازه برای توصیف قابلیت‌های اعطاشده توسط میانای برنامه‌سازی کاربردی وجود دارد، اما برخی‌از این هشدارها ممکن است واضح نباشد. Permissions 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 موقعیت جغرافیایی API استفاده کند.
"mdns" به افزونه اجازه می‌دهد به chrome.mdns API دسترسی داشته باشد.
"proxy" به افزونه اجازه می‌دهد به میانای برنامه‌سازی کاربردی chrome.proxy دسترسی داشته باشد تا تنظیمات پراکسی Chrome را مدیریت کند.
"tts" chrome.tts API نوشتار به گفتار (TTS) ترکیبی را پخش می‌کند.
"ttsEngine" chrome.ttsEngine API موتور نوشتار به گفتار (TTS) را بااستفاده از افزونه پیاده‌سازی می‌کند.

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

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

اجازه‌ها را از درون اشاره کاربر بااستفاده از 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

    • نتیجه

      بولی

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

بازگشتی‌ها

  • Promise<boolean>

    Chrome نسخه ۹۶ و بالاتر

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

getAll()

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

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

پارامترها

  • بازخوانی

    تابع اختیاری

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

    (permissions: Permissions) => void

    • اجازه‌ها

      اجازه‌ها

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

بازگشتی‌ها

  • Promise<Permissions>

    Chrome نسخه ۹۶ و بالاتر

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

remove()

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

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

پارامترها

  • اجازه‌ها

    اجازه‌ها

  • بازخوانی

    تابع اختیاری

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

    (removed: boolean) => void

    • حذف شد

      بولی

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

بازگشتی‌ها

  • Promise<boolean>

    Chrome نسخه ۹۶ و بالاتر

    Promises فقط برای Manifest V3 و نسخه‌های جدیدتر پشتیبانی می‌شود، پلاتفرم‌های دیگر باید از 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 فقط برای Manifest V3 و نسخه‌های جدیدتر پشتیبانی می‌شود، پلاتفرم‌های دیگر باید از callbacks استفاده کنند.

رویدادها

onAdded

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

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

پارامترها

  • بازخوانی

    عملکرد

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

    (permissions: Permissions) => void

onRemoved

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

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

پارامترها

  • بازخوانی

    عملکرد

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

    (permissions: Permissions) => void