跳轉到主要內容
Extension.js 支援純 CSS,以及 Sass 與 Less 等預處理器,無需任何設定。它會針對頁面情境(popup、options、side panel)與 content script 情境採用不同的路由方式。 頁面樣式以連結資產的方式出貨。在 content script 裡,樣式套用在哪裡取決於你怎麼引用它。本頁的 content script 一節列出了每一種方式。

範本範例

content-sass

content-sass template screenshot 把 Sass 樣式注入網頁的 content script。
儲存庫:extension-js/templates/content-sass

content-custom-font

content-custom-font template screenshot 示範透過 CSS 載入自訂字型的 content script。
儲存庫:extension-js/templates/content-custom-font

CSS 能力

在哪裡參考 CSS

  • manifest.json(content_scripts[].css)
  • HTML 檔案(<link rel="stylesheet" href="...">)
  • Script 中的 import(import "./styles.css",啟用時也包含 Sass/Less)。在 content script 裡,這種 import 本身不會替任何東西加上樣式。

CSS 支援

Manifest 中的 CSS 進入點:

範例:manifest.json 中的 CSS

範例:在擴充功能頁面 script 中引用 CSS

content script 中的樣式

在 content script 裡,單純的 import "./styles.css" 得到的值是一個 data: URL 形式的樣式表。它本身不會替任何東西加上樣式。Sass 與 Less 的 import 也是一樣。 Extension.js 只在一種情況下替你放置這份樣式表。這條 import 必須寫在已宣告的 content script 的入口檔裡,而且腳本必須用 data-extension-root 標記一個宿主元素。樣式表隨後會進入這個宿主的 shadow root。請見 Shadow DOM。 要替頁面本身加上樣式,請使用下列任一種方式: 最後一種方式會讀取 import 得到的值,再自己放置它:
你在執行階段注入的 scripts/ 檔案不會得到任何自動放置。在那裡請讀取這個值,再把它設到 <link> 上。 從 4.1.39 之後的版本起,如果一條只為副作用而寫的樣式 import 沒有被任何東西放置,建置會印出一則警告。

樣式政策嚴格的頁面

頁面的內容安全政策(CSP)也決定 content script 自己的 DOM 呼叫能做什麼。結果取決於腳本執行在哪個 world。在送出 style-src 'self' 的頁面上: 這些結果是在 Chrome 151 與 Firefox 160 上量測的,dev 與正式建置都一樣。shadow root 裡的 <style> 元素會和文件裡的一樣被拒絕。 在送出 default-src 'self' 的頁面上,fetch(href) 也會被拒絕。在 MAIN world 裡兩個瀏覽器都是如此,在 isolated world 裡只有 Firefox 如此。 建置看不到腳本將要造訪的頁面的政策。它不會更動這些呼叫,也不會印出警告。必須在這種政策下運作的 MAIN world 腳本,可以不發請求,直接從 URL 裡讀出樣式表並採用它:
關於注入的樣式表裡的 @import,以及 public/ 裡被注入的樣式表,見執行階段載入的檔案。

內容腳本中的網頁字型

把介面渲染到 shadow root 的內容腳本,無法只靠 CSS 載入網頁字型。有兩條平台規則會擋住它,而且都是靜默的。 shadow root 內部的 @font-face 永遠不會生效。 字型(font face)解析的是文件的字型集,而不是 shadow 樹,所以 Chrome 會忽略該規則並靜默回退。修正前在 content-custom-font 範本上實測:document.fonts 為空,沒有發出任何字型請求,以 "Momo Signature", cursive 排版的文字寬度與純 cursive 完全相同。 注入樣式表中的根絕對 url() 會相對宿主頁面解析。 注入到 example.com 的樣式表中的 url(/fonts/Momo.woff2) 請求的是 https://example.com/fonts/Momo.woff2,而不是擴充功能自己的那份檔案。 改為把字型註冊到頁面自身的字型集上,URL 指向擴充功能,並在內容腳本卸載時移除它:
該字型檔必須能被頁面存取,所以要在 web_accessible_resources 中宣告:
字型一旦進入 document.fonts,shadow 樹就可以在一般的 font-family 規則裡以名稱使用它。可運行的版本見 content-custom-font。

