範例:使用內容指令碼的圖片插入器

此範例使用 JavaScript 程式碼將影像插入 stars.jpeg 目前網頁頂端的元素內 <body> 。 擴充功能的快顯視窗包含標題和標示為 [插入圖片] 的 HTML 按鈕。 當您按一下 [插入圖片 ] 按鈕時,擴充功能的 JavaScript 程式碼會從擴充功能圖示的快顯視窗傳送訊息,並動態插入在瀏覽器索引標籤中執行的 JavaScript。

此示例演示以下擴充功能:

  • 將 JavaScript 程式庫插入擴充功能。
  • 將擴充功能資產公開至瀏覽器索引標籤。
  • 在現有瀏覽器索引標籤中包含內容網頁。
  • 讓內容網頁接聽來自快顯視窗的訊息並做出回應。

範例預覽

您將使用瀏覽器的 [ 管理擴充功能 ] 索引標籤安裝擴充功能範例,按一下 [ 擴充功能 ]  ([擴充功能] 圖示) 按鈕以顯示已安裝的擴充功能清單,然後按一下此擴充功能範例:

按一下擴充功能的圖示以開啟擴充功能

擴充功能會在彈出視窗中顯示小型 HTML 網頁,其中包含標題、[ 插入圖片] 按鈕,以及指示:

 選取 [擴充功能] 圖示後的popup.html 顯示

當您按一下 [插入圖片] 按鈕時,JavaScript 程式碼會暫時插入 stars.jpeg 目前網頁的頂端,將網頁內容下推到影像下方。 插入的內容會將影像元素設定為在目前網頁頂端顯示靜態影像 stars.jpeg :

瀏覽器中顯示的影像

當您按一下影像時,插入的 JavaScript 會從 DOM 樹狀結構和網頁中移除影像。

取得、安裝及執行範例,如下所示。

複製 MicrosoftEdge-Extensions 存放庫

您可以使用各種工具來複製 GitHub 存放庫。 您可以下載選取的目錄,或複製整個存放庫。

將 MicrosoftEdge-Extensions 存放庫複製到本機磁碟機,然後切換至工作分支,如下所示。

  1. 在命令提示字元中,輸入 git 以檢查是否已安裝 git。

  2. 如果尚未完成, 請下載 git 並安裝它。

  3. 如果尚未完成,請在安裝 git 的位置啟動命令提示字元。

  4. 變更至您要複製 MicrosoftEdge-Extensions 存放庫的目錄。 例如:

    cd C:/Users/localAccount/GitHub/
    
  5. 在 Microsoft Edge 中,移至 MicrosoftEdge-Extensions 存放庫。

  6. 按一下綠色程式碼按鈕右側的向下箭頭,然後在使用 Web URL 複製區段中,按一下旁邊的https://github.com/microsoft/MicrosoftEdge-Extensions.git將 URL 複製到剪貼簿按鈕。

  7. 在命令提示字元視窗中,輸入命令:

    git clone https://github.com/microsoft/MicrosoftEdge-Extensions.git
    

    目錄會在 /MicrosoftEdge-Extensions/ 您指定的目錄內新增。

建立運作中的分支,並切換至該分支

  1. 檢查目錄清單:

    ls
    

    /MicrosoftEdge-Extensions/目錄隨即列出。

  2. 切換到新的目錄:

    cd MicrosoftEdge-Extensions
    
  3. 建立工作分支:

    git branch test
    
  4. 切換至工作分支:

    git switch test
    

    退貨: Switched to branch 'test'

您現在可以隨意修改工作分支中的程式碼,而不需要變更存放庫「主要」分支中的程式碼。 稍後您可能會想切換回「主要」分支,或根據「主要」分支建立不同的分支。

在本機安裝範例 (側載)

