رویدادها را با اسکریپت های پس زمینه مدیریت کنید

برنامه‌های افزودنی برنامه‌های مبتنی بر رویداد هستند که برای تغییر یا بهبود تجربه مرور Chrome استفاده می‌شوند. رویدادها محرک های مرورگر هستند، مانند پیمایش به یک صفحه جدید، حذف یک نشانک یا بستن یک برگه. برنامه های افزودنی این رویدادها را در اسکریپت پس زمینه خود نظارت می کنند، سپس با دستورالعمل های مشخص شده واکنش نشان می دهند.

یک صفحه پس‌زمینه در صورت نیاز بارگیری می‌شود و زمانی که غیرفعال می‌شود، بارگیری می‌شود. چند نمونه از رویدادها عبارتند از:

  • برنامه افزودنی ابتدا نصب یا به نسخه جدید به روز می شود.
  • صفحه پس‌زمینه در حال گوش دادن به یک رویداد بود و رویداد ارسال می‌شود.
  • یک اسکریپت محتوا یا برنامه افزودنی دیگر پیامی را ارسال می کند.
  • نمای دیگری در برنامه افزودنی، مانند پنجره بازشو، runtime.getBackgroundPage را فراخوانی می‌کند.

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

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

ثبت اسکریپت های پس زمینه

اسکریپت های پس زمینه در مانیفست در قسمت "background" ثبت می شوند. آنها در یک آرایه بعد از کلید "scripts" فهرست می شوند و "persistent" باید به عنوان نادرست مشخص شود.

{
  "name": "Awesome Test Extension",
  ...
  "background": {
    "scripts": ["background.js"],
    "persistent": false
  },
  ...
}

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

{
    "name": "Awesome Test Extension",
    ...
    "background": {
      "scripts": [
        "backgroundContextMenus.js",
        "backgroundOmniBox.js",
        "backgroundOauth.js"
      ],
      "persistent": false
    },
    ...
  }

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

پسوند را راه اندازی کنید

به رویداد runtime.onInstalled گوش دهید تا یک برنامه افزودنی در هنگام نصب مقداردهی شود. از این رویداد برای تنظیم یک وضعیت یا برای مقداردهی اولیه، مانند منوی زمینه استفاده کنید.

chrome.runtime.onInstalled.addListener(function() {
  chrome.contextMenus.create({
    "id": "sampleContextMenu",
    "title": "Sample Context Menu",
    "contexts": ["selection"]
  });
});

شنوندگان را تنظیم کنید

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

شنوندگان باید از ابتدای صفحه به طور همزمان ثبت شوند.

chrome.runtime.onInstalled.addListener(function() {
  chrome.contextMenus.create({
    "id": "sampleContextMenu",
    "title": "Sample Context Menu",
    "contexts": ["selection"]
  });
});

// This will run when a bookmark is created.
chrome.bookmarks.onCreated.addListener(function() {
  // do something
});

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

chrome.runtime.onInstalled.addListener(function() {
  // ERROR! Events must be registered synchronously from the start of
  // the page.
  chrome.bookmarks.onCreated.addListener(function() {
    // do something
  });
});

برنامه های افزودنی می توانند شنوندگان را با فراخوانی removeListener از اسکریپت های پس زمینه خود حذف کنند. اگر همه شنوندگان یک رویداد حذف شوند، Chrome دیگر اسکریپت پس‌زمینه برنامه افزودنی را برای آن رویداد بارگیری نمی‌کند.

chrome.runtime.onMessage.addListener(function(message, sender, reply) {
    chrome.runtime.onMessage.removeListener(event);
});

رویدادها را فیلتر کنید

از API هایی استفاده کنید که از فیلترهای رویداد پشتیبانی می کنند تا شنوندگان را به مواردی که برنامه افزودنی به آنها اهمیت می دهد محدود کند. اگر برنامه افزودنی در حال گوش دادن به رویداد tabs.onUpdated است، به جای آن از رویداد webNavigation.onCompleted با فیلترها استفاده کنید، زیرا API تب ها از فیلترها پشتیبانی نمی کند.

chrome.webNavigation.onCompleted.addListener(function() {
    alert("This is my favorite website!");
}, {url: [{urlMatches : 'https://www.google.com/'}]});

به شنوندگان واکنش نشان دهید

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

chrome.runtime.onMessage.addListener(function(message, callback) {
  if (message.data == "setAlarm") {
    chrome.alarms.create({delayInMinutes: 5})
  } else if (message.data == "runLogic") {
    chrome.tabs.executeScript({file: 'logic.js'});
  } else if (message.data == "changeColor") {
    chrome.tabs.executeScript(
        {code: 'document.body.style.backgroundColor="orange"'});
  };
});

