شرح
از chrome.declarativeContent API برای انجام کنش‌ها براساس محتوای صفحه استفاده کنید، بدون اینکه نیاز به اجازه خواندن محتوای صفحه داشته باشید.
اجازه‌ها
declarativeContentمفاهیم و استفاده
«میانای برنامه کاربردی محتوای بیانیه» به شما امکان می‌دهد کنش افزونه‌تان را بسته به نشانی وب صفحه وب یا درصورتی‌که انتخابگر CSS با عنصری در صفحه مطابقت داشته باشد فعال کنید، بدون اینکه نیاز باشد اجازه‌های میزبان اضافه کنید یا برنامه محتوا تزریق کنید.
از اجازه activeTab برای تعامل با صفحه پس‌از کلیک کاربر روی کنش افزونه استفاده کنید.
قوانین
قوانین شامل شرایط و کنش‌ها است. اگر هریک از شرایط برآورده شود، همه کنش‌ها اجرا می‌شوند. کنش‌ها setIcon() و showAction() هستند.
PageStateMatcher تنها درصورتی با صفحه‌های وب مطابقت می‌کند که همه معیارهای فهرست‌شده برآورده شود. می‌تواند با نشانی وب صفحه، گزینشگر مرکب css
یا وضعیت نشانک‌گذاری‌شده صفحه مطابقت داشته باشد. قانون زیر کنش افزونه را در صفحه‌های Google وقتی فیلد گذرواژه وجود دارد فعال می‌کند:
let rule1 = {
conditions: [
new browser.declarativeContent.PageStateMatcher({
pageUrl: { hostSuffix: '.google.com', schemes: ['https'] },
css: ["input[type='password']"]
})
],
actions: [ new browser.declarativeContent.ShowAction() ]
};
برای فعال کردن کنش افزونه برای سایت‌های Google دارای ویدیو، می‌توانید شرط دومی اضافه کنید، زیرا هر شرط برای راه‌اندازی همه کنش‌های مشخص‌شده کافی است:
let rule2 = {
conditions: [
new browser.declarativeContent.PageStateMatcher({
pageUrl: { hostSuffix: '.google.com', schemes: ['https'] },
css: ["input[type='password']"]
}),
new browser.declarativeContent.PageStateMatcher({
css: ["video"]
})
],
actions: [ new browser.declarativeContent.ShowAction() ]
};
رویداد onPageChanged آزمایش می‌کند که آیا هر قانونی حداقل یک شرط برآورده‌شده دارد یا نه و کنش‌ها را اجرا می‌کند. قوانین در سراسر جلسات مرور باقی می‌مانند؛ بنابراین، درطول
زمان نصب افزونه، ابتدا باید از removeRules برای پاک کردن
قوانین نصب‌شده قبلی استفاده کنید و سپس از addRules برای ثبت قوانین جدید استفاده کنید.
browser.runtime.onInstalled.addListener(function(details) {
browser.declarativeContent.onPageChanged.removeRules(undefined, function() {
browser.declarativeContent.onPageChanged.addRules([rule2]);
});
});
با اجازه activeTab، افزونه شما هیچ هشدار اجازه‌ای نمایش نخواهد داد و وقتی کاربر روی کنش افزونه کلیک می‌کند، فقط در صفحه‌های مرتبط اجرا خواهد شد.
تطبیق نشانی وب صفحه
وقتی معیارهای نشانی وب برآورده شود، PageStateMatcher.pageurl مطابقت پیدا می‌کند. رایج‌ترین معیارها عبارت‌اند از ترکیب میزبان، مسیر، یا نشانی وب، به‌همراه «شامل»، «برابر»، «پیشوند»، یا
«پسوند». جدول زیر شامل چند نمونه است:
| معیارها | موارد منطبق |
|---|---|
{ hostSuffix: 'google.com' } |
همه نشانی‌های وب Google |
{ pathPrefix: '/docs/extensions' } |
نشانی‌های وب اسناد افزونه |
{ urlContains: 'developer.chrome.com' } |
همه نشانی‌های وب اسناد توسعه‌دهندگان Chrome |
همه معیارها حروف‌حساس هستند. برای فهرست کامل معیارها، UrlFilter را ببینید.
تطبیق CSS
PageStateMatcher.css شرط باید انتخابگر مرکب باشد،
یعنی نمی‌توانید ترکیب‌کننده‌هایی مثل فضای خالی یا «>» را در
انتخابگرهایتان بگنجانید. این کار به Chrome کمک می‌کند انتخابگرها را کارآمدتر مطابقت دهد.
| گزینشگرهای مرکب (تأیید) | گزینشگرهای پیچیده (نامناسب) |
|---|---|
a |
div p |
iframe.special[src^='http'] |
p>span.highlight |
ns|* |
p + ol |
#abcd:checked |
p::first-line |
شرایط CSS فقط با عناصر نمایش‌داده‌شده مطابقت دارد: اگر عنصری که با گزینشگر شما مطابقت دارد display:none باشد یا یکی از عناصر والد آن display:none باشد، باعث نمی‌شود شرط مطابقت کند. عناصری که با visibility:hidden سبک‌بندی شده‌اند، در خارج از صفحه قرار گرفته‌اند، یا توسط عناصر دیگر پنهان شده‌اند
همچنان می‌توانند باعث شوند وضعیت شما مطابقت پیدا کند.
تطبیق وضعیت نشانک‌گذاری‌شده
شرط PageStateMatcher.isBookmarked امکان مطابقت وضعیت نشانک‌گذاری نشانی وب فعلی در نمایه کاربر را فراهم می‌کند. برای استفاده از این شرط، اجازه «نشانک‌ها» باید در مانیفست افزونه اعلام شود.
انواع
ImageDataType
https://developer.mozilla.org/en-US/docs/Web/API/ImageData را ببینید.
نوع
ImageData
PageStateMatcher
وضعیت صفحه وب را براساس معیارهای مختلف مطابقت می‌دهد.
مشخصات
-
سازنده
باطل
تابع
constructorبه‌صورت زیر است:(arg: PageStateMatcher) => {...}
-
arg
-
returns
-
-
css
رشته[] اختیاری
اگر همه انتخابگرهای CSS در آرایه با عناصر نمایش‌داده‌شده در چارچوبی با مبدأ یکسان با چارچوب اصلی صفحه مطابقت داشته باشند، مطابقت پیدا می‌کند. همه انتخابگرهای این آرایه باید انتخابگرهای مرکب باشند تا سرعت مطابقت افزایش یابد. توجه: فهرست کردن صدها گزینشگر CSS یا فهرست کردن گزینشگرهای CSS که صدها بار در صفحه مطابقت دارند می‌تواند سرعت وب‌سایت‌ها را کاهش دهد.
-
isBookmarked
مقدار منطقی اختیاری
Chrome نسخه ۴۵ و بالاتراگر وضعیت نشانک‌گذاری صفحه با مقدار مشخص‌شده برابر باشد، مطابقت دارد. به اجازه نشانک‌ها نیاز دارد.
-
pageUrl
UrlFilter اختیاری
اگر شرایط
UrlFilterبرای نشانی وب سطح بالای صفحه برآورده شود، مطابقت پیدا می‌کند.
RequestContentScript
کنش رویداد بیانی که یک متن محتوا را تزریق می‌کند.
هشدار: این کنش هنوز آزمایشی است و در ساخت‌های پایدار Chrome پشتیبانی نمی‌شود.
مشخصات
-
سازنده
باطل
تابع
constructorبه‌صورت زیر است:(arg: RequestContentScript) => {...}
-
returns
-
-
allFrames
مقدار منطقی اختیاری
آیا متن محتوا در همه قاب‌های صفحه منطبق اجرا می‌شود یا فقط در قاب بالا. پیش‌فرض
falseاست. -
css
رشته[] اختیاری
نام فایل‌های CSS که باید به‌عنوان بخشی از دستورگان محتوا تزریق شوند.
-
js
رشته[] اختیاری
نام فایل‌های جاوا اسکریپت که به‌عنوان بخشی از دستورگان محتوا تزریق می‌شوند.
-
matchAboutBlank
مقدار منطقی اختیاری
آیا دستورگان محتوا در
about:blankوabout:srcdocدرج شود یا نه. پیش‌فرضfalseاست.
SetIcon
کنش رویداد بیانی که نماد مربعی n-dip را برای کنش صفحه یا کنش مرورگر افزونه تنظیم می‌کند، درحالی‌که شرایط مربوطه برآورده می‌شود. این کنش را می‌توان بدون اجازه‌های میزبان استفاده کرد، اما افزونه باید کنش صفحه یا مرورگر داشته باشد.
دقیقاً یکی از imageData یا path باید مشخص شود. هر دو فرهنگ لغت‌هایی هستند که تعدادی پیکسل را به یک نمایش تصویری نگاشت می‌کنند. نمایش تصویر در imageData یک شیء ImageData است؛ برای مثال، از عنصر canvas، درحالی‌که نمایش تصویر در path مسیر فایل تصویر نسبت‌به مانیفست افزونه است. اگر scale پیکسل صفحه‌نمایش در یک پیکسل مستقل از دستگاه جا شود، از نماد scale * n استفاده می‌شود. اگر آن مقیاس وجود نداشته باشد، تصویر دیگری به اندازه موردنیاز تغییر اندازه داده می‌شود.
مشخصات
-
سازنده
باطل
تابع
constructorبه‌صورت زیر است:(arg: SetIcon) => {...}
-
arg
-
returns
-
-
imageData
ImageData | object اختیاری
یا شیء
ImageDataیا فرهنگ لغت {اندازه -> ImageData} که نشان‌دهنده نمادی است که باید تنظیم شود. اگر نماد به‌عنوان فرهنگ لغت مشخص شده باشد، تصویر استفاده‌شده بسته به تراکم پیکسل صفحه انتخاب می‌شود. اگر تعداد پیکسل‌های تصویری که در یک واحد فضای صفحه جا می‌شود برابر باscaleباشد، تصویری با اندازهscale * nانتخاب می‌شود، که در آن n اندازه نماد در رابط کاربری است. حداقل یک تصویر باید مشخص شود. توجه داشته باشید کهdetails.imageData = fooمعادلdetails.imageData = {'16': foo}است.
ShowAction
کنش رویداد بیانی که نوارابزار کنش افزونه را درحالی‌که شرایط مربوطه برآورده می‌شود روی حالت فعال تنظیم می‌کند. این کنش را می‌توان بدون اجازه‌های میزبان استفاده کرد. اگر افزونه اجازه activeTab را داشته باشد، کلیک کردن روی کنش صفحه دسترسی به زبانه فعال را اعطا می‌کند.
در صفحاتی که شرایط برآورده نمی‌شود، کنش نوارابزار افزونه خاکستری خواهد بود و با کلیک کردن روی آن، منو زمینه‌ای باز می‌شود و کنش راه‌اندازی نمی‌شود.
مشخصات
-
سازنده
باطل
تابع
constructorبه‌صورت زیر است:(arg: ShowAction) => {...}
-
arg
-
returns
-
ShowPageAction
لطفاً از declarativeContent.ShowAction استفاده کنید.
کنش رویداد بیانی که کنش صفحه افزونه را درحالی‌که شرایط مربوطه برآورده می‌شود روی حالت فعال تنظیم می‌کند. این کنش را می‌توان بدون اجازه‌های میزبان استفاده کرد، اما افزونه باید کنش صفحه داشته باشد. اگر افزونه اجازه activeTab را داشته باشد، کلیک کردن روی کنش صفحه دسترسی به زبانه فعال را اعطا می‌کند.
در صفحاتی که شرایط برآورده نمی‌شود، کنش نوارابزار افزونه خاکستری خواهد بود و با کلیک کردن روی آن، منو زمینه‌ای باز می‌شود و کنش راه‌اندازی نمی‌شود.
مشخصات
-
سازنده
باطل
تابع
constructorبه‌صورت زیر است:(arg: ShowPageAction) => {...}
-
arg
-
returns
-
رویدادها
onPageChanged
Declarative Event API را که شامل addRules، removeRules، و getRules است ارائه می‌دهد.