توضیحات
از API chrome.contentSettings برای تغییر تنظیماتی که کنترل می‌کنند آیا وب‌سایت‌ها می‌توانند از ویژگی‌هایی مانند کوکی‌ها، جاوا اسکریپت و افزونه‌ها استفاده کنند یا خیر، استفاده کنید. به طور کلی، تنظیمات محتوا به شما امکان می‌دهد رفتار کروم را به جای سراسری، بر اساس هر سایت سفارشی کنید.
مجوزها
contentSettingsمانیفست
برای استفاده از API، باید مجوز "contentSettings" را در فایل مانیفست افزونه خود اعلام کنید. برای مثال:
{
"name": "My extension",
...
"permissions": [
"contentSettings"
],
...
}
الگوهای تنظیم محتوا
شما می‌توانید از الگوها برای مشخص کردن وب‌سایت‌هایی که هر تنظیم محتوا روی آنها تأثیر می‌گذارد استفاده کنید. برای مثال، https://*.youtube.com/* youtube.com و تمام زیردامنه‌های آن را مشخص می‌کند. نحو الگوهای تنظیم محتوا مشابه الگوهای تطبیق است، با چند تفاوت:
- برای آدرس‌های اینترنتی
http،httpsوftp، مسیر باید یک کاراکتر عمومی (/*) باشد. برای آدرس‌های اینترنتیfile، مسیر باید کاملاً مشخص شده و نباید حاوی کاراکترهای عمومی باشد. - برخلاف الگوهای تطبیق، الگوهای تنظیم محتوا می‌توانند یک شماره پورت را مشخص کنند. اگر شماره پورت مشخص شود، الگو فقط وب‌سایت‌هایی را که دارای آن پورت هستند مطابقت می‌دهد. اگر هیچ شماره پورتی مشخص نشود، الگو با همه پورت‌ها مطابقت دارد.
اولویت الگو
وقتی بیش از یک قانون تنظیم محتوا برای یک سایت مشخص اعمال می‌شود، قانونی که الگوی خاص‌تری دارد، اولویت دارد.
برای مثال، الگوهای زیر بر اساس اولویت مرتب شده‌اند:
-
https://www.example.com/* -
https://*.example.com/*(مطابق با example.com و همه زیر دامنه‌ها) -
<all_urls>(مطابق با هر URL)
سه نوع علامت اختصاری بر میزان خاص بودن یک الگو تأثیر می‌گذارند:
- کاراکترهای جایگزین (wildcards) در پورت (برای مثال
https://www.example.com:*/*) - کاراکترهای جایگزین (Wildcards) در این طرح (برای مثال
*://www.example.com:123/*) - کاراکترهای جایگزین (Wildcards) در نام میزبان (برای مثال
https://*.example.com:123/*)
اگر الگویی در یک بخش نسبت به الگوی دیگر خاص‌تر باشد اما در بخش دیگر خاص‌تر باشد، بخش‌های مختلف به ترتیب زیر بررسی می‌شوند: نام میزبان، طرح، پورت. به عنوان مثال، الگوهای زیر بر اساس اولویت مرتب شده‌اند:
-
https://www.example.com:*/*نام میزبان و طرحواره را مشخص می‌کند. -
*:/www.example.com:123/*نه به آن اندازه بالا، زیرا اگرچه نام میزبان را مشخص می‌کند، اما طرحواره را مشخص نمی‌کند. -
https://*.example.com:123/*پایین‌تر است زیرا اگرچه پورت و طرح را مشخص می‌کند، اما در نام میزبان یک wildcard دارد.
الگوهای اولیه و ثانویه
URL که هنگام تصمیم‌گیری در مورد اعمال تنظیمات محتوا در نظر گرفته می‌شود، به نوع محتوا بستگی دارد. به عنوان مثال، برای contentSettings.notifications تنظیمات بر اساس URL نشان داده شده در omnibox است. این URL، URL "اصلی" نامیده می‌شود.
برخی از انواع محتوا می‌توانند URLهای اضافی را در نظر بگیرند. برای مثال، اینکه آیا یک سایت مجاز به تنظیم contentSettings.cookies است یا خیر، بر اساس URL درخواست HTTP (که در این مورد URL اصلی است) و همچنین URL نشان داده شده در omnibox (که URL "ثانویه" نامیده می‌شود) تعیین می‌شود.
اگر چندین قانون دارای الگوهای اولیه و ثانویه باشند، قانونی که الگوی اولیه خاص‌تری دارد، اولویت دارد. اگر چندین قانون دارای الگوی اولیه یکسانی باشند، قانونی که الگوی ثانویه خاص‌تری دارد، اولویت دارد. برای مثال، لیست زیر از جفت الگوهای اولیه/ثانویه بر اساس اولویت مرتب شده است:
| حق تقدم | الگوی اولیه | الگوی ثانویه |
|---|---|---|
| ۱ | https://www.moose.com/* ، | https://www.wombat.com/* |
| ۲ | https://www.moose.com/* ، | <all_urls> |
| ۳ | <all_urls> ، | https://www.wombat.com/* |
| ۴ | <all_urls> ، | <all_urls> |
شناسه‌های منابع
شناسه‌های منبع به شما امکان می‌دهند تنظیمات محتوا را برای زیرگروه‌های خاص یک نوع محتوا مشخص کنید. در حال حاضر، تنها نوع محتوایی که از شناسه‌های منبع پشتیبانی می‌کند contentSettings.plugins است، که در آن شناسه منبع، یک افزونه خاص را شناسایی می‌کند. هنگام اعمال تنظیمات محتوا، ابتدا تنظیمات مربوط به افزونه خاص بررسی می‌شوند. اگر هیچ تنظیماتی برای افزونه خاص یافت نشد، تنظیمات عمومی محتوا برای افزونه‌ها بررسی می‌شوند.
برای مثال، اگر یک قانون تنظیم محتوا دارای شناسه منبع adobe-flash-player و الگوی <all_urls> باشد، نسبت به قانونی که شناسه منبع و الگوی https://www.example.com/* ندارد، اولویت دارد، حتی اگر آن الگو خاص‌تر باشد.
شما می‌توانید با فراخوانی متد contentSettings.ContentSetting.getResourceIdentifiers فهرستی از شناسه‌های منابع را برای یک نوع محتوا دریافت کنید. فهرست برگردانده شده می‌تواند با مجموعه افزونه‌های نصب شده روی دستگاه کاربر تغییر کند، اما کروم تلاش می‌کند شناسه‌ها را در به‌روزرسانی‌های افزونه ثابت نگه دارد.
مثال‌ها
برای امتحان کردن این API، نمونه‌ی contentSettings API را از مخزن chrome-extension-samples نصب کنید.
انواع
AutoVerifyContentSetting
شمارشی
«اجازه دادن» "بلوک"
CameraContentSetting
شمارشی
«اجازه دادن» "بلوک" «پرسیدن»
ClipboardContentSetting
شمارشی
«اجازه دادن» "بلوک" «پرسیدن»
ContentSetting
خواص
- واضح
باطل
وعدهتمام قوانین تنظیم محتوای تعیین‌شده توسط این افزونه را پاک کنید.
تابع
clearبه شکل زیر است:(details: object, callback?: function) => {...}
- جزئیات
شیء
- محدوده
محدوده اختیاری
کجا می‌توان تنظیمات را پاک کرد (پیش‌فرض: معمولی).
- تماس برگشتی
تابع اختیاری
پارامتر
callbackبه شکل زیر است:() => void
- بازده
قول<void>
کروم ۹۶+Promiseها فقط برای Manifest V3 و نسخه‌های بعدی پشتیبانی می‌شوند، سایر پلتفرم‌ها باید از callbackها استفاده کنند.
- دریافت
باطل
وعدهتنظیمات محتوای فعلی را برای یک جفت URL مشخص دریافت می‌کند.
تابع
getبه شکل زیر است:(details: object, callback?: function) => {...}
- جزئیات
شیء
- ناشناس
بولی اختیاری
اینکه آیا تنظیمات محتوا برای یک جلسه ناشناس بررسی شود یا خیر. (پیش‌فرض نادرست)
- آدرس اصلی
رشته
URL اصلی که تنظیمات محتوا باید برای آن بازیابی شود. توجه داشته باشید که معنی URL اصلی به نوع محتوا بستگی دارد.
- شناسه منبع
شناسه منبع اختیاری است
شناسه‌ای دقیق‌تر از نوع محتوایی که تنظیمات باید برای آن بازیابی شوند.
- آدرس ثانویه
رشته اختیاری
URL ثانویه‌ای که تنظیمات محتوا باید برای آن بازیابی شود. پیش‌فرض روی URL اصلی است. توجه داشته باشید که معنای URL ثانویه به نوع محتوا بستگی دارد و همه انواع محتوا از URLهای ثانویه استفاده نمی‌کنند.
- تماس برگشتی
تابع اختیاری
پارامتر
callbackبه شکل زیر است:(details: object) => void
- جزئیات
شیء
- تنظیم
تی
تنظیمات محتوا. برای مقادیر ممکن، به توضیحات مربوط به اشیاء ContentSetting مراجعه کنید.
- بازده
قول دادن<object>
کروم ۹۶+Promiseها فقط برای Manifest V3 و نسخه‌های بعدی پشتیبانی می‌شوند، سایر پلتفرم‌ها باید از callbackها استفاده کنند.
- شناسه‌های منبع
باطل
وعدهتابع
getResourceIdentifiersبه شکل زیر است:(callback?: function) => {...}
- تماس برگشتی
تابع اختیاری
پارامتر
callbackبه شکل زیر است:(resourceIdentifiers?: ResourceIdentifier[]) => void
- شناسه‌های منابع
شناسه منبع [] اختیاری
فهرستی از شناسه‌های منبع برای این نوع محتوا، یا اگر این نوع محتوا از شناسه‌های منبع استفاده نمی‌کند،
undefined.
- بازده
قول < شناسه منبع []>
کروم ۹۶+Promiseها فقط برای Manifest V3 و نسخه‌های بعدی پشتیبانی می‌شوند، سایر پلتفرم‌ها باید از callbackها استفاده کنند.
- مجموعه
باطل
وعدهیک قانون تنظیم محتوای جدید اعمال می‌کند.
تابع
setبه شکل زیر است:(details: object, callback?: function) => {...}
- جزئیات
شیء
- الگوی اولیه
رشته
الگوی مربوط به URL اصلی. برای جزئیات بیشتر در مورد قالب یک الگو، به الگوهای تنظیم محتوا مراجعه کنید.
- شناسه منبع
شناسه منبع اختیاری است
شناسه منبع برای نوع محتوا.
- محدوده
محدوده اختیاری
محل تنظیم تنظیمات (پیش‌فرض: معمولی).
- الگوی ثانویه
رشته اختیاری
الگویی برای URL ثانویه. پیش‌فرض برای تطبیق با همه URLها. برای جزئیات بیشتر در مورد قالب یک الگو، به الگوهای تنظیم محتوا مراجعه کنید.
- تنظیم
هر
تنظیمات اعمال شده توسط این قانون. برای مقادیر ممکن، به توضیحات مربوط به اشیاء ContentSetting مراجعه کنید.
- تماس برگشتی
تابع اختیاری
پارامتر
callbackبه شکل زیر است:() => void
- بازده
قول<void>
کروم ۹۶+Promiseها فقط برای Manifest V3 و نسخه‌های بعدی پشتیبانی می‌شوند، سایر پلتفرم‌ها باید از callbackها استفاده کنند.
CookiesContentSetting
شمارشی
«اجازه دادن» "بلوک" "فقط جلسه"
FullscreenContentSetting
ارزش
«اجازه دادن»
ImagesContentSetting
شمارشی
«اجازه دادن» "بلوک"
JavascriptContentSetting
شمارشی
«اجازه دادن» "بلوک"
LocationContentSetting
شمارشی
«اجازه دادن» "بلوک" «پرسیدن»
MicrophoneContentSetting
شمارشی
«اجازه دادن» "بلوک" «پرسیدن»
MouselockContentSetting
ارزش
«اجازه دادن»
MultipleAutomaticDownloadsContentSetting
شمارشی
«اجازه دادن» "بلوک" «پرسیدن»
NotificationsContentSetting
شمارشی
«اجازه دادن» "بلوک" «پرسیدن»
PluginsContentSetting
ارزش
"بلوک"
PopupsContentSetting
شمارشی
«اجازه دادن» "بلوک"
PpapiBrokerContentSetting
ارزش
"بلوک"
ResourceIdentifier
تنها نوع محتوایی که از شناسه‌های منبع استفاده می‌کند contentSettings.plugins است. برای اطلاعات بیشتر، به شناسه‌های منبع مراجعه کنید.
خواص
- توضیحات
رشته اختیاری
توصیفی خوانا برای انسان از منبع.
- شناسه
رشته
شناسه منبع برای نوع محتوای داده شده.
Scope
دامنه‌ی ContentSetting. یکی از موارد regular : تنظیم برای پروفایل معمولی (که اگر در جای دیگری لغو نشود، توسط پروفایل ناشناس به ارث می‌رسد)، incognito\_session\_only : تنظیم برای پروفایل ناشناس که فقط می‌تواند در طول یک جلسه ناشناس تنظیم شود و با پایان جلسه ناشناس حذف می‌شود (تنظیمات معمولی را لغو می‌کند).
شمارشی
"منظم" "فقط جلسه ناشناس"
SoundContentSetting
شمارشی
«اجازه دادن» "بلوک"
خواص
automaticDownloads
اینکه آیا به سایت‌ها اجازه دانلود خودکار چندین فایل داده شود یا خیر. یکی از allow : به سایت‌ها اجازه دانلود خودکار چندین فایل داده شود، block : به سایت‌ها اجازه دانلود خودکار چندین فایل داده نشود، ask : وقتی سایتی می‌خواهد فایل‌ها را پس از اولین فایل به‌طور خودکار دانلود کند، این گزینه پرسیده شود. پیش‌فرض ask است. URL اصلی، URL فریم سطح بالا است. URL ثانویه استفاده نمی‌شود.
autoVerify
اینکه آیا به سایت‌ها اجازه استفاده از API توکن‌های حالت خصوصی داده شود یا خیر. یکی از دو حالت allow : اجازه استفاده از API توکن‌های حالت خصوصی توسط سایت‌ها، block : جلوگیری از استفاده سایت‌ها از API توکن‌های حالت خصوصی. مقدار پیش‌فرض allow است. هنگام فراخوانی set() ، الگوی URL اصلی باید <all_urls> باشد. URL ثانویه استفاده نمی‌شود.
camera
اینکه آیا به سایت‌ها اجازه دسترسی به دوربین داده شود یا خیر. یکی از موارد allow : اجازه دسترسی به سایت‌ها به دوربین، block : اجازه دسترسی به سایت‌ها به دوربین، ask : درخواست دسترسی به دوربین. پیش‌فرض ask است. URL اصلی، URL سندی است که درخواست دسترسی به دوربین را داده است. URL ثانویه استفاده نمی‌شود. توجه: اگر هر دو الگو '<all_urls>' باشند، تنظیم 'allow' معتبر نیست.
نوع
clipboard
اینکه آیا به سایت‌ها اجازه دسترسی به کلیپ‌بورد از طریق قابلیت‌های پیشرفته‌ی Async Clipboard API داده شود یا خیر. قابلیت‌های «پیشرفته» شامل هر چیزی علاوه بر نوشتن فرمت‌های داخلی پس از اشاره‌ی کاربر می‌شود، یعنی قابلیت خواندن، قابلیت نوشتن فرمت‌های سفارشی و قابلیت نوشتن بدون اشاره‌ی کاربر. یکی از این موارد allow : به سایت‌ها اجازه دهید از قابلیت‌های پیشرفته‌ی کلیپ‌بورد استفاده کنند، block : به سایت‌ها اجازه ندهید از قابلیت‌های پیشرفته‌ی کلیپ‌بورد استفاده کنند، ask است: وقتی سایتی می‌خواهد از قابلیت‌های پیشرفته‌ی کلیپ‌بورد استفاده کند، ask . پیش‌فرض ask است. URL اصلی، URL سندی است که درخواست دسترسی به کلیپ‌بورد را داده است. URL ثانویه استفاده نمی‌شود.
cookies
اینکه آیا اجازه داده شود کوکی‌ها و سایر داده‌های محلی توسط وب‌سایت‌ها تنظیم شوند یا خیر. یکی از موارد allow : پذیرش کوکی‌ها، block : مسدود کردن کوکی‌ها، session\_only : پذیرش کوکی‌ها فقط برای جلسه فعلی. پیش‌فرض allow است. URL اصلی، URLای است که نشان‌دهنده منشأ کوکی است. URL ثانویه، URL فریم سطح بالا است.
نوع
fullscreen
منسوخ شده. دیگر هیچ تاثیری ندارد. اکنون مجوز تمام صفحه به طور خودکار برای همه سایت‌ها اعطا می‌شود. مقدار آن همیشه allow است.
نوع
images
اینکه آیا تصاویر نمایش داده شوند یا خیر. یکی از دو حالت allow : نمایش تصاویر، block : عدم نمایش تصاویر. حالت پیش‌فرض allow است. آدرس اینترنتی اصلی، آدرس اینترنتی فریم سطح بالا است. آدرس اینترنتی ثانویه، آدرس اینترنتی تصویر است.
نوع
javascript
اینکه آیا جاوا اسکریپت اجرا شود یا خیر. یکی از دو حالت allow : اجرای جاوا اسکریپت، block : عدم اجرای جاوا اسکریپت. حالت پیش‌فرض allow است. URL اصلی، URL فریم سطح بالا است. URL ثانویه استفاده نمی‌شود.
location
اینکه آیا موقعیت جغرافیایی مجاز باشد یا خیر. یکی از موارد allow : به سایت‌ها اجازه دهید موقعیت مکانی فیزیکی شما را ردیابی کنند، block : به سایت‌ها اجازه ندهید موقعیت مکانی فیزیکی شما را ردیابی کنند، ask : قبل از اجازه دادن به سایت‌ها برای ردیابی موقعیت مکانی فیزیکی شما، ask کنید. پیش‌فرض ask است. URL اصلی، URL سندی است که داده‌های موقعیت مکانی را درخواست کرده است. URL ثانویه، URL فریم سطح بالا است (که ممکن است با URL درخواست‌کننده متفاوت باشد یا نباشد).
نوع
microphone
اینکه آیا به سایت‌ها اجازه دسترسی به میکروفون داده شود یا خیر. یکی از موارد allow : اجازه دسترسی سایت‌ها به میکروفون، block : اجازه دسترسی سایت‌ها به میکروفون، ask : درخواست دسترسی سایت‌ها به میکروفون. پیش‌فرض ask است. URL اصلی، URL سندی است که درخواست دسترسی به میکروفون را داده است. URL ثانویه استفاده نمی‌شود. توجه: اگر هر دو الگو '<all_urls>' باشند، تنظیم 'allow' معتبر نیست.
نوع
mouselock
منسوخ شده. دیگر هیچ تاثیری ندارد. اجازه قفل ماوس اکنون به طور خودکار برای همه سایت‌ها اعطا می‌شود. مقدار آن همیشه allow است.
notifications
اینکه آیا به سایت‌ها اجازه نمایش اعلان‌های دسکتاپ داده شود یا خیر. یکی از allow : به سایت‌ها اجازه نمایش اعلان‌های دسکتاپ داده شود، block : به سایت‌ها اجازه نمایش اعلان‌های دسکتاپ داده نشود، ask : وقتی سایتی می‌خواهد اعلان‌های دسکتاپ را نشان دهد، پرسیده شود. پیش‌فرض ask است. URL اصلی، URL سندی است که می‌خواهد اعلان را نشان دهد. URL ثانویه استفاده نمی‌شود.
نوع
plugins
منسوخ شده. با حذف پشتیبانی از فلش در کروم ۸۸، این مجوز دیگر هیچ تاثیری ندارد. مقدار آن همیشه block است. فراخوانی‌های set() و clear() نادیده گرفته می‌شوند.
popups
اینکه آیا به سایت‌ها اجازه نمایش پاپ‌آپ داده شود یا خیر. یکی از دو allow : اجازه نمایش پاپ‌آپ به سایت‌ها، block : اجازه نمایش پاپ‌آپ به سایت‌ها داده نشود. حالت پیش‌فرض block است. آدرس اینترنتی اصلی، آدرس اینترنتی فریم سطح بالا است. آدرس اینترنتی ثانویه استفاده نمی‌شود.
unsandboxedPlugins
منسوخ شده. پیش از این، کنترل می‌شد که آیا به سایت‌ها اجازه داده شود افزونه‌ها را بدون سندباکس اجرا کنند یا خیر، با این حال، با حذف فرآیند واسطه فلش در کروم ۸۸، این مجوز دیگر هیچ تاثیری ندارد. مقدار همیشه block است. فراخوانی‌های set() و clear() نادیده گرفته می‌شوند.