From 1109132f09d75da9a28b649c7677bb6ce07c40c0 Mon Sep 17 00:00:00 2001 From: Peter Bengtsson Date: Tue, 8 Dec 2020 14:41:45 -0500 Subject: initial commit --- .../mozilla/add-ons/webextensions/api/index.html | 61 +++ .../add-ons/webextensions/api/runtime/index.html | 168 ++++++++ .../webextensions/api/runtime/onmessage/index.html | 317 ++++++++++++++ files/fa/mozilla/add-ons/webextensions/index.html | 97 +++++ .../your_first_webextension/index.html | 152 +++++++ .../your_second_webextension/index.html | 458 +++++++++++++++++++++ 6 files changed, 1253 insertions(+) create mode 100644 files/fa/mozilla/add-ons/webextensions/api/index.html create mode 100644 files/fa/mozilla/add-ons/webextensions/api/runtime/index.html create mode 100644 files/fa/mozilla/add-ons/webextensions/api/runtime/onmessage/index.html create mode 100644 files/fa/mozilla/add-ons/webextensions/index.html create mode 100644 files/fa/mozilla/add-ons/webextensions/your_first_webextension/index.html create mode 100644 files/fa/mozilla/add-ons/webextensions/your_second_webextension/index.html (limited to 'files/fa/mozilla/add-ons/webextensions') diff --git a/files/fa/mozilla/add-ons/webextensions/api/index.html b/files/fa/mozilla/add-ons/webextensions/api/index.html new file mode 100644 index 0000000000..724bf34516 --- /dev/null +++ b/files/fa/mozilla/add-ons/webextensions/api/index.html @@ -0,0 +1,61 @@ +--- +title: JavaScript APIs +slug: Mozilla/Add-ons/WebExtensions/API +tags: + - NeedsTranslation + - TopicStub + - WebExtensions +translation_of: Mozilla/Add-ons/WebExtensions/API +--- +
{{AddonSidebar}}
+ +
+

JavaScript APIs for WebExtensions can be used inside the extension's background scripts and in any other documents bundled with the extension, including browser action or page action popups, sidebars, options pages, or new tab pages. A few of these APIs can also be accessed by an extension's content scripts (see the list in the content script guide).

+ +

To use the more powerful APIs you need to request permission in your extension's manifest.json.

+ +

You can access the APIs using the browser namespace:

+ +
function logTabs(tabs) {
+  console.log(tabs)
+}
+
+browser.tabs.query({currentWindow: true}, logTabs)
+
+ +
+

Many of the APIs are asynchronous, returning a {{JSxRef("Promise")}}:

+ +
function logCookie(c) {
+  console.log(c)
+}
+
+function logError(e) {
+  console.error(e)
+}
+
+let setCookie = browser.cookies.set(
+  {url: "https://developer.mozilla.org/"}
+);
+setCookie.then(logCookie, logError)
+
+ +
+

Note that this is different from Google Chrome's extension system, which uses the chrome namespace instead of browser, and which uses callbacks instead of promises for asynchronous functions. As a porting aid, the Firefox implementation of WebExtensions APIs supports chrome and callbacks as well as browser and promises. Mozilla has also written a polyfill which enables code that uses browser and promises to work unchanged in Chrome: https://github.com/mozilla/webextension-polyfill.

+ +

Firefox also implements these APIs under the chrome namespace using callbacks. This allows code written for Chrome to run largely unchanged in Firefox for the APIs documented here.

+ +

Microsoft Edge uses the browser namespace, but doesn't yet support promise-based asynchronous APIs. In Edge, for the time being, asynchronous APIs must use callbacks.

+ +

Not all browsers support all the APIs: for the details, see Browser support for JavaScript APIs.

+ +

Tip: Throughout the JavaScript API listings you will find short code examples that illustrate how the API is used. You can exercise these examples, without needing to create a web extension, using the console in the Toolbox. For example, here is the first code example on this page running in the Toolbox console in Firefox Developer Edition:

+ +

Illustration of a snippet of web extension code run from the console in the Toolbox

+ +

JavaScript API listing

+ +

See below for a complete list of JavaScript APIs:

+
+ +
{{LandingPageListSubpages}}
diff --git a/files/fa/mozilla/add-ons/webextensions/api/runtime/index.html b/files/fa/mozilla/add-ons/webextensions/api/runtime/index.html new file mode 100644 index 0000000000..62478e3457 --- /dev/null +++ b/files/fa/mozilla/add-ons/webextensions/api/runtime/index.html @@ -0,0 +1,168 @@ +--- +title: runtime +slug: Mozilla/Add-ons/WebExtensions/API/runtime +tags: + - API + - Add-ons + - Extensions + - Interface + - NeedsTranslation + - Reference + - TopicStub + - WebExtensions + - runtime +translation_of: Mozilla/Add-ons/WebExtensions/API/runtime +--- +
{{AddonSidebar}}
+ +

This module provides information about your extension and the environment it's running in.

+ +

It also provides messaging APIs enabling you to:

+ + + +

Types

+ +
+
{{WebExtAPIRef("runtime.Port")}}
+
Represents one end of a connection between two specific contexts, which can be used to exchange messages.
+
{{WebExtAPIRef("runtime.MessageSender")}}
+
+

Contains information about the sender of a message or connection request.

