chrome.declarativeContent

شرح

از chrome.declarativeContent API برای انجام اقداماتی بسته به محتوای یک صفحه، بدون نیاز به مجوز برای خواندن محتوای صفحه استفاده کنید.

مجوزها

declarativeContent

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

Declarative Content API به شما این امکان را می دهد که عملکرد برنامه افزودنی خود را بسته به URL یک صفحه وب، یا اگر انتخابگر CSS با عنصری در صفحه مطابقت دارد، بدون نیاز به اضافه کردن مجوزهای میزبان یا تزریق اسکریپت محتوا ، فعال کنید.

پس از کلیک کاربر بر روی عملکرد برنامه افزودنی، از مجوز activeTab برای تعامل با یک صفحه استفاده کنید.

قوانین

قوانین شامل شرایط و اقدامات است. در صورت تحقق هر یک از شرایط، تمام اقدامات اجرا می شوند. اکشن ها setIcon() و showAction() هستند.

PageStateMatcher با صفحات وب منطبق است اگر و فقط در صورتی که تمام معیارهای فهرست شده برآورده شوند. می‌تواند با یک url صفحه ، یک انتخابگر ترکیبی css یا حالت نشانه‌گذاری شده یک صفحه مطابقت داشته باشد. قانون زیر در صورت وجود فیلد رمز عبور، عملکرد برنامه افزودنی را در صفحات Google فعال می کند:

let rule1 = {
  conditions: [
    new chrome.declarativeContent.PageStateMatcher({
      pageUrl: { hostSuffix: '.google.com', schemes: ['https'] },
      css: ["input[type='password']"]
    })
  ],
  actions: [ new chrome.declarativeContent.ShowAction() ]
};

برای فعال کردن عملکرد برنامه افزودنی برای سایت‌های Google با یک ویدیو، می‌توانید شرط دوم را اضافه کنید، زیرا هر شرط برای فعال کردن تمام اقدامات مشخص شده کافی است:

let rule2 = {
  conditions: [
    new chrome.declarativeContent.PageStateMatcher({
      pageUrl: { hostSuffix: '.google.com', schemes: ['https'] },
      css: ["input[type='password']"]
    }),
    new chrome.declarativeContent.PageStateMatcher({
      css: ["video"]
    })
  ],
  actions: [ new chrome.declarativeContent.ShowAction() ]
};

رویداد onPageChanged آزمایش می کند که آیا یک قانون حداقل یک شرط انجام شده دارد یا خیر و اقدامات را اجرا می کند. قوانین در سراسر جلسات مرور وجود دارند. بنابراین، در طول زمان نصب برنامه افزودنی، ابتدا باید از removeRules برای پاک کردن قوانین نصب شده قبلی استفاده کنید و سپس از addRules برای ثبت قوانین جدید استفاده کنید.

chrome.runtime.onInstalled.addListener(function(details) {
  chrome.declarativeContent.onPageChanged.removeRules(undefined, function() {
    chrome.declarativeContent.onPageChanged.addRules([rule2]);
  });
});

با مجوز activeTab ، برنامه افزودنی شما هیچ اخطار مجوزی را نشان نمی‌دهد و وقتی کاربر روی عملکرد برنامه افزودنی کلیک می‌کند، فقط در صفحات مربوطه اجرا می‌شود.

مطابقت URL صفحه

PageStateMatcher.pageurl زمانی مطابقت دارد که معیارهای URL برآورده شوند. متداول‌ترین معیارها ترکیب میزبان، مسیر یا URL است و به دنبال آن Contains، Equals، Prefix یا Suffix قرار می‌گیرد. جدول زیر شامل چند نمونه است:

شاخص مسابقات
{ hostSuffix: 'google.com' } همه URL های گوگل
{ pathPrefix: '/docs/extensions' } URL اسناد برنامه افزودنی
{ urlContains: 'developer.chrome.com' } همه توسعه‌دهندگان کروم نشانی‌های وب را اسناد می‌کنند

همه معیارها به حروف کوچک و بزرگ حساس هستند. برای فهرست کامل معیارها، UrlFilter را ببینید.

تطبیق CSS

