chrome.events

توضیحات

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

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

یک 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 باید دارای یک شناسه منحصر به فرد باشد که قبلاً توسط قانون دیگری یا یک شناسه خالی استفاده نشده است.

توجه: قوانین در تمام جلسات مرور پایدار هستند. بنابراین، باید قوانین را در زمان نصب برنامه افزودنی با استفاده از رویداد runtime.onInstalled نصب کنید. توجه داشته باشید که این رویداد هنگام به‌روزرسانی یک برنامه افزودنی نیز فعال می‌شود. بنابراین، ابتدا باید قوانین نصب شده قبلی را پاک کنید و سپس قوانین جدید را ثبت کنید.

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

برای حذف قوانین 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 قابل بیان است. UrlFilter، به جز تطبیق طرح و پورت.

انواع

Event

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

خواص

• addListener

  باطل

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

  تابع addListener به شکل زیر است:

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

  • پاسخ به تماس

    اچ

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

• addRules

  باطل

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

  تابع addRules به شکل زیر است:

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

  • قوانین

    قانون <anyany>[]

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

  • پاسخ به تماس

    عملکرد اختیاری

    پارامتر callback به نظر می رسد:

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

    • قوانین

      قانون <anyany>[]

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

• قوانین را دریافت کنید

  باطل

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

  تابع getRules به نظر می رسد:

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

  • شناسه های rule

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

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

  • پاسخ به تماس

    تابع

    پارامتر callback به نظر می رسد:

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

    • قوانین

      قانون <anyany>[]

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

• hasListener

  باطل

  تابع hasListener به شکل زیر است:

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

  • پاسخ به تماس

    اچ

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

  • برمی گرداند

    بولی

    اگر پاسخ تماس در رویداد ثبت شده باشد درست است.

• شنوندگان دارد

  باطل

  تابع hasListeners به ​​شکل زیر است:

  () => {...}

  • برمی گرداند

    بولی

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

• removeListener

  باطل

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

  تابع removeListener به شکل زیر است:

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

  • پاسخ به تماس

    اچ

    شنونده ای که باید ثبت نشده باشد.

• حذف قوانین

  باطل

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

  تابع removeRules به نظر می رسد:

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

  • شناسه های rule

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

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

  • پاسخ به تماس

    عملکرد اختیاری

    پارامتر callback به نظر می رسد:

    () => void

Rule

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

خواص

• اقدامات

  هر[]

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

• شرایط

  هر[]

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

• شناسه

  رشته اختیاری

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

• اولویت

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

  اولویت اختیاری این قانون. پیش فرض 100 است.

• برچسب ها

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

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

UrlFilter

URL ها را برای معیارهای مختلف فیلتر می کند. فیلتر کردن رویداد را ببینید. همه معیارها به حروف کوچک و بزرگ حساس هستند.

خواص

• cidrBlocks

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

  Chrome 123+

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

• میزبان حاوی

  رشته اختیاری

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

• میزبان برابر است

  رشته اختیاری

  اگر نام میزبان URL برابر با یک رشته مشخص باشد مطابقت دارد.

• hostPrefix

  رشته اختیاری

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

• پسوند میزبان

  رشته اختیاری

  در صورتی مطابقت دارد که نام میزبان URL به یک رشته مشخص ختم شود.

• OriginalAndPathMatches

  رشته اختیاری

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

• مسیر شامل

  رشته اختیاری

  در صورتی مطابقت دارد که بخش مسیر URL حاوی یک رشته مشخص باشد.

• مسیر برابر است

  رشته اختیاری

  در صورتی مطابقت دارد که بخش مسیر URL برابر با یک رشته مشخص باشد.

• پیشوند path

  رشته اختیاری

  اگر قسمت مسیر URL با یک رشته مشخص شروع شود مطابقت دارد.

• پسوند path

  رشته اختیاری

  در صورتی مطابقت دارد که بخش مسیر URL با یک رشته مشخص به پایان برسد.

• پورت ها

  (شماره | شماره[])[] اختیاری است

  اگر پورت URL در هر یک از لیست های پورت مشخص شده باشد مطابقت دارد. برای مثال [80, 443, [1000, 1200]] با تمام درخواست‌های موجود در پورت 80، 443 و در محدوده 1000-1200 مطابقت دارد.

• queryContains

  رشته اختیاری

  در صورتی مطابقت دارد که بخش پرس و جو URL حاوی یک رشته مشخص باشد.

• queryEquals

  رشته اختیاری

  در صورتی مطابقت دارد که بخش پرس و جو از URL برابر با یک رشته مشخص شده باشد.

• queryPrefix

  رشته اختیاری

  در صورتی مطابقت دارد که بخش پرس و جو از URL با یک رشته مشخص شروع شود.

• پسوند query

  رشته اختیاری

  در صورتی مطابقت دارد که بخش پرس و جو از URL با یک رشته مشخص به پایان برسد.

• طرح ها

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

  در صورتی مطابقت دارد که طرح URL با هر یک از طرح های مشخص شده در آرایه برابر باشد.

• url حاوی

  رشته اختیاری

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

• urlEquals

  رشته اختیاری

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

• urlMatches

  رشته اختیاری

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

• urlPrefix

  رشته اختیاری

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

• پسوند url

  رشته اختیاری

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