chrome.contentSettings

شرح

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

مجوزها

contentSettings

برای استفاده از API باید مجوز "contentSettings" را در مانیفست برنامه افزودنی خود اعلام کنید. مثلا:

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

مفاهیم و کاربرد

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

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

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

تقدم الگو

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

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

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

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

  • حروف عام در پورت (به عنوان مثال 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 بر اساس URL نشان داده شده در omnibox است. این URL URL "اصلی" نامیده می شود.

برخی از انواع محتوا می توانند URL های اضافی را در نظر بگیرند. برای مثال، اینکه آیا یک سایت مجاز به تنظیم یک contentSettings.cookies است یا خیر، بر اساس URL درخواست HTTP (که در این مورد URL اصلی است) و همچنین URL نشان داده شده در omnibox (که "ثانویه" نامیده می شود، تصمیم گیری می شود. " 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 سعی می‌کند شناسه‌ها را در بین به‌روزرسانی‌های افزونه ثابت نگه دارد.

مثال ها

برای امتحان این API، نمونه ContentSettings API را از مخزن chrome-extension-samples نصب کنید.

انواع

AutoVerifyContentSetting

Chrome 113+

Enum

"اجازه"

"مسدود کردن"

CameraContentSetting

Chrome 46+

Enum

"اجازه"

"مسدود کردن"

"پرسیدن"

ClipboardContentSetting

Chrome 121+

Enum

"اجازه"

"مسدود کردن"

"پرسیدن"

ContentSetting

خواص

  • روشن

    خالی

    وعده

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

    تابع clear به نظر می رسد: 

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

    • جزئیات

      هدف - شی

      • محدوده

        دامنه اختیاری است

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

    • پاسخ به تماس

      عملکرد اختیاری

      پارامتر callback به نظر می رسد: 

      ()=>void

    • برمی گرداند

      قول<باطل>

      Chrome 96+

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

  • گرفتن

    خالی

    وعده

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

    تابع get به نظر می رسد: 

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

    • جزئیات

      هدف - شی

      • ناشناس

        بولی اختیاری

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

      • PrimaryUrl

        رشته

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

      • شناسه منبع

        ResourceIdentifier اختیاری است

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

      • secondaryUrl

        رشته اختیاری

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

    • پاسخ به تماس

      عملکرد اختیاری

      پارامتر callback به نظر می رسد: 

      (details: object)=>void

      • جزئیات

        هدف - شی

        • تنظیمات

          تی

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

    • برمی گرداند

      قول<object>

      Chrome 96+

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

  • getResourceIdentifiers

    خالی

    وعده

    تابع getResourceIdentifiers به ​​نظر می رسد: 

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

    • پاسخ به تماس

      عملکرد اختیاری

      پارامتر callback به نظر می رسد: 

      (resourceIdentifiers?: ResourceIdentifier[])=>void

      • شناسه های منبع

        ResourceIdentifier [] اختیاری است

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

    • برمی گرداند

      Promise< ResourceIdentifier []>

      Chrome 96+

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

  • تنظیم

    خالی

    وعده

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

    تابع set به نظر می رسد: 

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

    • جزئیات

      هدف - شی

      • الگوی اولیه

        رشته

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

      • شناسه منبع

        ResourceIdentifier اختیاری است

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

      • محدوده

        دامنه اختیاری است

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

      • الگوی ثانویه

        رشته اختیاری

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

      • تنظیمات

        هر

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

    • پاسخ به تماس

      عملکرد اختیاری

      پارامتر callback به نظر می رسد: 

      ()=>void

    • برمی گرداند

      قول<باطل>

      Chrome 96+

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

CookiesContentSetting

Chrome 44+

Enum

"اجازه"

"مسدود کردن"

"sesion_only"

FullscreenContentSetting

Chrome 44+

ارزش

"اجازه"

ImagesContentSetting

Chrome 44+

Enum

"اجازه"

"مسدود کردن"

JavascriptContentSetting

Chrome 44+

Enum

"اجازه"

"مسدود کردن"

LocationContentSetting

Chrome 44+

Enum

"اجازه"

"مسدود کردن"

"پرسیدن"

MicrophoneContentSetting

Chrome 46+

Enum

"اجازه"

"مسدود کردن"

"پرسیدن"

MouselockContentSetting

Chrome 44+

ارزش

"اجازه"

MultipleAutomaticDownloadsContentSetting

Chrome 44+

Enum

"اجازه"

"مسدود کردن"

"پرسیدن"

NotificationsContentSetting

Chrome 44+

Enum

"اجازه"

"مسدود کردن"

"پرسیدن"

PluginsContentSetting

Chrome 44+

ارزش

"مسدود کردن"

PopupsContentSetting

Chrome 44+

Enum

"اجازه"

"مسدود کردن"

PpapiBrokerContentSetting

Chrome 44+

ارزش

"مسدود کردن"

ResourceIdentifier

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

خواص

  • شرح

    رشته اختیاری

    توصیف قابل خواندن توسط انسان از منبع.

  • شناسه

    رشته

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

Scope

Chrome 44+

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

Enum

"منظم"

"oncognito_session_only"

خواص

automaticDownloads

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

تایپ کنید

ContentSetting < MultipleAutomaticDownloadsContentSetting >

autoVerify

Chrome 113+

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

تایپ کنید

ContentSetting < AutoVerifyContentSetting >

camera

Chrome 46+

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

تایپ کنید

ContentSetting < CameraContentSetting >

clipboard

Chrome 121+

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

تایپ کنید

ContentSetting < ClipboardContentSetting >

cookies

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

تایپ کنید

ContentSetting < CookiesContentSetting >

fullscreen

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

تایپ کنید

ContentSetting < FullscreenContentSetting >

images

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

تایپ کنید

ContentSetting < ImagesContentSetting >

javascript

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

تایپ کنید

ContentSetting < JavascriptContentSetting >

location

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

تایپ کنید

ContentSetting < LocationContentSetting >

microphone

Chrome 46+

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

تایپ کنید

ContentSetting < MicrophoneContentSetting >

mouselock

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

تایپ کنید

ContentSetting < MouselockContentSetting >

notifications

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

تایپ کنید

ContentSetting < NotificationsContentSetting >

plugins

منسوخ. با حذف پشتیبانی فلش در کروم 88، ​​این مجوز دیگر اثری ندارد. ارزش همیشه block است. فراخوان های set() و clear() نادیده گرفته می شوند.

تایپ کنید

ContentSetting < PluginsContentSetting >

popups

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

تایپ کنید

ContentSetting < PopupsContentSetting >

unsandboxedPlugins

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

تایپ کنید

ContentSetting < PpapiBrokerContentSetting >