以 URL 匯入樣式表

從 4.1.41 之後的版本起,在 content script 之外,?url 匯入會給出編譯後樣式表的 URL:
建置會編譯該樣式表,並把它當成獨立的檔案放在 assets/ 下。該樣式表中相對的 url() 或 @import 無法跟著它到新位置,一則警告會列出這些位址。把那些檔案移到 public/ 中並從根路徑引用,或不帶 ?url 匯入該樣式表。

依情境的輸出行為

Extension.js 會依照哪一個進入點 import 該 CSS 自動拆分情境。 從 4.1.41 之後的版本起,content script 樣式表會連同它匯入的每個專案 .css 檔案的規則一起發布。匯入的 media、supports 或 layer 條件會被保留。content script 樣式表從 data: URL 載入,瀏覽器在那裡不會擷取任何相對匯入。套件與遠端的匯入保持原樣。專案之外的樣式表或私有檔案不會被帶進來,建置會點名該檔案發出警告。在所有工具執行完之後仍留在樣式表中的 @import,會警告它的規則不會載入。 從 4.1.41 之後的版本起,Extension.js 以自己的規則編譯每個樣式表,這些規則優先於你的設定。你的設定為 .css、.scss、.sass 或 .less 檔案設定的 type 不會套用。一則警告會說明這一點。請從該規則中移除 type。要取得檔案 URL,以 ?url 匯入樣式表。要取得文字,以 ?raw 匯入。 正式建置壓縮樣式表時,Extension.js 會把結果與壓縮前的樣式表比較。遺失了規則的樣式表會照原樣發布,並附上一則警告,指出被丟掉的內容。從 4.1.41 之後的版本起,只有建置進行壓縮時才執行這項檢查,因此 dev 會略過它。從 4.2.0 起,這則警告帶有代碼 W_CSS_PARSE。 url() 指向專案中任何地方都不存在的檔案時,會以 W_CSS_DEAD_REF 警告,樣式表的其餘部分照常發布。瀏覽器對那個位址回應 404。設定 EXTENSION_STRICT_REFS=true 可以讓建置以 E_CSS_DEAD_REF 失敗。 從 4.2.0 之後的版本開始,打包器無法解析的 url(),比如沒有副檔名的裸名稱,或者未安裝的作用域套件路徑,也會回報同樣的 W_CSS_DEAD_REF,而且 EXTENSION_STRICT_REFS=true 會讓建置以 E_CSS_DEAD_REF 失敗。4.2.0 及之前的版本把它回報為 W_ASSET_MISSING,嚴格參照模式也不會因此失敗。

開發行為

  • Content script 的 CSS import 會參與 content script 的 HMR/重新掛載流程。
  • Extension.js 會為純 CSS 的 content script 進入點加上開發輔助 script,讓更新可以傳播。
  • 頁面 CSS 會走標準的頁面 HMR 流程。
  • manifest 的修改會重新載入整個擴充功能。修改 manifest 中的 content script 進入點還會讓 dev 工作階段重新啟動編譯器,不需你操作。

模組與預處理器

  • CSS Modules 在擴充功能頁面情境中運作得最好。
  • 當你安裝相關相依套件時,Extension.js 會啟用 Sass/Less 支援。
  • 如果專案引用了 .scss/.less 檔案但沒有安裝預處理器,建置不會失敗,而是發出警告並把原始檔原封不動地複製過去(不編譯)。瀏覽器會把這份未編譯的原始碼當成壞掉的 CSS,那些畫面就會完全沒有樣式,所以請安裝預處理器以取得真正的編譯。
  • 當 Extension.js 偵測到專案中的 PostCSS 設定、或你明確設定時,會自動執行 PostCSS。

最佳實務

  • 刻意限制 content script 樣式範圍,降低與主機頁面的衝突。
  • 為擴充功能頁面 UI 優先採用元件本地的 module 樣式。
  • 明確保留預處理器與 PostCSS 設定,避免建置設定隨時間意外改變。
  • 在持續整合(CI)中驗證被 manifest 欄位參考的 CSS 路徑。

後續步驟

影片導覽