chrome.declarativeContent

تاریخ به‌روزرسانی: 2026-09-25 ربات‌ها: noindex

توضیحات

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

مجوزها

declarativeContent

کاربرد

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

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

قوانین

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

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

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

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

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) است که به دنبال آن شامل، مساوی، پیشوند یا پسوند می‌آید. جدول زیر شامل چند مثال است:

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

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

تطبیق CSS

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

انتخابگرهای مرکب (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 فعلی در پروفایل کاربر را فراهم می‌کند. برای استفاده از این شرط، مجوز "bookmarks" باید در فایل manifest افزونه تعریف شود.

انواع

ImageDataType

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

نوع

داده تصویر

PageStateMatcher

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

خواص

  • سازنده

    باطل

    تابع constructor به شکل زیر است: 

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

  • سی‌اس‌اس

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

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

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

    بولی اختیاری

    کروم ۴۵+

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

  • آدرس صفحه

    فیلتر آدرس (اختیاری)

    در صورتی که شرایط UrlFilter برای URL سطح بالای صفحه برقرار باشد، تطبیق می‌یابد.

RequestContentScript

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

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

خواص

  • سازنده

    باطل

    تابع constructor به شکل زیر است: 

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

  • همه فریم‌ها

    بولی اختیاری

    اینکه آیا اسکریپت محتوا در تمام فریم‌های صفحه منطبق اجرا شود یا فقط در فریم بالایی. مقدار پیش‌فرض false است.

  • سی‌اس‌اس

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

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

  • جی‌اس

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

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

  • matchAboutBlank

    بولی اختیاری

    اینکه آیا اسکریپت محتوا در about:blank و about:srcdoc درج شود یا خیر. مقدار پیش‌فرض false است.

SetIcon

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

دقیقاً یکی از imageData یا path باید مشخص شود. هر دو دیکشنری‌هایی هستند که تعدادی پیکسل را به یک نمایش تصویر نگاشت می‌کنند. نمایش تصویر در imageData یک شیء ImageData است؛ برای مثال، از یک عنصر canvas ، در حالی که نمایش تصویر در path مسیر یک فایل تصویر نسبت به مانیفست افزونه است. اگر پیکسل‌های صفحه نمایش scale در یک پیکسل مستقل از دستگاه قرار بگیرند، از آیکون scale * n استفاده می‌شود. اگر آن scale وجود نداشته باشد، تصویر دیگری به اندازه مورد نیاز تغییر اندازه داده می‌شود.

خواص

  • سازنده

    باطل

    تابع constructor به شکل زیر است: 

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

  • تصویرداده

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

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

ShowAction

کروم ۹۷+

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

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

خواص

ShowPageAction

از کروم ۹۷ منسوخ شده است

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

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

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

خواص

رویدادها