chrome.declarativeContent

refresh date: 2026-09-25 robots: noindex

شرح

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

اجازه‌ها

declarativeContent

توجه: برای انتقال از کنش صفحه به کنش، شبیه‌سازی pageActions با declarativeContent را ببینید

کاربرد

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

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

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

قوانین

قوانین شامل شرایط و کنش‌ها است. اگر هریک از شرایط برآورده شود، همه کنش‌ها اجرا می‌شود. کنش‌ها عبارت‌اند از setIcon و showAction.

PageStateMatcher فقط درصورتی با صفحه‌های وب مطابقت دارد که همه معیارهای فهرست‌شده برآورده شده باشد. می‌تواند با نشانی وب صفحه، گزینشگر ترکیبی 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، افزونه شما هیچ هشدار اجازه‌ای نمایش نخواهد داد و وقتی کاربر روی کنش افزونه کلیک می‌کند، فقط در صفحه‌های مربوطه اجرا خواهد شد.

مطابقت نشانی وب صفحه

وقتی معیارهای نشانی وب برآورده شود، 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

    PageStateMatcher

  • returns

    PageStateMatcher

• css

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

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

• isBookmarked

  بولی اختیاری

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

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

• pageUrl

  UrlFilter اختیاری

  اگر شرایط UrlFilter برای نشانی وب سطح بالای صفحه برآورده شود، مطابقت دارد.

RequestContentScript

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

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

مشخصات

• سازنده

  باطل کردن

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

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

  • arg

    RequestContentScript

  • returns

    RequestContentScript

• 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

    SetIcon

  • returns

    SetIcon

• imageData

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

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

ShowAction

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

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

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

مشخصات

• سازنده

  باطل کردن

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

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

  • arg

    ShowAction

  • returns

    ShowAction

ShowPageAction

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

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

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

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

مشخصات

• سازنده

  باطل کردن

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

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

  • arg

    ShowPageAction

  • returns

    ShowPageAction

رویدادها

onPageChanged

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

وضعیت

PageStateMatcher

کنش‌ها

RequestContentScript

SetIcon

ShowPageAction

ShowAction