你的第一個 WebExtension

在這篇文章中,我們將鉅細靡遺講解製作 Firefox 的 WebExtensionIn。這支附加元件會在 "mozilla.org" 網域底下的任何網頁,增加紅色外框。

這個範例的原始碼也放在 GitHub 喔:https://github.com/mdn/webextensions-examples/tree/master/borderify

首先勒,你需要 Firefox 45.0 或以上的版本。

撰寫 WebExtension

新增一個資料夾,然後進到裡面去:

mkdir borderify
cd borderify

manifest.json

現在新增一個稱作 "manifest.json" 的檔案,直接放在 "borderify" 目錄底下即可,然後把下方個程式碼塞進去:

{

  "manifest_version": 2,
  "name": "Borderify",
  "version": "1.0",

  "description": "Adds a solid red border to all webpages matching mozilla.org.",

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

  "content_scripts": [
    {
      "matches": ["*://*.mozilla.org/*"],
      "js": ["borderify.js"]
    }
  ]

}
  • 最前面的三個 key:manifest_versionnameversion,是附加元件的基本詮釋資料(metadata)且是強制要包含的。
  • description 是可選、但建議要有的:它會在附加元件的管理員顯示出來。
  • icons 也是可選、但建議要有的:它允許附加元件指定圖示、也會在附加元件的管理員顯示。

這裡最有趣的 key 是 content_scripts:它告訴 Firefox 說:匹配特定型態的 URL 會載入網頁的腳本。在這裡,我們告訴 Firefox 說:所有由 "mozilla.org" 或其子域名服務的 HTTP 或 HTTPS 頁面,要載入 "borderify.js"。

如果你用 Firefox 48 以前的版本,你還需要一個稱為 applications 的額外 key:

"applications": {
  "gecko": {
    "id": "borderify@example.com",
    "strict_min_version": "42.0",
    "strict_max_version": "50.*",
    "update_url": "https://example.com/updates.json"
  }
}

icons/border-48.png

附加元件要有一個圖標。它會在附加元件管理員的附加元件清單旁邊列出來。我們的 manifest.json 說好了,在 "icons/border-48.png" 那邊會有個圖標。

在 "borderify" 目錄下直接建立 "icons" 目錄。在那邊存一個稱作 "border-48.png" 的圖標檔。你可以用範例的這張圖標,它是從 Google Material Design 圖標集抓下來的,並使用創用 CC:姓名標示-相同方式分享授權。

如果你要用自己的圖標,它應該是 48x48 像素。你也可以針對高解析度提供 96x96 像素的圖標,這樣的話它在 manifest.json 會被指定為 icons 物件內的 96 property:

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

要不然,你也能提供 SVG 檔,它就會正確地縮放。

borderify.js

最後,新增一個檔案叫作 "borderify.js" ,直接放在 "borderify" 目錄底下即可,然後一樣把下方個 code 塞進去:

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

這段 code 會被載入符合,我們在 manifest.json 裡 content_scripts 中定義的 pattern,就會被載入到頁面中,這段 code 就可以存取這份 document,就像我們直接讓頁面自己載入 script 一樣。 

測試看看

首先,仔細檢查這些檔案是否在正確的位置:

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

在 Firefox 打開 about:debugging,點選 Load Temporary Add-on 然後選擇你的 manifest.json 檔案:

現在這個附加元件就要安裝起來,但它要在你重新啟動 Firefox 後才會開始。

現在去看一下 mozilla.org 還有它下面的所有網頁。你應該會看到有個紅色外框圍繞著網頁。

再做點小實驗吧。改一下腳本讓外框顏色改變,或是做其他更動。接著存檔,並按下 about:debugging 的 Reload 鍵重啟附加元件。現在你能看到更動了:

打包並發送

想讓別人用你的附加元件,就要把元件遞交給 Mozilla for signing。想獲得更多資訊,請參見 發布你的 WebExtension

接下來咧?

現在你針對 Firefox 的 WebExtension 開發有點子的話,來看看:

文件標籤與貢獻者

 此頁面的貢獻者: iigmir, ALiangLiang
 最近更新: iigmir,