+
+
{{WebExtAPIRef("runtime.PlatformOs")}}
+
Identifies the browser's operating system.
+
{{WebExtAPIRef("runtime.PlatformArch")}}
+
Identifies the browser's processor architecture.
+
{{WebExtAPIRef("runtime.PlatformInfo")}}
+
Contains information about the platform the browser is running on.
+
{{WebExtAPIRef("runtime.RequestUpdateCheckStatus")}}
+
Result of a call to {{WebExtAPIRef("runtime.requestUpdateCheck()")}}.
+
{{WebExtAPIRef("runtime.OnInstalledReason")}}
+
The reason that the {{WebExtAPIRef("runtime.onInstalled")}} event is being dispatched.
+
{{WebExtAPIRef("runtime.OnRestartRequiredReason")}}
+
The reason that the {{WebExtAPIRef("runtime.onRestartRequired")}} event is being dispatched.
+
+ +

Properties

+ +
+
{{WebExtAPIRef("runtime.lastError")}}
+
This value is set when an asynchronous function has an error condition that it needs to report to its caller.
+
{{WebExtAPIRef("runtime.id")}}
+
The ID of the extension.
+
+ +

Functions

+ +
+
{{WebExtAPIRef("runtime.getBackgroundPage()")}}
+
Retrieves the Window object for the background page running inside the current extension.
+
{{WebExtAPIRef("runtime.openOptionsPage()")}}
+
+

Opens your extension's options page.

+
+
{{WebExtAPIRef("runtime.getManifest()")}}
+
Gets the complete manifest.json file, serialized as an object.
+
{{WebExtAPIRef("runtime.getURL()")}}
+
Given a relative path from the manifest.json to a resource packaged with the extension, returns a fully-qualified URL.
+
{{WebExtAPIRef("runtime.setUninstallURL()")}}
+
Sets a URL to be visited when the extension is uninstalled.
+
{{WebExtAPIRef("runtime.reload()")}}
+
Reloads the extension.
+
{{WebExtAPIRef("runtime.requestUpdateCheck()")}}
+
Checks for updates to this extension.
+
{{WebExtAPIRef("runtime.connect()")}}
+
Establishes a connection from a content script to the main extension process, or from one extension to a different extension.
+
{{WebExtAPIRef("runtime.connectNative()")}}
+
+
Connects the extension to a native application on the user's computer.
+
+
{{WebExtAPIRef("runtime.sendMessage()")}}
+
Sends a single message to event listeners within your extension or a different extension. Similar to {{WebExtAPIRef('runtime.connect')}} but only sends a single message, with an optional response.
+
{{WebExtAPIRef("runtime.sendNativeMessage()")}}
+
Sends a single message from an extension to a native application.
+
{{WebExtAPIRef("runtime.getPlatformInfo()")}}
+
Returns information about the current platform.
+
{{WebExtAPIRef("runtime.getBrowserInfo()")}}
+
Returns information about the browser in which this extension is installed.
+
{{WebExtAPIRef("runtime.getPackageDirectoryEntry()")}}
+
Returns a DirectoryEntry for the package directory.
+
+ +

Events

+ +
+
{{WebExtAPIRef("runtime.onStartup")}}
+
Fired when a profile that has this extension installed first starts up. This event is not fired when an incognito profile is started.
+
{{WebExtAPIRef("runtime.onInstalled")}}
+
Fired when the extension is first installed, when the extension is updated to a new version, and when the browser is updated to a new version.
+
{{WebExtAPIRef("runtime.onSuspend")}}
+
Sent to the event page just before the extension is unloaded. This gives the extension an opportunity to do some cleanup.
+
{{WebExtAPIRef("runtime.onSuspendCanceled")}}
+
Sent after {{WebExtAPIRef("runtime.onSuspend")}} to indicate that the extension won't be unloaded after all.
+
{{WebExtAPIRef("runtime.onUpdateAvailable")}}
+
Fired when an update is available, but isn't installed immediately because the extension is currently running.
+
{{WebExtAPIRef("runtime.onBrowserUpdateAvailable")}} {{deprecated_inline}}
+
Fired when an update for the browser is available, but isn't installed immediately because a browser restart is required.
+
{{WebExtAPIRef("runtime.onConnect")}}
+
Fired when a connection is made with either an extension process or a content script.
+
{{WebExtAPIRef("runtime.onConnectExternal")}}
+
Fired when a connection is made with another extension.
+
{{WebExtAPIRef("runtime.onMessage")}}
+
Fired when a message is sent from either an extension process or a content script.
+
{{WebExtAPIRef("runtime.onMessageExternal")}}
+
Fired when a message is sent from another extension. Cannot be used in a content script.
+
{{WebExtAPIRef("runtime.onRestartRequired")}}
+
Fired when the device needs to be restarted.
+
+ +

Browser compatibility

+ + + +

{{Compat("webextensions.api.runtime")}}

+ +
{{WebExtExamples("h2")}}
+ +
Acknowledgements + +

This API is based on Chromium's chrome.runtime API. This documentation is derived from runtime.json in the Chromium code.

+ +

Microsoft Edge compatibility data is supplied by Microsoft Corporation and is included here under the Creative Commons Attribution 3.0 United States License.

