مرورگر.رویدادها

توضیحات

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

یک Event شیء‌ای است که به شما امکان می‌دهد از وقوع اتفاق جالبی مطلع شوید. در اینجا مثالی از استفاده از رویداد browser.alarms.onAlarm برای مطلع شدن از زمان سپری شدن یک هشدار (alarm) آورده شده است:

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

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

مثال‌هایی از APIهایی که از Events استفاده می‌کنند: alarms ، i18n ، identity ، runtime . اکثر APIهای کروم این کار را انجام می‌دهند.

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

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

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

عملکرد

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

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

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

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

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