您將不是從 Microsoft Edge 附加元件 網站安裝範例,而是在本機安裝範例,以便修改並快速測試變更。 在本機安裝有時稱為 側載 延伸模組。

  1. 在 Microsoft Edge 中,按一下網址列旁的 [ 擴充功能 ] ([ 擴充功能] 圖示) 按鈕 (如果有顯示此圖示)。 或者,選取 [設定及其他] ([設定及其他] 圖示) > [擴充功能] 圖示 [擴充功能]。 [ 擴充功能] 快顯視窗隨即開啟:

    未安裝任何擴充功能時,會彈出 [擴充功能]

  2. 按一下 [管理擴充功能]。 擴充 功能 管理頁面會在新索引標籤中開啟:

    開啟開發人員模式

  3. 開啟 開發人員模式 切換。

  4. 第一次安裝範例擴充功能時,按一下 [載入解壓縮] ([載入解壓縮] 圖示) 按鈕。 [ 選取擴充功能目錄 ] 對話方塊隨即開啟。

  5. 選取包含擴充功能來源檔案的目錄,例如 manifest.json。

    範例路徑:

    C:\Users\localAccount\GitHub\MicrosoftEdge-Extensions\Extension-samples\picture-inserter-content-script

  6. 按一下 [選取資料夾 ] 按鈕。

    [ 選取擴充功能目錄 ] 對話方塊隨即關閉。

    擴充功能會安裝在瀏覽器中,類似於從 Microsoft Edge 附加元件網站安裝的擴充功能:

    [已安裝的擴充功能] 頁面,顯示側載的擴充功能