+
+ + diff --git a/files/fa/mozilla/add-ons/webextensions/api/runtime/onmessage/index.html b/files/fa/mozilla/add-ons/webextensions/api/runtime/onmessage/index.html new file mode 100644 index 0000000000..f58f2a5f8c --- /dev/null +++ b/files/fa/mozilla/add-ons/webextensions/api/runtime/onmessage/index.html @@ -0,0 +1,317 @@ +--- +title: runtime.onMessage +slug: Mozilla/Add-ons/WebExtensions/API/runtime/onMessage +translation_of: Mozilla/Add-ons/WebExtensions/API/runtime/onMessage +--- + + +

برخی از موارد مورد استفاده برای مثال:

+ + + +

برای ارسال پیام که توسط onMessage() listener, از {{WebExtAPIRef("runtime.sendMessage()")}} یا (برای ارسال پیام به یک content script) {{WebExtAPIRef("tabs.sendMessage()")}}.

+ +
+

از ایجاد چندین  onMessage() listeners برای همان نوع پیام خودداری کنید, زیرا نظم چندین listeners will fire تضمین نمی شود.

+ +

اگر می خواهید تحویل پیام به یک نقطه پایان خاص را تضمین کنید, از روش مبتنی بر اتصال برای پیام استفاده کنید.

+
+ +

همراه با message خود, به listener منتقل می شود:

+ + + +

شما می توانید با فراخوانی تابع ()sendResponse در listener خود. مثالی را ببینید.

+ +

برای ارسال  response ناهمزمان, دو گزینه وجود دارد:

+ + + +
+

بازگشت یک Promise در حال حاضر ترجیح داده می شود, زیرا sendResponse() از مشخصات W3C حذف می شود.

+ +

کتابخانه محبوب webextension-polyfill قبلا تابع ()sendResponse را از اجزای آن حذف کرده است.

+
+ +
+

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

+
+ +

Syntax

+ +
browser.runtime.onMessage.addListener(listener)
+browser.runtime.onMessage.removeListener(listener)
+browser.runtime.onMessage.hasListener(listener)
+
+ +

رویکردها سه تابع دارند:

+ +
+
addListener(listener)
+
به این رویداد یک listener اضلفه می کند.
+
removeListener(listener)
+
listening به این رویداد را متوقف می کند. یک listener دلیلی است برای حذف listener.
+
hasListener(listener)
+
بررسی می کند که حداقل یک listener برای این رویداد ثبت شده باشد. اگر listening وجود داشت true برمیگرداند, در غیر این صورت false را بر میگرداند.
+
+ +

addListener syntax

+ +

پارامترها

+ +
+
listener
+
+

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

+ +
+
message
+
object. خود پیام است. این یک شیء با قابلیت JSON-ifiable است.
+
sender
+
یک {{WebExtAPIRef('runtime.MessageSender')}} شیء به نمایندگی از فرستنده پیام.
+
sendResponse
+
+

یک تابع برای صدا زدن, حداکثر یک بار, برای ارسال پاسخ به پیام. این تابع یک آرگومان واحد را شامل می شود, که ممکن است هر شیء با قابلیت JSON باشد. این آرگومان به فرستنده پیام ارسال می شود.

+ +

اگر بیش از یک شنونده  onMessage() در همان سند دارید, پس فقط ممکن است یک نفر پاسخی ارسال کند.

+ +

برای ارسال پاسخ همزمان, قبل از بازگشت تابع listener با  sendResponse() تماس بگیرید.

+ +

برای ارسال پاسخ به صورت ناهمزمان:

+ +
    +
  • یا یک رفرنس برای آرگومان ()sendResponse نگه دارید و  مقدار true را برای تابع listener برگردانید. شما می توانید پس از بازگشت تابع listener، با  ()sendResponse تماس بگیرید.
    • +
  • یا یک {{jsxref("Promise")}} را از تابع listener برگردانید و  promise  را در صورت آماده بودن پاسخ حل کنید.  این یک روش ترجیحی است.
    • +
+
+
+ +

تابع  listener می تواند مقدار Boolean یا  {{jsxref("Promise")}} را برگرداند.

+ +
+

مهم: با استفاده از تابع async  با  ()addListener تماس نگیرید:

+ + 
// don't do this
+browser.runtime.onMessage.addListener(
+  async (data, sender) => {
+    if (data.type === 'handle_me') { return 'done'; }
+  }
+);
+
+ +

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

+ +

اگر می خواهید رویکردی ناهمزمان داشته باشید, به جای این کار از یک  Promise استفاده کنید, مانند مثال زیر:

+ + 
browser.runtime.onMessage.addListener(
+  (data, sender) => {
+    if (data.type === 'handle_me') {
+      return Promise.resolve('done');
+    }
+  }
+);
+
+
+
+
+ +

سازگاری مرورگر

+ + + +

{{Compat("webextensions.api.runtime.onMessage()")}}

+ +

Examples

+ +

Simple example

+ +

This content script listens for click events on the web page. If the click was on a link, it messages the background page with the target URL:

+ +
// content-script.js
+
+window.addEventListener("click", notifyExtension);
+
+function notifyExtension(e) {
+  if (e.target.tagName != "A") {
+    return;
+  }
+  browser.runtime.sendMessage({"url": e.target.href});
+}
+
+ +

The background script listens for these messages and displays a notification using the notifications API:

+ +
// background-script.js
+
+browser.runtime.onMessage.addListener(notify);
+
+function notify(message) {
+  browser.notifications.create({
+    "type": "basic",
+    "iconUrl": browser.extension.getURL("link.png"),
+    "title": "You clicked a link!",
+    "message": message.url
+  });
+}
+
+ +

Sending a synchronous response

+ +

This content script sends a message to the background script when the user clicks on the page. It also logs any response sent by the background script:

+ +
// content-script.js
+
+function handleResponse(message) {
+  console.log(`background script sent a response: ${message.response}`);
+}
+
+function handleError(error) {
+  console.log(`Error: ${error}`);
+}
+
+function sendMessage(e) {
+  const sending = browser.runtime.sendMessage({content: "message from the content script"});
+  sending.then(handleResponse, handleError);
+}
+
+window.addEventListener("click", sendMessage);
+ +

Here is a version of the corresponding background script, that sends a response synchronously, from inside in the listener:

+ +
// background-script.js
+
+function handleMessage(request, sender, sendResponse) {
+  console.log(`content script sent a message: ${request.content}`);
+  sendResponse({response: "response from background script"});
+}
+
+browser.runtime.onMessage.addListener(handleMessage);
+ +

And here is another version which uses {{jsxref("Promise.resolve()")}}:

+ +
// background-script.js
+
+function handleMessage(request, sender, sendResponse) {
+  console.log(`content script sent a message: ${request.content}`);
+  return Promise.resolve({response: "response from background script"});
+}
+
+browser.runtime.onMessage.addListener(handleMessage);
+ +

Sending an asynchronous response using sendResponse

+ +

Here is an alternative version of the background script from the previous example. It sends a response asynchronously after the listener has returned. Note return true; in the listener: this tells the browser that you intend to use the sendResponse argument after the listener has returned.

+ +
// background-script.js
+
+function handleMessage(request, sender, sendResponse) {
+  console.log(`content script sent a message: ${request.content}`);
+  setTimeout(() => {
+    sendResponse({response: "async response from background script"});
+  }, 1000);
+  return true;
+}
+
+browser.runtime.onMessage.addListener(handleMessage);
+
+ +

Sending an asynchronous response using a Promise

+ +

This content script gets the first <a> link on the page and sends a message asking if the link's location is bookmarked. It expects to get a Boolean response (true if the location is bookmarked, false otherwise):

+ +
// content-script.js
+
+const firstLink = document.querySelector("a");
+
+function handleResponse(isBookmarked) {
+  if (isBookmarked) {
+    firstLink.classList.add("bookmarked");
+  }
+}
+
+browser.runtime.sendMessage({
+  url: firstLink.href
+}).then(handleResponse);
+ +

Here is the background script. It uses {{WebExtAPIRef("bookmarks.search()")}} to see if the link is bookmarked, which returns a {{jsxref("Promise")}}:

+ +
// background-script.js
+
+function isBookmarked(message, sender, response) {
+  return browser.bookmarks.search({
+    url: message.url
+  }).then(function(results) {
+    return results.length > 0;
+  });
+}
+
+browser.runtime.onMessage.addListener(isBookmarked);
+ +

If the asynchronous handler doesn't return a Promise, you can explicitly construct a promise. This rather contrived example sends a response after a 1-second delay, using Window.setTimeout():

+ +
// background-script.js
+
+function handleMessage(request, sender, sendResponse) {
+  return new Promise(resolve => {
+    setTimeout( () => {
+      resolve({response: "async response from background script"});
+    }, 1000);
+  });
+}
+
+browser.runtime.onMessage.addListener(handleMessage);
+ +

{{WebExtExamples}}

+ +
Acknowledgements + +

This API is based on Chromium's chrome.runtime API. This documentation is derived from runtime.json in the Chromium code.

+ +

Microsoft Edge compatibility data is supplied by Microsoft Corporation and is included here under the Creative Commons Attribution 3.0 United States License.

+
+ + diff --git a/files/fa/mozilla/add-ons/webextensions/index.html b/files/fa/mozilla/add-ons/webextensions/index.html new file mode 100644 index 0000000000..49530e6d87 --- /dev/null +++ b/files/fa/mozilla/add-ons/webextensions/index.html @@ -0,0 +1,97 @@ +--- +title: WebExtensions +slug: Mozilla/Add-ons/WebExtensions +tags: + - افزونه + - افزونه_فایرفاکس + - برنامه_نویسی + - توسعه +translation_of: Mozilla/Add-ons/WebExtensions +--- +
{{AddonSidebar}}
+ +
افزونه ها قادر به بسط و تغییر قابلیت یک مرورگر می باشند. افزونه ها، برای فایرفاکس، با به کارگیری 
+ +
وب-گستر API، که یک سیستم مرورگر-متقابل جهت توسعه افزونه هاست، ساخته می شود. برای یک گسترش بزرگ، سیستم با افزونه API یا  extension API مورد پشتیبانی گوگل و اوپرا و  W3C Draft Community Group سازگار می باشد. افزونه های نوشته شده برای این مرورگرها، اغلب بیشتر مواقع در فایرفاکس یا Microsoft Edge ، تنها با اندکی تغییر، اجرا خواهند شد. همچنین این API دارای سازگاری کامل با multiprocess Firefox است.
+ +
اگر شما ایده ها یا پرسش هایی داشته، یا برای رها شدن از افزونه های وراثتی، جهت به کارگیری وب-افزونه ها، نیازمند کمک باشید،می توانید در dev-addons mailing list  یا #webextensions در IRC به تنیجه برسید.
+ +

 

