JavaScript API

WebExtensions 的 JavaScript API 可以在擴充套件的背景指令碼以及隨擴充套件捆綁的任何其他文件中使用，包括瀏覽器操作或頁面操作彈出視窗、側邊欄、選項頁或新標籤頁。其中一些 API 也可以由擴充套件的內容指令碼訪問。（請參閱內容指令碼指南中的列表。）

要使用更強大的 API，您需要在擴充套件的 manifest.json 中請求許可權。

您可以使用 browser 名稱空間來訪問 API

function logTabs(tabs) {
  console.log(tabs);
}

browser.tabs.query({ currentWindow: true }, logTabs);

許多 API 是非同步的，返回一個 Promise

function logCookie(c) {
  console.log(c);
}

function logError(e) {
  console.error(e);
}

let setCookie = browser.cookies.set({ url: "https://mdn.club.tw/" });
setCookie.then(logCookie, logError);

瀏覽器 API 差異

請注意，這與 Google Chrome 的擴充套件系統不同，Chrome 使用 chrome 名稱空間而不是 browser，並且在 Manifest V2 中，它使用回撥而不是 Promise 來處理非同步函式。作為移植輔助，Firefox 對 WebExtensions API 的實現同時支援 chrome 和回撥，以及 browser 和 Promise。Mozilla 還編寫了一個 polyfill，使使用 browser 和 Promise 的程式碼在 Chrome 中也能不變地工作：https://github.com/mozilla/webextension-polyfill。

Firefox 還在 chrome 名稱空間下使用回撥來實現這些 API。這使得為 Chrome 編寫的程式碼在 Firefox 中對於此處記錄的 API 來說，幾乎可以不變地執行。

並非所有瀏覽器都支援所有 API：有關詳細資訊，請參閱 JavaScript API 的瀏覽器支援和 Chrome 不相容性。

示例

在整個 JavaScript API 列表中，簡短的程式碼示例說明了 API 的使用方法。您可以使用 Toolbox 中的控制檯來試驗大多數這些示例。但是，您需要 Toolbox 在 Web 擴充套件的上下文中執行。為此，請開啟 about:debugging，然後選擇 This Firefox，點選已安裝或臨時擴充套件旁邊的 Inspect，然後開啟 Console。然後，您可以將示例程式碼貼上到控制檯中並執行。

例如，這是在 Firefox Developer Edition 的 Toolbox 控制檯中執行的此頁面上的第一個程式碼示例

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

JavaScript API 列表

有關 JavaScript API 的完整列表，請參閱下文

