browser.events

شرح

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

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

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

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

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

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

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

برای مثال، از گرداننده‌های رویداد اعلانی در Declarative Content 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 هنگام فراخوانی تابع بازخوانی تنظیم می‌شود. هر قانون در rule_list باید حاوی شناسه یکتایی باشد که قبلاً توسط قانون دیگری استفاده نشده باشد یا شناسه خالی باشد.

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

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

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

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

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

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

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

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

عملکرد

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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