شرایط PageStateMatcher.css باید انتخابگرهای ترکیبی باشند، به این معنی که نمی‌توانید ترکیب‌کننده‌هایی مانند فضای خالی یا " > " را در انتخابگرهای خود قرار دهید. این به Chrome کمک می‌کند تا انتخاب‌کننده‌ها را کارآمدتر مطابقت دهد.

انتخابگرهای ترکیبی (OK) انتخابگرهای پیچیده (خوب نیست)
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 امکان تطبیق وضعیت نشانک شده URL فعلی در نمایه کاربر را فراهم می کند. برای استفاده از این شرط، مجوز «نشانک‌ها» باید در مانیفست پسوند اعلام شود.

انواع

ImageDataType

به https://developer.mozilla.org/en-US/docs/Web/API/ImageData مراجعه کنید.

تایپ کنید

ImageData

PageStateMatcher

با وضعیت یک صفحه وب بر اساس معیارهای مختلف مطابقت دارد.

خواص

  • سازنده

    خالی

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

    (arg: PageStateMatcher)=> {...}

  • css

    رشته[] اختیاری است

    در صورتی که همه انتخابگرهای CSS در آرایه با عناصر نمایش داده شده در فریمی با منشأ همان قاب اصلی صفحه مطابقت داشته باشند، مطابقت دارد. همه انتخابگرها در این آرایه باید انتخابگرهای مرکب باشند تا تطبیق سرعت بیشتری داشته باشد. توجه: فهرست کردن صدها انتخابگر CSS یا فهرست کردن انتخابگرهای CSS که صدها بار در هر صفحه مطابقت دارند، می‌تواند سرعت وب‌سایت‌ها را کاهش دهد.

  • نشانه گذاری شده است

    بولی اختیاری

    Chrome 45+

    در صورتی مطابقت دارد که حالت نشانک شده صفحه با مقدار مشخص شده برابر باشد. به مجوز نشانک ها نیاز دارد.

  • آدرس صفحه

    UrlFilter اختیاری است

    مطابق با شرایط UrlFilter برای URL سطح بالای صفحه است.

RequestContentScript

کنش رویداد اعلامی که یک اسکریپت محتوا را تزریق می کند.

هشدار: این اقدام هنوز آزمایشی است و در ساخت‌های پایدار Chrome پشتیبانی نمی‌شود.

خواص

  • سازنده

    خالی

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

    (arg: RequestContentScript)=> {...}

  • همه فریم ها

    بولی اختیاری

    خواه اسکریپت محتوا در تمام فریم های صفحه مطابقت اجرا شود یا فقط در فریم بالایی. پیش فرض 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)=> {...}

  • داده های تصویری

    ImageData|شیء اختیاری است

    یک شی ImageData یا یک فرهنگ لغت {size -> ImageData} که نمادی را نشان می دهد که باید تنظیم شود. اگر نماد به عنوان فرهنگ لغت مشخص شده باشد، تصویر مورد استفاده بسته به تراکم پیکسلی صفحه نمایش انتخاب می شود. اگر تعداد پیکسل های تصویری که در یک واحد فضای صفحه نمایش قرار می گیرند برابر با scale باشد، تصویری با scale * n انتخاب می شود که n اندازه نماد در رابط کاربری است. حداقل یک تصویر باید مشخص شود. توجه داشته باشید که details.imageData = foo معادل details.imageData = {'16': foo} است.

ShowAction

Chrome 97+

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

در صفحاتی که شرایط برآورده نمی شوند، عملکرد نوار ابزار برنامه افزودنی در مقیاس خاکستری خواهد بود و با کلیک بر روی آن، به جای فعال کردن عملکرد، منوی زمینه باز می شود.

خواص

ShowPageAction

از Chrome 97 منسوخ شده است

لطفاً از declarativeContent.ShowAction استفاده کنید.

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

در صفحاتی که شرایط برآورده نمی شوند، عملکرد نوار ابزار برنامه افزودنی در مقیاس خاکستری خواهد بود و با کلیک بر روی آن، به جای فعال کردن عملکرد، منوی زمینه باز می شود.

خواص

مناسبت ها

onPageChanged

API Declarative Event متشکل از addRules ، removeRules و getRules را ارائه می دهد.

شرایط

PageStateMatcher

اقدامات

RequestContentScript

SetIcon

ShowPageAction

ShowAction