action: 讀取和修改由 action manifest 鍵定義的瀏覽器工具欄按鈕的屬性，並監聽其點選事件。
alarms: 安排程式碼在未來的特定時間執行。這類似於 Window.setTimeout() 和 Window.setInterval()，不同之處在於這些函式不適用於按需載入的背景頁面。
bookmarks: WebExtensions 的 bookmarks API 允許擴充套件與瀏覽器的書籤系統進行互動和操作。您可以使用它來新增書籤、檢索現有書籤，以及編輯、刪除和組織書籤。
browserAction: 讀取和修改由 browser_action manifest 鍵定義的瀏覽器工具欄按鈕的屬性，並監聽其點選事件。
browserSettings: 允許擴充套件修改某些全域性瀏覽器設定。此 API 的每個屬性都是一個 types.BrowserSetting 物件，可以用來修改特定的設定。
browsingData: 允許擴充套件清除使用者瀏覽時積累的資料。
captivePortal: 確定使用者連線的代理門戶狀態。代理門戶是使用者首次連線到 Wi-Fi 網路時顯示的網頁。使用者在代理門戶網頁上提供資訊或進行操作以獲得更廣泛的網路訪問許可權，例如接受條款和條件或進行付款。
clipboard: WebExtension 的 clipboard API（與標準 Clipboard API 不同）允許擴充套件將專案複製到系統剪貼簿。目前，WebExtension clipboard API 只支援複製影像，但未來打算支援複製文字和 HTML。
commands: 監聽使用者執行透過 commands manifest.json 鍵註冊的命令。
contentScripts: 使用此 API 註冊內容指令碼。註冊內容指令碼會指示瀏覽器將給定的內容指令碼插入與指定 URL 模式匹配的頁面中。
contextualIdentities: 處理上下文身份：列出、建立、移除和更新上下文身份。
cookies: 允許擴充套件獲取、設定和刪除 cookie，並接收 cookie 更改的通知。
declarativeNetRequest: 此 API 允許擴充套件指定描述網路請求應如何處理的條件和操作。這些宣告式規則使瀏覽器無需通知擴充套件有關單個網路請求即可評估和修改網路請求。
devtools: 允許擴充套件與瀏覽器的開發者工具進行互動。您可以使用此 API 來建立開發者工具頁面，與被檢查的視窗進行互動，並檢查頁面的網路使用情況。
dns: 允許擴充套件解析域名。
dom: 訪問特殊的僅限擴充套件的 DOM 功能。
downloads: 允許擴充套件與瀏覽器的下載管理器進行互動。您可以使用此 API 模組來下載檔案、取消、暫停、恢復下載，並在檔案管理器中顯示已下載的檔案。
events: 由分派事件的 API 使用的通用型別。
extension: 與您的擴充套件相關的實用程式。獲取擴充套件包中資源的 URL。獲取擴充套件頁面 Window 物件。獲取各種設定的值。
extensionTypes: 其他 WebExtension API 中使用的一些通用型別。
find: 在網頁中查詢文字並高亮顯示匹配項。
history: 使用 history API 與瀏覽器歷史記錄進行互動。
i18n: 用於國際化擴充套件的函式。您可以使用這些 API 從隨擴充套件一起打包的 locale 檔案中獲取本地化字串，找出瀏覽器的當前語言，並找出其 Accept-Language 標頭的值。
identity: 使用 identity API 獲取 OAuth2 授權碼或訪問令牌，擴充套件可以使用它來從支援 OAuth2 訪問的服務（如 Google 或 Facebook）獲取使用者資料。
idle: 瞭解使用者系統何時空閒、鎖定或啟用。
management: 獲取已安裝的附加元件資訊。
menus: 將專案新增到瀏覽器的菜單系統中。
notifications: 使用底層的作業系統通知機制向用戶顯示通知。由於此 API 使用作業系統的通知機制，因此通知的外觀和行為可能因作業系統和使用者設定而異。
omnibox: 允許擴充套件在使用者在瀏覽器位址列中輸入內容時實現自定義行為。
pageAction: 讀取和修改由 page_action manifest 鍵定義的位址列按鈕的屬性，並監聽其點選事件。
permissions: 允許擴充套件在安裝後執行時請求額外的許可權。
pkcs11: pkcs11 API 允許擴充套件列舉 PKCS #11 安全模組，並使它們作為金鑰和證書的來源可供瀏覽器訪問。
privacy: 訪問和修改各種與隱私相關的瀏覽器設定。
proxy: 使用 proxy API 來代理 Web 請求。您可以使用 proxy.onRequest 事件監聽器來攔截 Web 請求，並返回一個物件來描述如何以及是否代理它們。
runtime: 此模組提供有關您的擴充套件及其執行環境的資訊。
scripting: 將 JavaScript 和 CSS 插入網站。此 API 提供兩種插入內容的方法
search: 使用 search API 來檢索已安裝的搜尋引擎並執行搜尋。
sessions: 使用 sessions API 來列出和恢復瀏覽器執行期間已關閉的標籤頁和視窗。
sidebarAction: 獲取和設定擴充套件側邊欄的屬性。
storage: 允許擴充套件儲存和檢索資料，並監聽已儲存項的更改。
tabGroups: 此 API 允許擴充套件修改和重新排列標籤頁組。
tabs: 與瀏覽器的標籤頁系統進行互動。
theme: 允許瀏覽器擴充套件獲取瀏覽器主題的詳細資訊並更新主題。
topSites: 使用 topSites API 獲取一個包含使用者經常訪問頁面的陣列。
types: 定義 BrowserSetting 型別，該型別用於表示瀏覽器設定。
userScripts: 使用此 API 註冊使用者指令碼，這些使用者指令碼是用於操作網頁或提供新功能的第三方指令碼。註冊使用者指令碼會指示瀏覽器將指令碼附加到在註冊期間指定的 URL 模式匹配的頁面。
userScripts (Legacy): 警告：這是舊版 userScripts API 的文件。它在 Firefox 中可用於 Manifest V2。有關在 Manifest V3 中與使用者指令碼配合使用的功能，請參閱新的 userScripts API。
webNavigation: 為導航的各個階段新增事件監聽器。導航由瀏覽器中的一個框架從一個 URL 過渡到另一個 URL 組成，通常（但並非總是）響應使用者操作，例如點選連結或在位址列中輸入 URL。
webRequest: 為 HTTP 請求的各個階段新增事件監聽器，包括 ws:// 和 wss:// 上的 websocket 請求。事件監聽器會收到有關請求的詳細資訊，並可以修改或取消請求。
windows: 與瀏覽器視窗進行互動。您可以使用此 API 獲取有關開啟視窗的資訊，並開啟、修改和關閉視窗。您還可以監聽視窗開啟、關閉和啟用事件。

幫助改進 MDN

瞭解如何貢獻

此頁面最後修改於 2025 年 7 月 17 日，由 MDN 貢獻者修改。

在 GitHub 上檢視此頁面 • 報告此內容的問題