執行範例

  1. 在新視窗或索引標籤中移至網頁,例如 TODO 應用程式。索引標籤不得為空白,且不得是 [管理擴充功能] 頁面,因為此範例會將內容插入目前網頁。

  2. 重新整理網頁。 重新載入擴充功能後,有時需要這樣做。

  3. 在 Microsoft Edge 網址列右側,如果顯示此圖示,請按一下 [ 擴充功能] ([ 擴充功能] 圖示) 按鈕。 或者,選取 [ 設定及其他] ([ 設定及其他] 圖示) >擴充功能。

    [ 擴充功能] 快顯視窗隨即開啟:

    按一下擴充功能的圖示以開啟擴充功能

  4. 使用 內容指令碼) 按一下 (圖片插入器 擴充功能的圖示或名稱。

    擴充功能隨即開啟,且擴充功能的圖示會新增在網址列旁邊,以及 [ 擴充功能 ]  ([擴充功能] 圖示) 圖示旁邊。

    隨即會開啟一個快顯視窗,其中包含一個含有標題、[ 插入圖片] 按鈕和指示的小型 HTML 網頁:

     按一下擴充功能圖示後的popup.html

  5. 按一下 [插入圖片 ] 按鈕。 stars.jpeg 會插入目前索引標籤中的目前網頁頂端,將網頁內容往下推到影像下方:

    瀏覽器中顯示的影像

  6. 按一下 stars.jpeg 網頁頂端的影像。 該影像元素會從 DOM 樹狀結構和網頁中移除,而目前的網頁會還原,並將其內容移回索引標籤的頂端。

擴充功能會從擴充功能圖示的快顯視窗傳送訊息,並在瀏覽器索引標籤中動態插入做為執行內容的 JavaScript。插入的內容會將影像元素設定為顯示 stars.jpeg 在目前網頁的頂端,然後在您按一下影像時移除影像。

另請參閱:

研究樣本

在下列章節中,您將研究樣本。 之後,若要開發您自己的 Microsoft Edge 擴充功能,您可以複製和修改範例的目錄,並安裝和測試產生的擴充功能。

Files and directories

此範例具有下列目錄結構和檔案。

範例的路徑範例:

C:\Users\localAccount\GitHub\MicrosoftEdge-Extensions\Extension-samples\picture-inserter-content-script

目錄和目錄中的 /picture-inserter-content-script/ 檔案:

/content-scripts/
   content.js
/icons/
   extension-icon16x16.png
   extension-icon32x32.png
   extension-icon48x48.png
   extension-icon128x128.png
/images/
   stars.jpeg
/popup/
   popup.html
   popup.js
manifest.json
  • 目錄包含 /content-scripts/content.js,這是插入目前網頁的指令碼。
  • /icons/該目錄包含用來表示瀏覽器位址列附近、擴充功能快顯視窗和 [擴充功能管理] 頁面中的檔案版本.png。
  • 目錄包含 /images/stars.jpeg,會顯示在擴充功能的快顯視窗中。
  • 目錄包含 /popup/ 下列檔案:
    • popup.html 定義擴充功能初始快顯網頁的內容, (標題、按鈕和) 指示。
    • popup.js 針對初始快顯視窗,網頁會傳送訊息至索引標籤頁面上執行的內容指令碼 (content.js) ,指定要顯示的影像檔案。
  • manifest.json 包含關於擴充功能的基本資訊。

更新網頁以在頂端插入影像 (stars.jpeg) 策略

此範例包含插入目前瀏覽器索引標籤中載入之網頁的內容指令碼。

  1. 當您執行擴充功能範例時,初始快顯 HTML 頁面會顯示 (popup.html) ,顯示標題、指示和 [插入圖片 ] 按鈕。

  2. 當您按一下 [插入圖片] 按鈕時,初始快顯頁面的 JavaScript (popup.js) 會傳送訊息至在索引標籤頁面上執行的內容指令碼 (content.js) 。 此訊息會指定要顯示的影像檔。

  3. 在索引標籤頁面上執行的內容指令碼 (content.js) 會收到訊息,並顯示指定的影像檔 (stars.jpeg) 。

最初快顯的網頁 (popup.html)

/popup/popup.html 會在資訊清單檔案中指定為要在擴充功能初始快顯視窗中顯示的網頁。 資訊清單檔案包含索引鍵欄位 "default_popup": "popup/popup.html"。 此範例的 popup.html 檔案是一個小型網頁,包含標題、[ 插入圖片] 按鈕和指示。

popup.html:

<!DOCTYPE html>
<html>
    <head>
        <meta charset="utf-8" />
        <style>
            body {
                width: 500px;
            }
            button {
                background-color: #336dab;
                border: none;
                color: white;
                padding: 15px 32px;
                text-align: center;
                font-size: 16px;
            }
        </style>
    </head>
    <body>
        <h1>Picture inserter using a content script</h1>
        <button id="sendmessageid">Insert picture</button>
        <script src="popup.js"></script>
        <p>Click the displayed image to remove it from the webpage.</p>
    </body>
</html>

JavaScript (popup.js 用於初始快顯頁面的) ,用於傳送訊息至插入的 JavaScript

/popup/popup.js 傳送訊息至暫時插入瀏覽器索引標籤的內容指令碼 (content.js) 。為此, popup.js 請將事件新增至 onclick 快顯網頁的 插入圖片 按鈕,其識別碼 sendmessageid為:

popup.js (部分) :

const sendMessageId = document.getElementById("sendmessageid");
if (sendMessageId) {
    sendMessageId.onclick = function() {
        ...
    };
}

在 中 popup.js, chrome.tabs.query 尋找目前的瀏覽器索引標籤,然後 chrome.tabs.sendMessage 傳送訊息至該索引標籤。範例會傳入目前索引標籤的識別碼。 訊息必須包含將要顯示之影像的 URL。

您必須傳送唯一 ID 才能指派給插入的影像,以便稍後再次尋找影像元素並將其刪除。 若要傳送唯一 ID 以指派給插入的影像,會產生 popup.js 唯一 ID 並傳遞至內容指令碼。

popup.js (完整) :

const sendMessageId = document.getElementById("sendmessageid");
if (sendMessageId) {
    sendMessageId.onclick = function() {
        chrome.tabs.query({ active: true, currentWindow: true }, function(tabs) {
            chrome.tabs.sendMessage(
                tabs[0].id,
                {
                    url: chrome.runtime.getURL("images/stars.jpeg"),
                    imageDivId: crypto.randomUUID(),
                    tabId: tabs[0].id
                },
                function(response) {
                    window.close();
                }
            );
        });
    };
}

內容指令碼訊息接聽程式 (content.js)

以下是 content-scripts\content.js 插入每個瀏覽器索引標籤頁面的檔案。 此檔案會列在中的manifest.json區段中content-scripts。

content.js (完整) :

chrome.runtime.onMessage.addListener(function(request, sender, sendResponse) {
  const img = document.createElement("img");
  img.id = request.imageDivId;
  img.src = request.url;
  img.style = "height: auto; width: 90vw;";
  document.body.prepend(img);

  img.addEventListener("click", () => {
      img.remove();
  }, { once: true });

  sendResponse({ fromcontent: "This message is from content.js" });
});

content.js 使用 chrome.runtime.onMessage.addListener 延伸模組 API 方法註冊接聽程式。 此接聽程式會等候呼叫 chrome.tabs.sendMessage時所傳送popup.js的訊息。

在 content.js中,方法採用 addListener 單一參數,也就是函數。 該函數的第一個參數 request,包含所傳入訊息的詳細資料。

在 中 content.js,當接聽程式處理事件時,會執行傳遞給 addListener 的接聽程式函式。 傳入接聽器函數的第一個參數是一個request物件,其屬性由 指派。sendMessage

在 中 popup.js,對於 chrome.tabs.sendMessage 方法呼叫,的 sendMessage 第二個參數屬性是 url、 imageDivId及 tabId。

以下是傳遞至 addListener:

content.js (部分)

function(request, sender, sendResponse) {
  const img = document.createElement("img");
  img.id = request.imageDivId;
  img.src = request.url;
  img.style = "height: auto; width: 90vw;";
  document.body.prepend(img);

  img.addEventListener("click", () => {
      img.remove();
  }, { once: true });

  sendResponse({ fromcontent: "This message is from content.js" });
}

接聽程式函數中的前五行會緊接在瀏覽器索引標籤元素的body正下方附加一個img元素。

接聽程式函數img.id = request.imageDivId;中的第二行 ,會將元素imageDivId的img識別碼設定為傳入要求的 。

在接聽程式函式中,呼叫會 addEventListener 新增涵蓋 click 整個影像的事件接聽程式函式,讓使用者按一下影像上的任何位置。 當您按一下插入的影像時,影像會以 一行 img.remove();從目前網頁中移除,且事件接聽程式也會移除,方法是指定 { once: true }。

如何 stars.jpeg 從任何瀏覽器索引標籤

若要 images/stars.jpeg 從任何瀏覽器索引標籤啟用:

  • popup.js 上述 () 使用 chrome.runtime.getURL API。
  • 下列資訊清單 () 指定 [符合所有網址] 類型的.jpeg資訊web_accessible_resources清單。

此範例會使用 src 元素的 img 屬性將影像插入內容頁面。 內容頁面執行在與執行擴充功能的執行緒不同的唯一執行緒上。 靜態影像檔案必須公開為Web資產,才能正常運作。

檔案中 manifest.json 會新增另一個項目,宣告影像可供所有瀏覽器索引標籤使用:

/manifest.json (部分) :

"web_accessible_resources": [
    {
      "resources": ["images/*.jpeg"],
      "matches": ["<all_urls>"]
    }
  ]

檔案中的 popup.js 程式碼會傳送訊息至內嵌在目前使用中索引標籤頁面中的內容頁面。

資源列在資訊清單 (manifest.json) 的方式

此範例會建立並插入內嵌在目前作用中索引標籤頁面上的內容頁面。 manifest.json 包括 content-scriptsweb_accessible_resources和 ,如下所示:

/manifest.json (完整) :

{
    "name": "Picture inserter using content script",
    "version": "0.0.0.1",
    "manifest_version": 3,
    "description": "A browser extension that uses JavaScript to insert an image at the top of the current webpage.",
    "icons": {
        "16": "icons/extension-icon16x16.png",
        "32": "icons/extension-icon32x32.png",
        "48": "icons/extension-icon48x48.png",
        "128": "icons/extension-icon128x128.png"
    },
    "action": {
        "default_popup": "popup/popup.html"
    },
    "content_scripts": [
        {
            "matches": [
              "<all_urls>"
            ],
            "js": ["content-scripts/content.js"]
        }
    ],
    "web_accessible_resources": [
        {
            "resources": ["images/*.jpeg"],
            "matches": ["<all_urls>"]
        }
    ]
}

資訊清單的 content_scripts 區段會將 JavaScript 插入所有瀏覽器索引標籤中

在資訊清單檔案的索引鍵區段中content_scripts,matches屬性設定為 <all_urls>,這表示.js在載入每個索引標籤時,將索引鍵區段中content_scripts指定的 (或 .css) 檔案插入所有瀏覽器索引標籤頁面。 允許插入的檔案類型為 JavaScript (.js) 和 CSS (.css) 。

此示例的資訊清單指定單一內容指令碼。 content-scripts/content.js

每個內容指令碼都在自己的執行緒中執行,沙箱化

每個索引標籤頁面 (和擴充功能) 都在自己的對話中執行。 即使瀏覽器索引標籤包含執行 JavaScript 程式碼的網頁, content.js 擴充功能插入該瀏覽器索引標籤的指令碼也無法存取該 JavaScript 程式碼。 插入的內容指令碼只能存取網頁的 DOM。

後續步驟

若要開發您自己的 Microsoft Edge 擴充功能,您可以複製和修改範例的目錄,然後安裝和測試產生的擴充功能。

另請參閱

GitHub: