建立第一個能在網頁上插入新元素的擴充功能。
總覽
本教學課程會建構一個擴充功能,可將預期的閱讀時間新增至任何 Chrome 擴充功能, Chrome 線上應用程式商店說明文件頁面。
![在擴充功能的歡迎頁面中讀取延期資訊](https://developer.chrome.google.cn/static/docs/extensions/get-started/tutorial/scripts-on-every-tab/image/reading-extension-the-e-0070620f12665.png?authuser=19&hl=zh-tw)
本指南將說明下列概念:
- 擴充功能資訊清單。
- 擴充功能使用的圖示大小。
- 如何使用內容指令碼將程式碼插入網頁。
- 如何使用比對模式。
- 擴充功能權限。
事前準備
本指南假設您具備基本的網站開發經驗。建議您參閱 Hello World:擴充功能開發工作流程簡介。
建立擴充功能
首先,請建立名為 reading-time
的新目錄,用來存放擴充功能的檔案。如果發生以下情況:
如有需要,您可以前往 GitHub 下載完整的原始碼。
步驟 1:新增擴充功能相關資訊
資訊清單 JSON 檔案是唯一的必要檔案。其中包含
。在專案的根目錄中建立 manifest.json
檔案,並新增下列程式碼:
{
"manifest_version": 3,
"name": "Reading time",
"version": "1.0",
"description": "Add the reading time to Chrome Extension documentation articles"
}
這些鍵包含擴充功能的基本中繼資料。並控制擴充功能在擴充功能頁面和 Chrome 線上應用程式商店發布後的顯示方式。若要深入瞭解,請查閱
上的 "name"
、"version"
和 "description"
鍵
「資訊清單」總覽頁面。
💡? 擴充功能資訊清單的其他相關資訊
- 它必須位於專案的根層級。
- 只需要使用
"manifest_version"
、"name"
和"version"
這兩個鍵。 - 這個擴充功能在開發期間支援註解 (
//
),但您必須先移除這些註解,才能將程式碼上傳至 Chrome 線上應用程式商店。
步驟 2:提供圖示
那麼,為什麼需要圖示?雖然圖示在開發期間是選用項目,但 。也會顯示在其他 例如「擴充功能管理」頁面
建立 images
資料夾,將圖示放入其中。您可以前往
GitHub。接著,請將醒目顯示的程式碼新增至資訊清單來宣告圖示:
{
"icons": {
"16": "images/icon-16.png",
"32": "images/icon-32.png",
"48": "images/icon-48.png",
"128": "images/icon-128.png"
}
}
建議使用 PNG 檔案,但可使用其他檔案格式 (SVG 檔案除外)。
💡? 這些不同大小的圖示會顯示在哪裡?
圖示尺寸 | 使用圖示 |
---|---|
16x16 | 擴充功能頁面與內容選單中的網站小圖示。 |
32x32 | Windows 電腦通常需要這個大小。 |
48x48 | 這項資訊會顯示在「額外資訊」頁面上。 |
128x128 | 會顯示在安裝過程中和 Chrome 線上應用程式商店中。 |
步驟 3:宣告內容指令碼
擴充功能可以執行指令碼,以便讀取及修改網頁內容。這些都稱為內容 指令碼這些 Cookie 生活在獨立的世界,因此能夠變更自己的 JavaScript 環境,而不會與代管網頁或其他擴充功能相衝突內容指令碼
將下列程式碼新增至 manifest.json
來註冊名為
content.js
。
{
"content_scripts": [
{
"js": ["scripts/content.js"],
"matches": [
"https://developer.chrome.com/docs/extensions/*",
"https://developer.chrome.com/docs/webstore/*"
]
}
]
}
"matches"
欄位可以有一或多個比對模式。這些事件可讓瀏覽器
找出要插入內容指令碼的網站。比對模式由三個部分組成:
<scheme>://<host><path>
。可以包含「*
」字元。
💡? 這項擴充功能會顯示權限警告嗎?
當使用者安裝擴充功能時,瀏覽器會通知使用者這項擴充功能可執行的操作。內容指令碼會要求在符合比對模式條件的網站上執行。
在此範例中,使用者會看到下列權限警告:
![使用者安裝閱讀時間擴充功能時,會看到權限警告](https://developer.chrome.google.cn/static/docs/extensions/get-started/tutorial/scripts-on-every-tab/image/permission-warning-user-af0cb023a0128.png?authuser=19&hl=zh-tw)
如要進一步瞭解擴充功能權限,請參閱「宣告權限及警告使用者」。
步驟 4:計算並插入朗讀時間
內容指令碼可以使用標準文件物件模型 (DOM) 來讀取及變更
網頁上的內容擴充功能會先檢查網頁是否含有 <article>
元素。
然後,它會計算該元素內的所有字詞,並建立顯示總計
讀取及寫入資料
在名為 scripts
的資料夾中建立名為 content.js
的檔案,然後新增下列程式碼:
const article = document.querySelector("article");
// `document.querySelector` may return null if the selector doesn't match anything.
if (article) {
const text = article.textContent;
const wordMatchRegExp = /[^\s]+/g; // Regular expression
const words = text.matchAll(wordMatchRegExp);
// matchAll returns an iterator, convert to array to get word count
const wordCount = [...words].length;
const readingTime = Math.round(wordCount / 200);
const badge = document.createElement("p");
// Use the same styling as the publish information in an article's header
badge.classList.add("color-secondary-text", "type--caption");
badge.textContent = `⏱️ ${readingTime} min read`;
// Support for API reference docs
const heading = article.querySelector("h1");
// Support for article docs with date
const date = article.querySelector("time")?.parentNode;
(date ?? heading).insertAdjacentElement("afterend", badge);
}
💡? 程式碼中使用的有趣 JavaScript
- 普通
運算式,可用於計算
<article>
元素中的字詞。 insertAdjacentElement()
,用來在元素後方插入朗讀時間節點。- classList 屬性可用於將 CSS 類別名稱新增至元素類別屬性。
- 選用的鏈結,用來存取可能未定義或空值的物件屬性。
- 如果
<date>
為空值或未定義,Nullish Coalescing 會傳回<heading>
。
測試是否能正常運作
確認專案的檔案結構如下所示:
在本機載入擴充功能
如要在開發人員模式下載入未封裝的擴充功能,請按照「開發 基本概念。
開啟擴充功能或 Chrome 線上應用程式商店說明文件
您可以開啟下列幾頁,查看每篇文章需要多少時間。
看起來應該像這樣:
![歡迎頁面上的朗讀時間](https://developer.chrome.google.cn/static/docs/extensions/get-started/tutorial/scripts-on-every-tab/image/reading-running-the-wel-1d750346edcea.png?authuser=19&hl=zh-tw)
🎯? 改進空間
請根據您目前學到的內容,嘗試以下列任何一種方式實作:
- 在 manifest.json 中加入另一個比對模式,以支援其他 Chrome 開發人員 頁面,例如 Chrome 開發人員工具或 Workbox。
- 新增內容指令碼,可計算閱讀時間至任何喜愛網誌,或是 說明文件網站。
繼續建構
恭喜您完成本教學課程 🎉?。完成其他 本系列的教學課程:
擴充功能 | 學習目標 |
---|---|
專注模式 | 點選擴充功能動作後,在目前頁面執行程式碼。 |
分頁管理工具 | 建立用於管理瀏覽器分頁的彈出式視窗。 |
繼續探索
希望您會喜歡建構這個 Chrome 擴充功能,也非常期待能繼續使用您的 Chrome 開發學習旅程建議您按照下列學習路徑操作:
- 開發人員指南提供了數十種說明文件的連結 與進階額外資訊建立流程相關
- 除了開放網路可用的擴充功能,擴充功能也能存取各種強大的 API。 Chrome API 說明文件會逐一介紹各個 API。