跳轉到主要內容
以 Svelte 元件打造擴充功能 UI,同時讓 Extension.js 負責框架的串接工作。 Extension.js 會從專案的相依套件偵測 Svelte,並自動設定 .svelte 解析、loader 與 Svelte 的 client 別名。

什麼情況下適合使用 Svelte

  • 你希望 popup、options、sidebar 或 new-tab UI 有較小的執行期。
  • 你偏好以元件為主、語法精簡的撰寫方式。
  • 你希望這個框架在擴充功能頁面與 content script UI 兩種情境都可用。

範本範例

new-svelte

new-svelte template screenshot 當你想要以框架為主的擴充功能 UI 且只需最少設定時,使用 Svelte 範本。
Repository: extension-js/templates/newtab-svelte

content-svelte

content-svelte template screenshot 透過 content script 把 Svelte 元件注入網頁中。
Repository: extension-js/templates/content-svelte

在既有擴充功能中使用

安裝 Svelte:
如果要在既有專案中明確設定,也安裝 Svelte loader:
當選用的 svelte-loader 套件缺少時,建置錯誤會指出與內建工具鏈相符的確切版本。錯誤訊息中的安裝指令會依你專案實際使用的套件管理器來呈現。

開發行為

當 Extension.js 偵測到 Svelte 時,會:
  • 啟用 .svelte 檔案解析。
  • 在 JS 框架 pipeline 中設定 Svelte loader,並在開發階段啟用熱重載,讓修改過的元件不必整頁重新載入就能更新。
  • 套用 Svelte client 別名(例如 svelte、svelte/store、svelte/reactivity)。
若專案缺少選用工具,Extension.js 不會替你安裝,而是以確切的安裝指令提出警告。之後請重新啟動。

使用範例

在擴充功能頁面中

Extension.js 以 Svelte 5 為目標。Svelte 4 的 class API(new App(...) 與 app.$destroy()) 在模板所安裝的版本上會拋出 component_api_invalid_new。

在 content_script 檔中

對於 content script,建立掛載節點,並在 default export 中回傳一個 cleanup 函式。這讓 Extension.js 在開發階段可以安全地重新掛載:
從 4.1.39 之後的版本起,元件的 <style> 區塊在 content script 裡會生效。它落在哪裡取決於 Svelte 編譯器的 css 選項:
  • 預設設定。 Extension.js 把這個區塊編譯成一份獨立的樣式表。建置會把它以一個 <style> 元素加進 document,所以它進不了 shadow root。
  • css: "injected"。 編譯後的元件自帶樣式,Svelte 5 會在元件掛載時把它們加進去。掛載在 shadow root 裡的元件,它的 <style> 元素會放進那個 root。其他元件的 <style> 元素會放進 document 的 <head>。
Extension.js 從專案根目錄的 svelte.loader.js 檔案讀取 Svelte loader 選項。在 compilerOptions 下設定這個選項:
該檔案也可以命名為 svelte.loader.mjs、svelte.loader.ts 或 svelte.loader.mts。從 4.2.0 之後的版本起,載入時拋出例外的 loader 選項檔會讓建置以 E_CONFIG_LOAD 停止。訊息會指名該檔案與原因。 當 Svelte 編譯器比你專案中的 svelte 套件更新時,執行環境會跟隨編譯器,並有一則警告說明這一點。從 4.2.0 之後的版本起,編譯器比專案的 svelte 更舊時也是如此。這則警告帶有代碼 W_MANAGED_DEP_CONFLICT,而且 svelte 只從你的專案讀取,永遠不會從指令執行所在的資料夾讀取。 這則警告每次執行只印一次。要用你專案固定的 svelte 編譯,請把 svelte-loader 加入專案,讓編譯器在你自己的副本旁解析。

最佳實務

  • 讓 Svelte 元件專注於 UI,把瀏覽器 API 的協調工作放進專屬模組。
  • 在 content script 中,務必回傳 cleanup,讓重新掛載的行為可預期。
  • 先在擴充功能頁面使用 Svelte,等到功能範圍清楚後再擴展到 content script UI。

下一步

影片導覽

模板示範