+ +
+
+

آغاز کار

+ + + +

چگونه

+ + + +

مفاهیم

+ + + +

انتقال

+ + + +

نحوه کار فایرفاکس

+ + +
+ +
+

منابع

+ + + +

JavaScript APIs

+ +
{{ ListSubpages ("/en-US/Add-ons/WebExtensions/API") }}
+ +

Manifest keys

+ +
{{ ListSubpages ("/en-US/Add-ons/WebExtensions/manifest.json") }}
+
+
diff --git a/files/fa/mozilla/add-ons/webextensions/your_first_webextension/index.html b/files/fa/mozilla/add-ons/webextensions/your_first_webextension/index.html new file mode 100644 index 0000000000..b3fcdaaa40 --- /dev/null +++ b/files/fa/mozilla/add-ons/webextensions/your_first_webextension/index.html @@ -0,0 +1,152 @@ +--- +title: اولین extension شما +slug: Mozilla/Add-ons/WebExtensions/Your_first_WebExtension +translation_of: Mozilla/Add-ons/WebExtensions/Your_first_WebExtension +--- +
{{AddonSidebar}}
+ +

در این مقاله ما از ابتدا تا انتهای ساخت یک افزونه برای فایر فاکس را با هم مرور میکنیم. این افزونه فقط یک border قرمز را به هر صفحه ای که از «mozilla.org» یا هر کدام از زیر دامنه های آن فراخوانی شده باشد را اضافه میکند .

+ +

منبع کد این مثال بر روی گیت هاب: https://github.com/mdn/webextensions-examples/tree/master/borderify.

+ +

در ابتدا شما به فایرفاکس نسخه 45 یا بالاتر نیاز دارید.

+ +

نوشتن extension

+ +

یک فولدر جدید ایجاد کنید و به آن بروید. به عنوان مثال ، در خط فرمان / ترمینال خود را اینگونه انجام می دهید:

+ +
mkdir borderify
+cd borderify
+ +

manifest.json

+ +

اکنون یک فایل جدید با نام "manifest.json" را مستقیماً در فولدر "borderify" ایجاد کنید. مطالب زیر را به آن بدهید:

+ +
{
+
+  "manifest_version": 2,
+  "name": "Borderify",
+  "version": "1.0",
+
+  "description": "Adds a red border to all webpages matching mozilla.org.",
+
+  "icons": {
+    "48": "icons/border-48.png"
+  },
+
+  "content_scripts": [
+    {
+      "matches": ["*://*.mozilla.org/*"],
+      "js": ["borderify.js"]
+    }
+  ]
+
+}
+ + + +

جالب ترین نکته اینجاست که content_scripts  به Firefox می گوید یک اسکریپت را در صفحات وب بارگذاری کنید که URL آن با الگوی خاصی مطابقت دارد. در این حالت ، ما از Firefox می خواهیم یک اسکریپت با نام "borderify.js" را در تمام صفحات HTTP یا HTTPS که از "mozilla.org" یا هر یک از زیر دامنه های آن استفاده می شود بارگیری کند.

+ + + +
+

در بعضی مواقع باید یک ID برای extension خود تعیین کنید . اگر نیاز به add-on ID دارید , کلید  برنامه ها را در manifest.json قرار دهید و ویژگی gecko.id آن را تنظیم کنید:

+ +
"applications": {
+  "gecko": {
+    "id": "borderify@example.com"
+  }
+}
+
+ +

icons/border-48.png

+ +

extension باید یک نماد داشته باشد. تا در کنار لیست  extension ها در  Add-ons Manager  نمایش داده شود. manifest.json ما قول داده است كه ما در " icons/border-48.png" نماد داشته باشيم.

+ +

فولدر "icons" را مستقیماً در فولدر "borderify" ایجاد کنید. نمادی را در آنجا با نام "border-48.png" ذخیره کنید. می توانید از نمونه این مورد که از نماد Google Material Design طراحی شده است و تحت شرایط مجوز Creative Commons Attribution-ShareAlike استفاده می شود استفاده کنید.

+ +

اگر می خواهید نماد خود را تهیه کنید ، باید 48x48 پیکسل باشد. شما همچنین می توانید یک نماد پیکسل 96x96 را برای نمایشگرهای با وضوح بالا تهیه کنید ، و اگر این کار را انجام دهید به عنوان 96خاصیت icons object در manifest.json مشخص می شود:

+ +
"icons": {
+  "48": "icons/border-48.png",
+  "96": "icons/border-96.png"
+}
+ +

