chrome.events

شرح

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

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

chrome.alarms.onAlarm.addListener((alarm) => {
  appendToLog(`alarms.onAlarm -- name: ${alarm.name}, scheduledTime: ${alarm.scheduledTime}`);
});

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

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

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

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

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

قوانین

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

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

در صورت تحقق هر یک از شرایط، تمام اقدامات اجرا می شوند.

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

const 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() شی رویداد را فراخوانی کنید. آرایه‌ای از نمونه‌های قانون را به‌عنوان پارامتر اول و تابع فراخوانی می‌گیرد که پس از تکمیل فراخوانی می‌شود.

const rule_list = [rule1, rule2, ...];
addRules(rule_list, (details) => {...});

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

قوانین را حذف کنید

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

const rule_ids = ["id1", "id2", ...];
removeRules(rule_ids, () => {...});

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

قوانین را بازیابی کنید

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

const rule_ids = ["id1", "id2", ...];
getRules(rule_ids, (details) => {...});

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

کارایی

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

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

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

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

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

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

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

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

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

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

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

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

رویدادهای فیلتر شده برای امکان گذار از کد فیلتر دستی در نظر گرفته شده است.

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

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

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

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