اسکریپت های پس زمینه را بارگیری کنید

داده ها باید به صورت دوره ای حفظ شوند تا در صورت خراب شدن برنامه افزودنی بدون دریافت onSuspend اطلاعات مهم از بین نرود. برای کمک به این کار از API ذخیره سازی استفاده کنید.

chrome.storage.local.set({variable: variableInformation});

اگر افزونه ای از ارسال پیام استفاده می کند، مطمئن شوید که همه پورت ها بسته هستند. اسکریپت پس‌زمینه تا زمانی که همه پورت‌های پیام بسته نشوند، بارگیری نمی‌شود. گوش دادن به رویداد runtime.Port.onDisconnect به شما اطلاعاتی را درباره زمان بسته شدن پورت های باز می دهد. آنها را به صورت دستی با runtime.Port.disconnect ببندید.

chrome.runtime.onMessage.addListener(function(message, callback) {
  if (message == 'hello') {
    sendResponse({greeting: 'welcome!'})
  } else if (message == 'goodbye') {
    chrome.runtime.Port.disconnect();
  }
});

طول عمر یک اسکریپت پس زمینه با نظارت بر زمانی که ورودی برای برنامه افزودنی ظاهر می شود و از مدیر وظیفه Chrome ناپدید می شود قابل مشاهده است.

ALT_TEXT_HERE

با کلیک کردن روی منوی Chrome، نگه داشتن ماوس روی ابزارهای بیشتر و انتخاب «Task Manager»، مدیر وظیفه را باز کنید.

اسکریپت‌های پس‌زمینه پس از چند ثانیه عدم فعالیت، خود به خود تخلیه می‌شوند. اگر به پاکسازی لحظه آخری نیاز است، به رویداد runtime.onSuspend گوش دهید.

chrome.runtime.onSuspend.addListener(function() {
  console.log("Unloading.");
  chrome.browserAction.setBadgeText({text: ""});
});

با این حال، داده های ماندگار باید بر اتکا به runtime.onSuspend ترجیح داده شوند. به اندازه‌ای که ممکن است نیاز باشد، اجازه تمیز کردن را نمی‌دهد و در صورت تصادف کمکی نخواهد کرد.

،

برنامه‌های افزودنی برنامه‌های مبتنی بر رویداد هستند که برای تغییر یا بهبود تجربه مرور Chrome استفاده می‌شوند. رویدادها محرک های مرورگر هستند، مانند پیمایش به یک صفحه جدید، حذف یک نشانک یا بستن یک برگه. برنامه های افزودنی این رویدادها را در اسکریپت پس زمینه خود نظارت می کنند، سپس با دستورالعمل های مشخص شده واکنش نشان می دهند.

یک صفحه پس‌زمینه در صورت نیاز بارگیری می‌شود و زمانی که غیرفعال می‌شود، بارگیری می‌شود. چند نمونه از رویدادها عبارتند از:

  • برنامه افزودنی ابتدا نصب یا به نسخه جدید به روز می شود.
  • صفحه پس‌زمینه در حال گوش دادن به یک رویداد بود و رویداد ارسال می‌شود.
  • یک اسکریپت محتوا یا برنامه افزودنی دیگر پیامی را ارسال می کند.
  • نمای دیگری در برنامه افزودنی، مانند پنجره بازشو، runtime.getBackgroundPage را فراخوانی می‌کند.

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

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

ثبت اسکریپت های پس زمینه

اسکریپت های پس زمینه در مانیفست در قسمت "background" ثبت می شوند. آنها در یک آرایه بعد از کلید "scripts" فهرست می شوند و "persistent" باید به عنوان نادرست مشخص شود.

{
  "name": "Awesome Test Extension",
  ...
  "background": {
    "scripts": ["background.js"],
    "persistent": false
  },
  ...
}

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

{
    "name": "Awesome Test Extension",
    ...
    "background": {
      "scripts": [
        "backgroundContextMenus.js",
        "backgroundOmniBox.js",
        "backgroundOauth.js"
      ],
      "persistent": false
    },
    ...
  }

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

پسوند را راه اندازی کنید

به رویداد runtime.onInstalled گوش دهید تا یک برنامه افزودنی در هنگام نصب مقداردهی شود. از این رویداد برای تنظیم یک وضعیت یا برای مقداردهی اولیه، مانند منوی زمینه استفاده کنید.

chrome.runtime.onInstalled.addListener(function() {
  chrome.contextMenus.create({
    "id": "sampleContextMenu",
    "title": "Sample Context Menu",
    "contexts": ["selection"]
  });
});

شنوندگان را تنظیم کنید

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

شنوندگان باید از ابتدای صفحه به طور همزمان ثبت شوند.

chrome.runtime.onInstalled.addListener(function() {
  chrome.contextMenus.create({
    "id": "sampleContextMenu",
    "title": "Sample Context Menu",
    "contexts": ["selection"]
  });
});

// This will run when a bookmark is created.
chrome.bookmarks.onCreated.addListener(function() {
  // do something
});

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

chrome.runtime.onInstalled.addListener(function() {
  // ERROR! Events must be registered synchronously from the start of
  // the page.
  chrome.bookmarks.onCreated.addListener(function() {
    // do something
  });
});

برنامه های افزودنی می توانند شنوندگان را با فراخوانی removeListener از اسکریپت های پس زمینه خود حذف کنند. اگر همه شنوندگان یک رویداد حذف شوند، Chrome دیگر اسکریپت پس‌زمینه برنامه افزودنی را برای آن رویداد بارگیری نمی‌کند.

chrome.runtime.onMessage.addListener(function(message, sender, reply) {
    chrome.runtime.onMessage.removeListener(event);
});

رویدادها را فیلتر کنید

از API هایی استفاده کنید که از فیلترهای رویداد پشتیبانی می کنند تا شنوندگان را به مواردی که برنامه افزودنی به آنها اهمیت می دهد محدود کند. اگر برنامه افزودنی در حال گوش دادن به رویداد tabs.onUpdated است، به جای آن از رویداد webNavigation.onCompleted با فیلترها استفاده کنید، زیرا API تب ها از فیلترها پشتیبانی نمی کند.

chrome.webNavigation.onCompleted.addListener(function() {
    alert("This is my favorite website!");
}, {url: [{urlMatches : 'https://www.google.com/'}]});

به شنوندگان واکنش نشان دهید

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

chrome.runtime.onMessage.addListener(function(message, callback) {
  if (message.data == "setAlarm") {
    chrome.alarms.create({delayInMinutes: 5})
  } else if (message.data == "runLogic") {
    chrome.tabs.executeScript({file: 'logic.js'});
  } else if (message.data == "changeColor") {
    chrome.tabs.executeScript(
        {code: 'document.body.style.backgroundColor="orange"'});
  };
});

اسکریپت های پس زمینه را بارگیری کنید

داده ها باید به صورت دوره ای حفظ شوند تا در صورت خراب شدن برنامه افزودنی بدون دریافت onSuspend اطلاعات مهم از بین نرود. برای کمک به این کار از API ذخیره سازی استفاده کنید.

chrome.storage.local.set({variable: variableInformation});

اگر افزونه ای از ارسال پیام استفاده می کند، مطمئن شوید که همه پورت ها بسته هستند. اسکریپت پس‌زمینه تا زمانی که همه پورت‌های پیام بسته نشوند، بارگیری نمی‌شود. گوش دادن به رویداد runtime.Port.onDisconnect به شما اطلاعاتی را درباره زمان بسته شدن پورت های باز می دهد. آنها را به صورت دستی با runtime.Port.disconnect ببندید.

chrome.runtime.onMessage.addListener(function(message, callback) {
  if (message == 'hello') {
    sendResponse({greeting: 'welcome!'})
  } else if (message == 'goodbye') {
    chrome.runtime.Port.disconnect();
  }
});

طول عمر یک اسکریپت پس زمینه با نظارت بر زمانی که ورودی برای برنامه افزودنی ظاهر می شود و از مدیر وظیفه Chrome ناپدید می شود قابل مشاهده است.

ALT_TEXT_HERE

با کلیک کردن روی منوی Chrome، نگه داشتن ماوس روی ابزارهای بیشتر و انتخاب «Task Manager»، مدیر وظیفه را باز کنید.

اسکریپت‌های پس‌زمینه پس از چند ثانیه عدم فعالیت، خود به خود تخلیه می‌شوند. اگر به پاکسازی لحظه آخری نیاز است، به رویداد runtime.onSuspend گوش دهید.

chrome.runtime.onSuspend.addListener(function() {
  console.log("Unloading.");
  chrome.browserAction.setBadgeText({text: ""});
});

با این حال، داده های ماندگار باید بر اتکا به runtime.onSuspend ترجیح داده شوند. به اندازه‌ای که ممکن است نیاز باشد، اجازه تمیز کردن را نمی‌دهد و در صورت تصادف کمکی نخواهد کرد.