chrome.events

refresh date: 2026-09-25 robots: noindex

شرح

فضای نام chrome.events حاوی انواع رایجی است که میاناهای برنامه‌سازی کاربردی برای ارسال رویدادها استفاده می‌کنند تا وقتی اتفاق جالبی می‌افتد به شما اطلاع دهند.

Event شیئی است که به شما امکان می‌دهد وقتی اتفاق جالبی می‌افتد مطلع شوید. در اینجا نمونه‌ای از استفاده از رویداد chrome.alarms.onAlarm برای دریافت اعلان در هر زمان که زنگ هشدار منقضی شده است آورده شده است:

chrome.alarms.onAlarm.addListener(function(alarm) {
  appendToLog('alarms.onAlarm --'
              + ' name: '          + alarm.name
              + ' scheduledTime: ' + alarm.scheduledTime);
});

همان‌طور که در مثال نشان داده شده است، بااستفاده از addListener() برای اعلان ثبت‌نام می‌کنید. متغیر مستقل addListener() همیشه تابعی است که برای رسیدگی به رویداد تعریف می‌کنید، اما پارامترهای تابع به رویدادی که به آن رسیدگی می‌کنید بستگی دارد. با بررسی مستندات alarms.onAlarm، می‌توانید ببینید که تابع یک پارامتر واحد دارد: یک شیء alarms.Alarm که جزئیاتی درباره زنگ هشدار سپری‌شده دارد.

نمونه‌های میاناهای برنامه‌سازی کاربردی که از «رویدادها» استفاده می‌کنند: alarms،‏ i18n،‏ identity،‏ runtime. اکثر chrome APIs این کار را می‌کنند.

مدیران رویداد اظهاری

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

از گرداننده‌های رویداد اعلانی برای مثال در Declarative Web Request API و Declarative Content API استفاده می‌شود. این صفحه مفاهیم اساسی همه گرداننده‌های رویداد اعلانی را شرح می‌دهد.

قوانین

ساده‌ترین قانون ممکن شامل یک یا چند شرط و یک یا چند کنش است:

var rule = {
  conditions: [ /* my conditions */ ],
  actions: [ /* my actions */ ]
};

اگر هریک از شرایط برآورده شود، همه کنش‌ها اجرا می‌شود.

علاوه‌بر شرایط و کنش‌ها، می‌توانید به هر قانون یک شناسه اختصاص دهید که لغو ثبت قوانین قبلاً ثبت‌شده را ساده‌تر می‌کند، و همچنین اولویتی برای تعریف تقدم بین قوانین. اولویت‌ها فقط درصورتی درنظر گرفته می‌شوند که قوانین با یکدیگر تداخل داشته باشند یا لازم باشد به ترتیب خاصی اجرا شوند. کنش‌ها به‌ترتیب نزولی اولویت قانون‌هایشان اجرا می‌شوند.

var rule = {
  id: "my rule",  // optional, will be generated if not set.
  priority: 100,  // optional, defaults to 100.
  conditions: [ /* my conditions */ ],
  actions: [ /* my actions */ ]
};

اشیای رویداد

اشیاء رویداد ممکن است از قوانین پشتیبانی کنند. این شیءهای رویداد هنگام وقوع رویدادها تابع بازخوانی را فراخوانی نمی‌کنند، بلکه آزمایش می‌کنند که آیا قانون ثبت‌شده‌ای حداقل یک شرط برآورده‌شده دارد یا نه و کنش‌های مرتبط با این قانون را اجرا می‌کنند. اشیاء رویداد که از API اعلانی پشتیبانی می‌کنند سه روش مرتبط دارند: events.Event.addRules، events.Event.removeRules، و events.Event.getRules.

افزودن قانون

برای افزودن قانون، تابع addRules() شیء رویداد را فراخوانی کنید. این تابع آرایه‌ای از نمونه‌های قانون را به‌عنوان پارامتر اول خود و یک تابع بازخوانی را که پس‌از تکمیل فراخوانی می‌شود دریافت می‌کند.

var rule_list = [rule1, rule2, ...];
function addRules(rule_list, function callback(details) {...});

