chrome.contentSettings

refresh date: 2026-09-25 robots: noindex

شرح

از chrome.contentSettings API برای تغییر تنظیماتی استفاده کنید که کنترل می‌کنند آیا وب‌سایت‌ها می‌توانند از ویژگی‌هایی مانند کوکی‌ها، جاوااسکریپت و افزونه‌ها استفاده کنند. به‌طور کلی، تنظیمات محتوا به شما امکان می‌دهد رفتار Chrome را به‌جای اینکه به‌صورت سراسری سفارشی‌سازی کنید، به‌صورت جداگانه برای هر سایت سفارشی‌سازی کنید.

اجازه‌ها

contentSettings

مانیفست

برای استفاده از API، باید اجازه «contentSettings» را در مانیفست افزونه‌تان اعلام کنید. برای مثال:

{
  "name": "My extension",
  ...
  "permissions": [
    "contentSettings"
  ],
  ...
}

الگوهای تنظیم محتوا

می‌توانید از الگوها برای مشخص کردن وب‌سایت‌هایی که هر تنظیم محتوا بر آن‌ها تأثیر می‌گذارد استفاده کنید. برای مثال، https://*.youtube.com/* youtube.com و همه زیردامنه‌های آن را مشخص می‌کند. نحو الگوهای تنظیم محتوا مانند الگوهای تطابق است، با چند تفاوت:

  • برای نشانی‌های وب http،‏ https، و ftp، مسیر باید نویسه عام (/*) باشد. برای نشانی‌های وب file، مسیر باید کاملاً مشخص باشد و نباید حاوی نویسه عام باشد.
  • برخلاف الگوهای تطابق، الگوهای تنظیمات محتوا می‌توانند شماره درگاه را مشخص کنند. اگر شماره درگاه مشخص شده باشد، الگو فقط با وب‌سایت‌هایی که آن درگاه را دارند مطابقت دارد. اگر شماره درگاهی مشخص نشده باشد، الگو با همه درگاه‌ها مطابقت دارد.

اولویت الگو

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

برای مثال، الگوهای زیر براساس اولویت مرتب شده‌اند:

  1. https://www.example.com/*
  2. https://*.example.com/* (مطابق با example.com و همه زیردامنه‌ها)
  3. ‫<all_urls> (مطابقت با همه نشانی‌های وب)

سه نوع نویسه عام بر میزان خاص بودن الگو تأثیر می‌گذارد:

  • نویسه‌های عام در درگاه (برای مثال https://www.example.com:*/*)
  • نویسه‌های عام در طرح (برای مثال *://www.example.com:123/*)
  • نویسه‌های عام در نام میزبان (برای مثال https://*.example.com:123/*)

اگر الگویی در یک بخش خاص‌تر از الگوی دیگر باشد اما در بخش دیگر کمتر خاص باشد، بخش‌های مختلف به‌ترتیب زیر بررسی می‌شوند: نام میزبان، طرح، درگاه. برای مثال، الگوهای زیر براساس اولویت مرتب شده‌اند:

  1. https://www.example.com:*/* نام میزبان و طرح را مشخص می‌کند.
  2. *:/www.example.com:123/* نه چندان بالا، زیرا اگرچه نام میزبان را مشخص می‌کند، اما طرح را مشخص نمی‌کند.
  3. https://*.example.com:123/* پایین‌تر است زیرا اگرچه درگاه و طرح را مشخص می‌کند، اما در نام میزبان دارای نویسه عام است.

الگوهای اصلی و فرعی

نشانی وبی که هنگام تصمیم‌گیری درباره تنظیم محتوای اعمال‌شده درنظر گرفته می‌شود به نوع محتوا بستگی دارد. برای مثال، برای contentSettings.notifications تنظیمات براساس نشانی وب نشان‌داده‌شده در omnibox است. این نشانی وب، نشانی وب «اصلی» نامیده می‌شود.

برخی‌از انواع محتوا می‌توانند نشانی‌های وب بیشتری را درنظر بگیرند. برای مثال، اینکه آیا سایتی مجاز است contentSettings.cookies تنظیم کند یا نه براساس نشانی وب درخواست HTTP (که در این مورد نشانی وب اصلی است) و همچنین نشانی وب نشان‌داده‌شده در همه‌جانبه‌باکس (که نشانی وب «ثانویه» نامیده می‌شود) تصمیم‌گیری می‌شود.

اگر چند قانون دارای الگوهای اصلی و فرعی باشند، قانونی که الگوی اصلی خاص‌تری دارد اولویت دارد. اگر چند قانون الگوی اصلی یکسانی داشته باشند، قانونی که الگوی فرعی خاص‌تری دارد اولویت دارد. برای مثال، فهرست زیر از جفت‌های الگوی اصلی/فرعی براساس اولویت مرتب شده است:

تقدمالگوی اصلیالگوی ثانویه
1https://www.moose.com/*،https://www.wombat.com/*
2https://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

Chrome نسخه ۱۱۳ به بالا

شمارشی

«مجاز کردن»

«مسدود کردن»

CameraContentSetting

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

شمارشی

«مجاز کردن»

«مسدود کردن»

«ask»

ClipboardContentSetting

Chrome نسخه ۱۲۱ و بالاتر

شمارشی

«مجاز کردن»

«مسدود کردن»

«ask»

ContentSetting

مشخصات

  • پاک کردن

    باطل

    Promise

    همه قوانین تنظیم محتوا را که این افزونه تنظیم کرده است پاک کنید.

    تابع clear به‌صورت زیر است: 

    (details: object, callback?: function) => {...}

    • جزئیات

      شیء

      • محدوده

        محدوده اختیاری

        محل پاک کردن تنظیم (پیش‌فرض: معمولی).

    • تماس برگشتی

      تابع اختیاری

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

      () => void

    • returns

      Promise<void>

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

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

  • دریافت

    باطل

    Promise

    تنظیم محتوای فعلی را برای جفت نشانی‌های وب داده‌شده دریافت می‌کند.

    تابع get به‌صورت زیر است: 

    (details: object, callback?: function) => {...}

    • جزئیات

      شیء

      • ناشناس

        بولی اختیاری

        اینکه تنظیمات محتوا برای جلسه ناشناس بررسی شود یا نه. (پیش‌فرض نادرست)

      • primaryUrl

        رشته

        نشانی وب اصلی که تنظیم محتوا باید برای آن بازیابی شود. توجه داشته باشید که معنی نشانی وب اصلی به نوع محتوا بستگی دارد.

      • resourceIdentifier

        ResourceIdentifier اختیاری

        شناسه دقیق‌تر نوع محتوایی که تنظیمات باید برای آن بازیابی شود.

      • secondaryUrl

        رشته اختیاری

        نشانی وب ثانویه‌ای که تنظیم محتوا باید برای آن بازیابی شود. به‌طور پیش‌فرض روی نشانی وب اصلی تنظیم می‌شود. توجه داشته باشید که معنی نشانی وب ثانویه به نوع محتوا بستگی دارد و همه انواع محتوا از نشانی وب ثانویه استفاده نمی‌کنند.

    • تماس برگشتی

      تابع اختیاری

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

      (details: object) => void

      • جزئیات

        شیء

        • تنظیم

          T

          تنظیم محتوا. برای مقادیر ممکن، شرح اشیاء ContentSetting تکی را ببینید.

    • returns

      Promise<object>

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

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

  • getResourceIdentifiers

    باطل

    Promise

    تابع getResourceIdentifiers به‌صورت زیر است: 

    (callback?: function) => {...}

    • تماس برگشتی

      تابع اختیاری

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

      (resourceIdentifiers?: ResourceIdentifier[]) => void

      • resourceIdentifiers

        ResourceIdentifier[] اختیاری

        فهرستی از شناسه‌های منبع برای این نوع محتوا، یا undefined اگر این نوع محتوا از شناسه‌های منبع استفاده نمی‌کند.

    • returns

      Promise<ResourceIdentifier[]>

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

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

  • تنظیم

    باطل

    Promise

    قانون تنظیم محتوای جدیدی را اعمال می‌کند.

    تابع set به‌صورت زیر است: 

    (details: object, callback?: function) => {...}

    • جزئیات

      شیء

      • primaryPattern

        رشته

        الگوی نشانی وب اصلی. برای جزئیات بیشتر درباره قالب الگو، به الگوهای تنظیم محتوا مراجعه کنید.

      • resourceIdentifier

        ResourceIdentifier اختیاری

        شناسه منبع برای نوع محتوا.

      • محدوده

        محدوده اختیاری

        محل تنظیم کردن تنظیمات (پیش‌فرض: معمولی).

      • secondaryPattern

        رشته اختیاری

        الگوی نشانی وب ثانویه. به‌طور پیش‌فرض با همه نشانی‌های وب مطابقت دارد. برای جزئیات مربوط به قالب الگو، به الگوهای تنظیم محتوا مراجعه کنید.

      • تنظیم

        همه

        تنظیمی که این قانون اعمال می‌کند. برای مقادیر ممکن، شرح اشیاء ContentSetting تکی را ببینید.

    • تماس برگشتی

      تابع اختیاری

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

      () => void

    • returns

      Promise<void>

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

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

CookiesContentSetting

Chrome نسخه ۴۴ به بالا

شمارشی

«مجاز کردن»

«مسدود کردن»

"session_only"

FullscreenContentSetting

Chrome نسخه ۴۴ به بالا

مقدار

«مجاز کردن»

ImagesContentSetting

Chrome نسخه ۴۴ به بالا

شمارشی

«مجاز کردن»

«مسدود کردن»

JavascriptContentSetting

Chrome نسخه ۴۴ به بالا

شمارشی

«مجاز کردن»

«مسدود کردن»

LocationContentSetting

Chrome نسخه ۴۴ به بالا

شمارشی

«مجاز کردن»

«مسدود کردن»

«ask»

MicrophoneContentSetting

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

شمارشی

«مجاز کردن»

«مسدود کردن»

«ask»

MouselockContentSetting

Chrome نسخه ۴۴ به بالا

مقدار

«مجاز کردن»

MultipleAutomaticDownloadsContentSetting

Chrome نسخه ۴۴ به بالا

شمارشی

«مجاز کردن»

«مسدود کردن»

«ask»

NotificationsContentSetting

Chrome نسخه ۴۴ به بالا

شمارشی

«مجاز کردن»

«مسدود کردن»

«ask»

PluginsContentSetting

Chrome نسخه ۴۴ به بالا

مقدار

«مسدود کردن»

PopupsContentSetting

Chrome نسخه ۴۴ به بالا

شمارشی

«مجاز کردن»

«مسدود کردن»

PpapiBrokerContentSetting

Chrome نسخه ۴۴ به بالا

مقدار

«مسدود کردن»

ResourceIdentifier

تنها نوع محتوایی که از شناسه‌های منبع استفاده می‌کند contentSettings.plugins است. برای اطلاعات بیشتر، شناسه‌های منبع را ببینید.

مشخصات

  • description

    رشته اختیاری

    شرح قابل‌خواندن برای انسان از منبع.

  • id

    رشته

    شناسه منبع برای نوع محتوای ارائه‌شده.

Scope

Chrome نسخه ۴۴ به بالا

محدوده ContentSetting. یکی از regular: تنظیم برای نمایه معمولی (که اگر در جای دیگری لغو نشود، توسط نمایه ناشناس به ارث برده می‌شود)، incognito\_session\_only: تنظیم برای نمایه ناشناس که فقط درطول جلسه ناشناس می‌تواند تنظیم شود و وقتی جلسه ناشناس به‌پایان می‌رسد حذف می‌شود (تنظیمات معمولی را لغو می‌کند).

شمارشی

«معمولی»

"incognito_session_only"

SoundContentSetting

Chrome نسخه ۱۴۱ به بالا

شمارشی

«مجاز کردن»

«مسدود کردن»

مشخصات

automaticDownloads

آیا به سایت‌ها اجازه داده شود چندین فایل را به‌طور خودکار بارگیری کنند. یکی از allow: به سایت‌ها اجازه داده شود چندین فایل را به‌طور خودکار بارگیری کنند، block: به سایت‌ها اجازه داده نشود چندین فایل را به‌طور خودکار بارگیری کنند، ask: وقتی سایتی می‌خواهد پس‌از اولین فایل، فایل‌های دیگری را به‌طور خودکار بارگیری کند، از شما سؤال شود. پیش‌فرض ask است. نشانی وب اصلی همان نشانی وب قاب سطح بالا است. از نشانی وب ثانویه استفاده نمی‌شود.

نوع

ContentSetting<MultipleAutomaticDownloadsContentSetting>

autoVerify

Chrome نسخه ۱۱۳ به بالا

آیا به سایت‌ها اجازه داده شود از Private State Tokens API استفاده کنند. یکی از این گزینه‌ها: allow: به سایت‌ها اجازه دهید از Private State Tokens API استفاده کنند، block: سایت‌ها را از استفاده از Private State Tokens API مسدود کنید. پیش‌فرض allow است. هنگام فراخوانی set()، الگوی نشانی وب اصلی باید <all_urls> باشد. از نشانی وب ثانویه استفاده نمی‌شود.

نوع

ContentSetting<AutoVerifyContentSetting>

camera

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

آیا به سایت‌ها اجازه داده شود به دوربین دسترسی داشته باشند. یکی از allow: به سایت‌ها اجازه داده شود به دوربین دسترسی داشته باشند، block: به سایت‌ها اجازه داده نشود به دوربین دسترسی داشته باشند، ask: وقتی سایتی می‌خواهد به دوربین دسترسی داشته باشد، پرسیده شود. پیش‌فرض ask است. نشانی وب اصلی نشانی وب سندی است که دسترسی به دوربین را درخواست کرده است. از نشانی وب ثانویه استفاده نمی‌شود. توجه: اگر هر دو الگو «<all_urls>» باشد، تنظیم «مجاز» معتبر نیست.

نوع

ContentSetting<CameraContentSetting>

clipboard

Chrome نسخه ۱۲۱ و بالاتر

آیا به سایت‌ها اجازه داده شود ازطریق قابلیت‌های پیشرفته Async Clipboard API به بریده‌دان دسترسی داشته باشند. قابلیت‌های «پیشرفته» شامل هر چیزی به‌جز نوشتن قالب‌های داخلی پس‌از اشاره کاربر می‌شود، یعنی توانایی خواندن، توانایی نوشتن قالب‌های سفارشی، و توانایی نوشتن بدون اشاره کاربر. یکی از allow: به سایت‌ها اجازه داده شود از قابلیت‌های پیشرفته بریده‌دان استفاده کنند، block: به سایت‌ها اجازه داده نشود از قابلیت‌های پیشرفته بریده‌دان استفاده کنند، ask: وقتی سایتی می‌خواهد از قابلیت‌های پیشرفته بریده‌دان استفاده کند، پرسیده شود. پیش‌فرض ask است. نشانی وب اصلی نشانی وب سندی است که دسترسی به بریده‌دان را درخواست کرده است. از نشانی وب ثانویه استفاده نمی‌شود.

نوع

ContentSetting<ClipboardContentSetting>

cookies

اینکه آیا به وب‌سایت‌ها اجازه داده شود کوکی‌ها و دیگر داده‌های محلی را تنظیم کنند یا نه. یکی از allow: پذیرفتن کوکی‌ها، block: مسدود کردن کوکی‌ها، session\_only: پذیرفتن کوکی‌ها فقط برای جلسه فعلی. پیش‌فرض allow است. نشانی وب اصلی نشانی وبی است که نشان‌دهنده مبدأ کوکی است. نشانی وب ثانویه نشانی وب قاب سطح بالا است.

نوع

ContentSetting<CookiesContentSetting>

fullscreen

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

نوع

ContentSetting<FullscreenContentSetting>

images

تصاویر نشان داده شود یا نه. یکی از allow: نمایش تصاویر، block: تصاویر نشان داده نشود. پیش‌فرض allow است. نشانی وب اصلی همان نشانی وب قاب سطح بالا است. نشانی وب ثانویه نشانی وب تصویر است.

نوع

ContentSetting<ImagesContentSetting>

javascript

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

نوع

ContentSetting<JavascriptContentSetting>

location

آیا Geolocation مجاز باشد یا نه. یکی از این گزینه‌ها: allow: به سایت‌ها اجازه داده شود مکان فیزیکی شما را ردیابی کنند، block: به سایت‌ها اجازه داده نشود مکان فیزیکی شما را ردیابی کنند، ask: قبل‌از اینکه به سایت‌ها اجازه داده شود مکان فیزیکی شما را ردیابی کنند، از شما سؤال شود. پیش‌فرض ask است. نشانی وب اصلی نشانی وب سندی است که داده‌های مکان را درخواست کرده است. نشانی وب ثانویه نشانی وب قاب سطح بالا است (که ممکن است با نشانی وب درخواست‌کننده متفاوت باشد یا نباشد).

نوع

ContentSetting<LocationContentSetting>

microphone

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

آیا به سایت‌ها اجازه داده شود به میکروفون دسترسی داشته باشند. یکی از allow: به سایت‌ها اجازه داده شود به میکروفون دسترسی داشته باشند، block: به سایت‌ها اجازه داده نشود به میکروفون دسترسی داشته باشند، ask: وقتی سایتی می‌خواهد به میکروفون دسترسی داشته باشد، پرسیده شود. پیش‌فرض ask است. نشانی وب اصلی نشانی وب سندی است که دسترسی به میکروفون را درخواست کرده است. از نشانی وب ثانویه استفاده نمی‌شود. توجه: اگر هر دو الگو «<all_urls>» باشد، تنظیم «مجاز» معتبر نیست.

نوع

ContentSetting<MicrophoneContentSetting>

mouselock

منسوخ‌شده. دیگر تأثیری ندارد. اکنون اجازه قفل موشواره به‌طور خودکار برای همه سایت‌ها اعطا می‌شود. مقدار همیشه allow است.

نوع

ContentSetting<MouselockContentSetting>

notifications

آیا به سایت‌ها اجازه داده شود اعلان‌های میز کار را نشان دهند. یکی از allow: به سایت‌ها اجازه داده شود اعلان‌های میز کار را نشان دهند، block: به سایت‌ها اجازه داده نشود اعلان‌های میز کار را نشان دهند، ask: وقتی سایتی می‌خواهد اعلان‌های میز کار را نشان دهد، پرسیده شود. پیش‌فرض ask است. نشانی وب اصلی نشانی وب سندی است که می‌خواهد اعلان را نشان دهد. از نشانی وب ثانویه استفاده نمی‌شود.

نوع

ContentSetting<NotificationsContentSetting>

plugins

منسوخ‌شده. با حذف پشتیبانی از Flash در Chrome 88، این اجازه دیگر تأثیری ندارد. مقدار همیشه block است. تماس‌های set() و clear() نادیده گرفته خواهد شد.

نوع

ContentSetting<PluginsContentSetting>

popups

آیا به سایت‌ها اجازه داده شود بالاپر نشان دهند. یکی از این گزینه‌ها: allow: به سایت‌ها اجازه داده شود بالاپر نشان دهند، block: به سایت‌ها اجازه داده نشود بالاپر نشان دهند. پیش‌فرض block است. نشانی وب اصلی همان نشانی وب قاب سطح بالا است. از نشانی وب ثانویه استفاده نمی‌شود.

نوع

ContentSetting<PopupsContentSetting>

unsandboxedPlugins

منسوخ‌شده. قبلاً کنترل می‌کرد که آیا به سایت‌ها اجازه داده شود افزایه‌ها را بدون جعبه امن اجرا کنند یا نه، اما با برداشته شدن فرایند واسطه Flash در Chrome 88، این اجازه دیگر تأثیری ندارد. مقدار همیشه block است. تماس‌های set() و clear() نادیده گرفته خواهد شد.

نوع

ContentSetting<PpapiBrokerContentSetting>