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 که جزئیات مربوط به زنگ سپری شده را دارد.

نمونه APIهایی با استفاده از رویدادها: زنگ هشدار ، i18n ، هویت ، زمان اجرا . اکثر API های کروم انجام می دهند.

کنترل کننده رویداد اعلامی

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

کنترل‌کننده‌های رویداد اعلامی برای مثال در API درخواست وب اعلامی و 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 هنگام فراخوانی تابع callback تنظیم می شود. هر قانون در rule_list باید دارای یک شناسه منحصر به فرد باشد که در حال حاضر توسط قانون دیگری یا یک شناسه خالی استفاده نمی شود.

حذف قوانین

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

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

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

بازیابی قوانین

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

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]);

تطبیق زیررشته‌ها را به عبارات معمولی در رویداد ترجیح دهید. 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'}]});

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

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