اگر قوانین با موفقیت درج شده باشند، پارامتر details حاوی آرایه‌ای از قوانین درج‌شده است که به همان ترتیبی که در rule_list ارسال‌شده ظاهر می‌شوند، جایی که پارامترهای اختیاری id و priority با مقادیر تولیدشده پر شده‌اند. اگر قانونی نامعتبر باشد، مثلاً به‌دلیل داشتن شرط یا کنش نامعتبر، هیچ‌کدام از قوانین اضافه نمی‌شوند و متغیر runtime.lastError هنگام فراخوانی تابع بازخوانی تنظیم می‌شود. هر قانون در rule_list باید حاوی شناسه یکتایی باشد که درحال‌حاضر توسط قانون دیگری استفاده نمی‌شود یا شناسه خالی باشد.

درحال برداشتن قوانین

برای برداشتن قوانین، تابع removeRules() را فراخوانی کنید. این روش یک آرایه اختیاری از شناسه‌های قانون را به‌عنوان پارامتر اول و یک تابع بازخوانی را به‌عنوان پارامتر دوم می‌پذیرد.

var rule_ids = ["id1", "id2", ...];
function removeRules(rule_ids, function callback() {...});

اگر rule_ids آرایه‌ای از شناسه‌ها باشد، همه قوانینی که شناسه‌های فهرست‌شده در آرایه را دارند برداشته می‌شوند. اگر rule_ids شناسه‌ای را فهرست کند که ناشناخته است، این شناسه بدون اطلاع نادیده گرفته می‌شود. اگر rule_ids undefined باشد، همه قوانین ثبت‌شده این افزونه برداشته می‌شود. تابع callback() هنگام برداشته شدن قوانین فراخوانده می‌شود.

درحال بازیابی قوانین

برای بازیابی فهرست قوانین ثبت‌شده فعلی، تابع getRules() را فراخوانی کنید. این تابع یک آرایه اختیاری از شناسه‌های قانون با همان معناشناسی removeRules و یک تابع بازخوانی را می‌پذیرد.

var rule_ids = ["id1", "id2", ...];
function getRules(rule_ids, function callback(details) {...});

پارامتر details که به تابع callback() ارسال شده است به آرایه‌ای از قوانین اشاره دارد که شامل پارامترهای اختیاری تکمیل‌شده است.

عملکرد

برای دستیابی به حداکثر عملکرد، باید دستورالعمل‌های زیر را درنظر داشته باشید.

ثبت و لغو ثبت قوانین به‌صورت انبوه. پس‌از هر ثبت‌نام یا لغو ثبت‌نام، Chrome باید ساختارهای داده داخلی را به‌روز کند. این به‌روزرسانی عملیات پرهزینه‌ای است.

به‌جای:

var rule1 = {...};
var rule2 = {...};
chrome.declarativeWebRequest.onRequest.addRules([rule1]);
chrome.declarativeWebRequest.onRequest.addRules([rule2]);

ترجیح:

var rule1 = {...};
var rule2 = {...};
chrome.declarativeWebRequest.onRequest.addRules([rule1, rule2]);

تطابق زیررشته را بر عبارات باقاعده در events.UrlFilter ترجیح دهید. تطبیق مبتنی بر زیررشته بسیار سریع است.

به‌جای:

var match = new chrome.declarativeWebRequest.RequestMatcher({
    url: {urlMatches: "example.com/[^?]*foo" } });

ترجیح:

var match = new chrome.declarativeWebRequest.RequestMatcher({
    url: {hostSuffix: "example.com", pathContains: "foo"} });

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

به‌جای:

var condition1 = new chrome.declarativeWebRequest.RequestMatcher({
    url: { hostSuffix: 'example.com' } });
var condition2 = new chrome.declarativeWebRequest.RequestMatcher({
    url: { hostSuffix: 'foobar.com' } });
var rule1 = { conditions: [condition1],
              actions: [new chrome.declarativeWebRequest.CancelRequest()]};
var rule2 = { conditions: [condition2],
              actions: [new chrome.declarativeWebRequest.CancelRequest()]};
chrome.declarativeWebRequest.onRequest.addRules([rule1, rule2]);

ترجیح:

  var rule = { conditions: [condition1, condition2],
                actions: [new chrome.declarativeWebRequest.CancelRequest()]};
  chrome.declarativeWebRequest.onRequest.addRules([rule]);

رویدادهای فیلترشده

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

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

chrome.webNavigation.onCommitted.addListener(function(e) {
  if (hasHostSuffix(e.url, 'google.com') ||
      hasHostSuffix(e.url, 'google.com.au')) {
    // ...
  }
});

به این:

chrome.webNavigation.onCommitted.addListener(function(e) {
  // ...
}, {url: [{hostSuffix: 'google.com'},
          {hostSuffix: 'google.com.au'}]});

رویدادها از فیلترهای خاصی پشتیبانی می‌کنند که برای آن رویداد معنی‌دار هستند. فهرست فیلترهایی که رویداد پشتیبانی می‌کند در اسناد آن رویداد در بخش «فیلترها» فهرست خواهد شد.

هنگام مطابقت دادن نشانی‌های وب (مانند مثال بالا)، فیلترهای رویداد از همان قابلیت‌های مطابقت دادن نشانی وب که با events.UrlFilter قابل‌بیان است پشتیبانی می‌کنند، به‌جز مطابقت دادن طرح و درگاه.

انواع

Event

شیئی که امکان افزودن و برداشتن شنوندگان را برای رویداد Chrome فراهم می‌کند.

مشخصات

  • addListener

    باطل کردن

    فراخوان برگشتی شنونده رویداد را برای رویدادی ثبت می‌کند.

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

    (callback: H) => {...}

    • تماس برگشتی

      H

      وقتی رویدادی رخ می‌دهد فراخوانی می‌شود. پارامترهای این تابع به نوع رویداد بستگی دارد.

  • addRules

    باطل کردن

    قوانین را برای رسیدگی به رویدادها ثبت می‌کند.

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

    (rules: Rule<anyany>[], callback?: function) => {...}

    • قوانین

      قانون<anyany>[]

      قوانینی که باید ثبت شوند. این‌ها جایگزین قوانین ثبت‌شده قبلی نمی‌شوند.

    • تماس برگشتی

      تابع اختیاری

      پارامتر callback به‌صورت زیر است: 

      (rules: Rule<anyany>[]) => void

      • قوانین

        قانون<anyany>[]

        قوانینی که ثبت شده‌اند، پارامترهای اختیاری با مقادیر پر شده‌اند.

  • getRules

    باطل کردن

    قوانین ثبت‌شده فعلی را برمی‌گرداند.

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

    (ruleIdentifiers?: string[], callback: function) => {...}

    • ruleIdentifiers

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

      اگر آرایه‌ای ارسال شود، فقط قوانینی که شناسه‌هایشان در این آرایه وجود دارد برگردانده می‌شوند.

    • تماس برگشتی

      عملکرد

      پارامتر callback به‌صورت زیر است: 

      (rules: Rule<anyany>[]) => void

      • قوانین

        قانون<anyany>[]

        قوانینی که ثبت شده‌اند، پارامترهای اختیاری با مقادیر پر شده‌اند.

  • hasListener

    باطل کردن

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

    (callback: H) => {...}

    • تماس برگشتی

      H

      شنونده‌ای که وضعیت ثبت‌نام او باید آزمایش شود.

    • returns

      بولی

      اگر callback برای رویداد ثبت شده باشد، True است.

  • hasListeners

    باطل کردن

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

    () => {...}

    • returns

      بولی

      اگر هرکدام از شنوندگان رویداد برای رویداد ثبت شده باشند، درست است.

  • removeListener

    باطل کردن

    لغو ثبت callback شنونده رویداد از رویداد.

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

    (callback: H) => {...}

    • تماس برگشتی

      H

      شنونده‌ای که باید لغو ثبت‌نام شود.

  • removeRules

    باطل کردن

    قوانین ثبت‌شده فعلی را لغو ثبت می‌کند.

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

    (ruleIdentifiers?: string[], callback?: function) => {...}

    • ruleIdentifiers

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

      اگر آرایه‌ای ارسال شود، فقط قوانینی که شناسه‌هایشان در این آرایه وجود دارد لغو ثبت می‌شوند.

    • تماس برگشتی

      تابع اختیاری

      پارامتر callback به‌صورت زیر است: 

      () => void

Rule

شرح قانون اعلانی برای رسیدگی به رویدادها.

مشخصات

  • کنش‌ها

    any[]

    فهرست کنش‌هایی که درصورت برآورده شدن یکی از شرایط راه‌اندازی می‌شوند.

  • عارضه‌ها

    any[]

    فهرست شرایطی که می‌تواند کنش‌ها را راه‌اندازی کند.

  • id

    رشته اختیاری

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

  • اولویت‌دار

    شماره اختیاری

    اولویت اختیاری این قانون. پیش‌فرض ۱۰۰ است.

  • برچسب‌ها

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

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

UrlFilter

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

مشخصات

  • cidrBlocks

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

    Chrome نسخه ۱۲۳ به بالا

    اگر بخش میزبان نشانی وب یک نشانی IP باشد و در هریک از بلوک‌های CIDR مشخص‌شده در آرایه موجود باشد، مطابقت دارد.

  • hostContains

    رشته اختیاری

    اگر نام میزبان نشانی وب حاوی رشته مشخص‌شده‌ای باشد، مطابقت دارد. برای آزمایش اینکه آیا مؤلفه نام میزبان پیشوند «foo» دارد یا نه، از hostContains: '.foo' استفاده کنید. این با «www.foobar.com» و «foo.com» مطابقت دارد، زیرا یک نقطه ضمنی به ابتدای نام میزبان اضافه شده است. به‌طور مشابه، می‌توان از hostContains برای مطابقت با پسوند مؤلفه (foo.) و مطابقت دقیق با مؤلفه‌ها (.foo.) استفاده کرد. تطبیق پسوند و تطبیق دقیق برای آخرین مؤلفه‌ها باید به‌طور جداگانه بااستفاده از hostSuffix انجام شود، زیرا هیچ نقطه ضمنی‌ای به انتهای نام میزبان اضافه نمی‌شود.

  • hostEquals

    رشته اختیاری

    اگر نام میزبان نشانی وب با رشته مشخص‌شده برابر باشد، مطابقت دارد.

  • hostPrefix

    رشته اختیاری

    اگر نام میزبان نشانی وب با رشته مشخص‌شده‌ای شروع شود، مطابقت دارد.

  • hostSuffix

    رشته اختیاری

    اگر نام میزبان نشانی وب با رشته مشخص‌شده‌ای به‌پایان برسد، مطابقت دارد.

  • originAndPathMatches

    رشته اختیاری

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

  • pathContains

    رشته اختیاری

    اگر بخش مسیر نشانی وب حاوی رشته مشخص‌شده‌ای باشد، مطابقت دارد.

  • pathEquals

    رشته اختیاری

    اگر بخش مسیر نشانی وب با رشته مشخص‌شده برابر باشد، مطابقت دارد.

  • pathPrefix

    رشته اختیاری

    اگر بخش مسیر نشانی وب با رشته مشخص‌شده‌ای شروع شود، مطابقت دارد.

  • pathSuffix

    رشته اختیاری

    اگر بخش مسیر نشانی وب با رشته مشخص‌شده‌ای به‌پایان برسد، مطابقت دارد.

  • درگاه‌ها

    (number | number[])[] اختیاری

    اگر درگاه نشانی وب در هرکدام از فهرست‌های درگاه مشخص‌شده وجود داشته باشد، مطابقت دارد. برای مثال، [80, 443, [1000, 1200]] با همه درخواست‌ها در درگاه ۸۰، ۴۴۳، و در محدوده ۱۰۰۰-۱۲۰۰ مطابقت دارد.

  • queryContains

    رشته اختیاری

    اگر بخش پُرسمان نشانی وب حاوی رشته مشخص‌شده‌ای باشد، مطابقت دارد.

  • queryEquals

    رشته اختیاری

    اگر بخش پُرسمان نشانی وب با رشته مشخص‌شده برابر باشد، مطابقت دارد.

  • queryPrefix

    رشته اختیاری

    اگر بخش پُرسمان نشانی وب با رشته مشخص‌شده‌ای شروع شود، مطابقت دارد.

  • querySuffix

    رشته اختیاری

    اگر بخش پُرسمان نشانی وب با رشته مشخص‌شده‌ای به‌پایان برسد، مطابقت دارد.

  • طرح‌ها

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

    اگر طرح‌واره نشانی وب با هرکدام از طرح‌واره‌های مشخص‌شده در آرایه برابر باشد، مطابقت دارد.

  • urlContains

    رشته اختیاری

    اگر نشانی وب (بدون شناسه بخش) حاوی رشته مشخص‌شده‌ای باشد، مطابقت دارد. اگر شماره‌های درگاه با شماره درگاه پیش‌فرض مطابقت داشته باشند، از نشانی وب حذف می‌شوند.

  • urlEquals

    رشته اختیاری

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

  • urlMatches

    رشته اختیاری

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

  • urlPrefix

    رشته اختیاری

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

  • urlSuffix

    رشته اختیاری

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