روش دیگر ، شما می توانید یک فایل SVG را در اینجا تهیه کنید ، و به درستی اندازه گیری می شود. (اگرچه: اگر از SVG استفاده می کنید و نماد شما متن را شامل می شود ، ممکن است بخواهید از ابزار "تبدیل به مسیر" ویرایشگر SVG خود برای صاف کردن متن استفاده کنید ، به طوری که با اندازه / موقعیت ثابت سازگار باشد.

+ + + +

borderify.js

+ +

سرانجام ، فایلی به نام "borderify.js" را مستقیماً در فولدر "borderify" ایجاد کنید. این محتوا را به آن بدهید:

+ +
document.body.style.border = "5px solid red";
+ +

این اسکریپت در صفحات مطابقت با الگوی ارائه شده در content_scriptsکلید manifest.json بارگذاری می شود . درست مانند اسکریپت هایی که توسط خود صفحه بارگذاری شده است ، اسکریپت دسترسی مستقیم به اسناد دارد.

+ + + +

امتحان کردن

+ +

ابتدا بررسی کنید که فایل های مناسب را در فولدرهای مناسب دارید:

+ +
borderify/
+    icons/
+        border-48.png
+    borderify.js
+    manifest.json
+ +

نصب

+ +

 در فایرفاکس : صفحه about:debugging را باز کنید، روی "This Firefox" (در نسخه های جدیدتر فایرفاکس) کلیک کنید، روی "Load Temporary Add-on" کلیک کنید و یکی از فایل ها را از آدرس اصلی extension خود انتخاب کنید

+ +

{{EmbedYouTube("cer9EUKegG4")}}

+ +

extension اکنون نصب شده است و تا زمانی که فایرفاکس را مجدداً راه اندازی کنید ، باقی خواهد ماند.

+ +

روش دیگر ، می توانید با استفاده از ابزار web-ext ، پسوند را از خط فرمان اجرا کنید.

+ +

آزمایش کردن

+ +

اکنون سعی کنید از صفحهای تحت "mozilla.org" بازدید کنید،  و باید border قرمز را در صفحه مشاهده کنید:

+ +

{{EmbedYouTube("rxBQl2Z9IBQ")}}

+ +
+

هر چند آن را در addons.mozilla.org امتحان نکنید! اسکریپت های محتوا در حال حاضر در آن دامنه مسدود شده اند .

+
+ +

کمی آزمایش کنید. اسکریپت محتوا را تغییر دهید تا رنگ حاشیه تغییر کند ، یا کاری دیگر روی محتوای صفحه انجام دهید. اسکریپت محتوا را ذخیره کنید ، سپس فایل های extension  را با کلیک کردن روی دکمه "Reload" در about:debugging بارگیری مجدد کنید. می توانید تغییرات را بلافاصله مشاهده کنید:

+ +

{{EmbedYouTube("NuajE60jfGY")}}

+ + + +

بسته بندی و انتشار

+ +

برای استفاده افراد دیگر از extension شما ، باید آن را بسته بندی کرده و برای امضا به موزیلا ارسال کنید. برای کسب اطلاعات بیشتر در مورد آن ، به  "Publishing your extension" مراجعه کنید.

+ +

بعدی چیست؟

+ +

اکنون شما یک ایده از روند توسعه یک WebExtension برای Firefox دارید ، سعی کنید:

+ + diff --git a/files/fa/mozilla/add-ons/webextensions/your_second_webextension/index.html b/files/fa/mozilla/add-ons/webextensions/your_second_webextension/index.html new file mode 100644 index 0000000000..aff7ba0259 --- /dev/null +++ b/files/fa/mozilla/add-ons/webextensions/your_second_webextension/index.html @@ -0,0 +1,458 @@ +--- +title: اکستنشن دوم شما +slug: Mozilla/Add-ons/WebExtensions/Your_second_WebExtension +translation_of: Mozilla/Add-ons/WebExtensions/Your_second_WebExtension +--- +
+

{{AddonSidebar}}

+ +

اگر شما مقاله اولین اکستنشن خود را خوانده اید، حالا ایده ای از چگونگی نوشتن یک اکستنشن به شما داده می شود. در این مقاله ما اکستنشن کمی پیچیده تری را که در ان از تعدادی از API ها استفاده شده، می نویسیم.

+ +

The extension adds a new button to the Firefox toolbar. When the user clicks the button, we display a popup enabling them to choose an animal. Once they choose an animal, we'll replace the current page's content with a picture of the chosen animal.

+ +

To implement this, we will:

+ + + +

You could visualise the overall structure of the extension like this:

+ +

+ +

It's a simple extension, but shows many of the basic concepts of the WebExtensions API:

+ + + +

You can find complete source code for the extension on GitHub.

+ +

To write this extension, you'll need Firefox 45 or newer.

+ +

Writing the extension

+ +

Create a new directory and navigate to it:

+ +
mkdir beastify
+cd beastify
+ +

manifest.json

+ +

Now create a new file called "manifest.json", and give it the following contents:

+ +
{
+
+  "manifest_version": 2,
+  "name": "Beastify",
+  "version": "1.0",
+
+  "description": "Adds a browser action icon to the toolbar. Click the button to choose a beast. The active tab's body content is then replaced with a picture of the chosen beast. See https://developer.mozilla.org/en-US/Add-ons/WebExtensions/Examples#beastify",
+  "homepage_url": "https://github.com/mdn/webextensions-examples/tree/master/beastify",
+  "icons": {
+    "48": "icons/beasts-48.png"
+  },
+
+  "permissions": [
+    "activeTab"
+  ],
+
+  "browser_action": {
+    "default_icon": "icons/beasts-32.png",
+    "default_title": "Beastify",
+    "default_popup": "popup/choose_beast.html"
+  },
+
+  "web_accessible_resources": [
+    "beasts/frog.jpg",
+    "beasts/turtle.jpg",
+    "beasts/snake.jpg"
+  ]
+
+}
+
+ + + +

Note that all paths given are relative to manifest.json itself.

+ +

The icon

+ +

The extension should have an icon. This will be shown next to the extension's listing in the Add-ons Manager (you can open this by visiting the URL "about:addons"). Our manifest.json promised that we would have an icon for the toolbar at "icons/beasts-48.png".

+ +

Create the "icons" directory and save an icon there named "beasts-48.png".  You could use the one from our example, which is taken from the Aha-Soft’s Free Retina iconset, and used under the terms of its license.

+ +

If you choose to supply your own icon, It should be 48x48 pixels. You could also supply a 96x96 pixel icon, for high-resolution displays, and if you do this it will be specified as the 96 property of the icons object in manifest.json:

+ +
"icons": {
+  "48": "icons/beasts-48.png",
+  "96": "icons/beasts-96.png"
+}
+ +

The toolbar button

+ +

The toolbar button also needs an icon, and our manifest.json promised that we would have an icon for the toolbar at "icons/beasts-32.png".

+ +

Save an icon named "beasts-32.png" in the "icons" directory. You could use the one from our example, which is taken from the IconBeast Lite icon set and used under the terms of its license.

+ +

If you don't supply a popup, then a click event is dispatched to your extension when the user clicks the button. If you do supply a popup, the click event is not dispatched, but instead, the popup is opened. We want a popup, so let's create that next.

+ +

The popup

+ +

The function of the popup is to enable the user to choose one of three beasts.

+ +

Create a new directory called "popup" under the extension root. This is where we'll keep the code for the popup. The popup will consist of three files:

+ + + +
mkdir popup
+cd popup
+touch choose_beast.html choose_beast.css choose_beast.js
+
+ +

choose_beast.html

+ +

The HTML file looks like this:

+ +
<!DOCTYPE html>
+
+<html>
+  <head>
+    <meta charset="utf-8">
+    <link rel="stylesheet" href="choose_beast.css"/>
+  </head>
+
+<body>
+  <div id="popup-content">
+    <div class="button beast">Frog</div>
+    <div class="button beast">Turtle</div>
+    <div class="button beast">Snake</div>
+    <div class="button reset">Reset</div>
+  </div>
+  <div id="error-content" class="hidden">
+    <p>Can't beastify this web page.</p><p>Try a different page.</p>
+  </div>
+  <script src="choose_beast.js"></script>
+</body>
+
+</html>
+
+ +

We have a <div> element with an ID of "popup-content" that contains an element for each animal choice. We have another <div> with an ID of "error-content" and a class "hidden". We'll use that in case there's a problem initializing the popup.

+ +

Note that we include the CSS and JS files from this file, just like a web page.

+ +

choose_beast.css

+ +

The CSS fixes the size of the popup, ensures that the three choices fill the space, and gives them some basic styling. It also hides elements with class="hidden": this means that our "error-content" <div> will be hidden by default.

+ +
html, body {
+  width: 100px;
+}
+
+.hidden {
+  display: none;
+}
+
+.button {
+  margin: 3% auto;
+  padding: 4px;
+  text-align: center;
+  font-size: 1.5em;
+  cursor: pointer;
+}
+
+.beast:hover {
+  background-color: #CFF2F2;
+}
+
+.beast {
+  background-color: #E5F2F2;
+}
+
+.reset {
+  background-color: #FBFBC9;
+}
+
+.reset:hover {
+  background-color: #EAEA9D;
+}
+
+
+ +

choose_beast.js

+ +

Here's the JavaScript for the popup:

+ +
/**
+ * CSS to hide everything on the page,
+ * except for elements that have the "beastify-image" class.
+ */
+const hidePage = `body > :not(.beastify-image) {
+                    display: none;
+                  }`;
+
+/**
+ * Listen for clicks on the buttons, and send the appropriate message to
+ * the content script in the page.
+ */
+function listenForClicks() {
+  document.addEventListener("click", (e) => {
+
+    /**
+     * Given the name of a beast, get the URL to the corresponding image.
+     */
+    function beastNameToURL(beastName) {
+      switch (beastName) {
+        case "Frog":
+          return browser.extension.getURL("beasts/frog.jpg");
+        case "Snake":
+          return browser.extension.getURL("beasts/snake.jpg");
+        case "Turtle":
+          return browser.extension.getURL("beasts/turtle.jpg");
+      }
+    }
+
+    /**
+     * Insert the page-hiding CSS into the active tab,
+     * then get the beast URL and
+     * send a "beastify" message to the content script in the active tab.
+     */
+    function beastify(tabs) {
+      browser.tabs.insertCSS({code: hidePage}).then(() => {
+        let url = beastNameToURL(e.target.textContent);
+        browser.tabs.sendMessage(tabs[0].id, {
+          command: "beastify",
+          beastURL: url
+        });
+      });
+    }
+
+    /**
+     * Remove the page-hiding CSS from the active tab,
+     * send a "reset" message to the content script in the active tab.
+     */
+    function reset(tabs) {
+      browser.tabs.removeCSS({code: hidePage}).then(() => {
+        browser.tabs.sendMessage(tabs[0].id, {
+          command: "reset",
+        });
+      });
+    }
+
+    /**
+     * Just log the error to the console.
+     */
+    function reportError(error) {
+      console.error(`Could not beastify: ${error}`);
+    }
+
+    /**
+     * Get the active tab,
+     * then call "beastify()" or "reset()" as appropriate.
+     */
+    if (e.target.classList.contains("beast")) {
+      browser.tabs.query({active: true, currentWindow: true})
+        .then(beastify)
+        .catch(reportError);
+    }
+    else if (e.target.classList.contains("reset")) {
+      browser.tabs.query({active: true, currentWindow: true})
+        .then(reset)
+        .catch(reportError);
+    }
+  });
+}
+
+/**
+ * There was an error executing the script.
+ * Display the popup's error message, and hide the normal UI.
+ */
+function reportExecuteScriptError(error) {
+  document.querySelector("#popup-content").classList.add("hidden");
+  document.querySelector("#error-content").classList.remove("hidden");
+  console.error(`Failed to execute beastify content script: ${error.message}`);
+}
+
+/**
+ * When the popup loads, inject a content script into the active tab,
+ * and add a click handler.
+ * If we couldn't inject the script, handle the error.
+ */
+browser.tabs.executeScript({file: "/content_scripts/beastify.js"})
+.then(listenForClicks)
+.catch(reportExecuteScriptError);
+
+
+ +

The place to start here is line 96. The popup script executes a content script in the active tab as soon as the popup is loaded, using the browser.tabs.executeScript() API. If executing the content script is successful, then the content script will stay loaded in the page until the tab is closed or the user navigates to a different page.

+ +

A common reason the browser.tabs.executeScript() call might fail is that you can't execute content scripts in all pages. For example, you can't execute them in privileged browser pages like about:debugging, and you can't execute them on pages in the addons.mozilla.org domain. If it does fail, reportExecuteScriptError() will hide the "popup-content" <div>, show the "error-content" <div>, and log an error to the console.

+ +

If executing the content script is successful, we call listenForClicks(). This listens for clicks on the popup.

+ + + +

The beastify() function does three things:

+ + + +

The reset() function essentially undoes a beastify:

+ + + +

The content script

+ +

Create a new directory, under the extension root, called "content_scripts" and create a new file in it called "beastify.js", with the following contents:

+ +
(function() {
+  /**
+   * Check and set a global guard variable.
+   * If this content script is injected into the same page again,
+   * it will do nothing next time.
+   */
+  if (window.hasRun) {
+    return;
+  }
+  window.hasRun = true;
+
+  /**
+   * Given a URL to a beast image, remove all existing beasts, then
+   * create and style an IMG node pointing to
+   * that image, then insert the node into the document.
+   */
+  function insertBeast(beastURL) {
+    removeExistingBeasts();
+    let beastImage = document.createElement("img");
+    beastImage.setAttribute("src", beastURL);
+    beastImage.style.height = "100vh";
+    beastImage.className = "beastify-image";
+    document.body.appendChild(beastImage);
+  }
+
+  /**
+   * Remove every beast from the page.
+   */
+  function removeExistingBeasts() {
+    let existingBeasts = document.querySelectorAll(".beastify-image");
+    for (let beast of existingBeasts) {
+      beast.remove();
+    }
+  }
+
+  /**
+   * Listen for messages from the background script.
+   * Call "beastify()" or "reset()".
+  */
+  browser.runtime.onMessage.addListener((message) => {
+    if (message.command === "beastify") {
+      insertBeast(message.beastURL);
+    } else if (message.command === "reset") {
+      removeExistingBeasts();
+    }
+  });
+
+})();
+
+ +

The first thing the content script does is to check for a global variable window.hasRun: if it's set the script returns early, otherwise it sets window.hasRun and continues. The reason we do this is that every time the user opens the popup, the popup executes a content script in the active tab, so we could have multiple instances of the script running in a single tab. If this happens, we need to make sure that only the first instance is actually going to do anything.

+ +

After that, the place to start is line 40, where the content script listens for messages from the popup, using the browser.runtime.onMessage API. We saw above that the popup script can send two different sorts of messages: "beastify" and "reset".

+ + + +

The beasts

+ +

Finally, we need to include the images of the beasts.

+ +

Create a new directory called "beasts", and add the three images in that directory, with the appropriate names. You can get the images from the GitHub repository, or from here:

+ +

+ +

Testing it out

+ +

First, double check that you have the right files in the right places:

+ +
beastify/
+
+    beasts/
+        frog.jpg
+        snake.jpg
+        turtle.jpg
+
+    content_scripts/
+        beastify.js
+
+    icons/
+        beasts-32.png
+        beasts-48.png
+
+    popup/
+        choose_beast.css
+        choose_beast.html
+        choose_beast.js
+
+    manifest.json
+ +

Starting in Firefox 45, you can install extensions temporarily from disk.

+ +

Open "about:debugging" in Firefox, click "Load Temporary Add-on", and select your manifest.json file. You should then see the extension's icon appear in the Firefox toolbar:

+ +

{{EmbedYouTube("sAM78GU4P34")}}

+ +

Open a web page, then click the icon, select a beast, and see the web page change:

+ +

{{EmbedYouTube("YMQXyAQSiE8")}}

+ +

Developing from the command line

+ +

You can automate the temporary installation step by using the web-ext tool. Try this:

+ +
cd beastify
+web-ext run
+
-- cgit v1.2.3-54-g00ecf