前端與設定介面
設定介面(config.exe)由 Tauri 2(Rust 後端)+ Svelte 5(前端) 構成。本章介紹其技術選型、結構與關鍵設計。
為什麼選擇 Svelte
設定介面是一個表單密集型的小應用程式,經過選型比較後採用 Svelte 5 + Vite:
- 雙向繫結是核心訴求:Svelte 的
bind:原生支援雙向繫結(React 無雙向繫結,需手寫受控元件;Vue 的v-model可用但執行階段更大)。 - 編譯期反應式、無虛擬 DOM:建置產物僅約 80 KB(gzip 約 28 KB),契合本專案「體積極小」的目標。
- Tauri 官方一等支援。
前端工程結構
apps/config/ui/
├── src/
│ ├── App.svelte 頂層:標籤頁 + 自動儲存 + 啟動編排
│ ├── main.js 進入點(掛載前先套用一次佈景主題,避免閃爍)
│ ├── components/ UI 元件(TitleBar、各設定面板、各對話方塊…)
│ └── lib/ 純邏輯(可單元測試)
│ ├── state.svelte.js 全域狀態($state)+ 各類動作
│ ├── ipc.js 呼叫 Tauri 命令/監聽事件
│ ├── hotkey.js 快速鍵解析/格式化(配 hotkey.test.js)
│ ├── capture.js 錄製期獨佔鍵盤(後端攔截,失敗回落 DOM 事件)
│ ├── pointer.js 滑鼠連按/連按時間常數(配 pointer.test.js)
│ ├── grouping.js 視窗/程序規則的增刪與篩選(配 grouping.test.js)
│ ├── theme.js 佈景主題切換(配 theme.test.js)
│ ├── i18n.svelte.js 介面語言:catalog 查表 + 語言解析(配 i18n.test.js)
│ ├── markdown.js 公告/更新記錄的 Markdown 算繪(配 markdown.test.js)
│ ├── powerstats.js 能效統計的換算與格式化(配 powerstats.test.js)
│ └── verhub.js 檢查更新/公告/意見回饋(含轉 Issue)/專案連結/開啟外部連結
├── locales/ 三語文案 catalog(zh-CN.js / en.js / zh-TW.js)
├── vite.config.js
└── svelte.config.js設定介面以標籤頁組織,每個標籤頁對應一個面板元件:
| 標籤 | 元件 | 內容 |
|---|---|---|
| 視窗綁定 | BindingPanel | 視窗清單 + 視窗/程序規則 |
| 白名單 | WhitelistPanel | 程式在隱藏時需要略過的功能 |
| 快速鍵與滑鼠 | HotkeysPanel | 鍵盤快速鍵、滑鼠連按、四角、閒置自動隱藏 |
| 隱藏設定 | HidePanel | 靜音/暫停鍵/通知區域圖示/最小化 |
| 能效控制 | PowerPanel | 程序凍結與記憶體佔用 |
| 提示設定 | NotificationsPanel | 逐事件通知開關與圖示狀態角標 |
| 關於與意見回饋 | AboutPanel | 版本、更新、公告、意見回饋(可轉為 GitHub Issue) |
| 通用設定 | OptionsPanel | 自動啟動/權限/語言/記錄檔/工具 |
無邊框自繪視窗
Tauri 設定 decorations: false,標題列由前端自繪:
data-tauri-drag-region實現拖曳、連按兩下最大化;- 自繪最小化/最大化/關閉按鈕;
- 八向邊緣
startResizeDragging縮放熱區(最大化時自動停用); - 淺色/深色/跟隨系統三態佈景主題(
localStorage保存 +prefers-color-scheme監聽)。
設定自動儲存
App.svelte 中用 $effect 深度追蹤設定物件(含 window_rules/process_rules)的任何變化,停頓後經 scheduleSave(內部 debounce)自動寫入磁碟。載入階段不觸發儲存,loadAll 完成後才「啟用」自動儲存。排程邏輯在 lib/autosave.js:連續變更合併為一次寫入,寫入互不並行,寫入途中的新變更在上一筆完成後補寫。
關窗請求(標題列按鈕、Alt+F4)會先把未寫入磁碟的變更寫完再關閉;寫入失敗時視窗保持開啟並彈出錯誤框,再次關閉不再阻攔。
儲存後前端透過 IPC 通知核心 reload_config,核心熱重新載入設定。
介面語言
文案集中在 src/locales/,每個語言一個扁平鍵值表;lib/i18n.svelte.js 負責查表與語言解析。
import { t } from "../lib/i18n.svelte.js";
t("common.close"); // → 關閉
t("restore.frozen", { n: 3 }); // → 已凍結 3 個程序t()讀取$state裡的目前語言,因此在範本中呼叫它即可在切換語言時自動重新算繪,不需手動訂閱。zh-CN.js是文案基準:新增文案先寫它,再同步en.js與zh-TW.js。i18n.test.js會驗證三份 catalog 的鍵集與佔位符完全一致,漏譯即測試失敗。- 缺少的鍵回落到簡體中文,仍缺少則傳回鍵本身,便於開發期發現漏譯。
- 目前語言取自
setting.language;auto時按navigator.language推斷。App.svelte用$effect追蹤該欄位,變更即時換文案,並同步寫<html lang>(影響字型回落與斷行)。 lib/裡的純邏輯模組(pointer.js、grouping.js、theme.js)也經由t()取文案;因預設語言為簡體中文,它們的既有單元測試不需改動。
NO_TITLE 不是文案
grouping.js 的 NO_TITLE("无标题窗口")與核心 zonedeck_common::NO_TITLE 一致,是寫進 config.json 的跨程序哨兵值,不可翻譯;僅在顯示時用 t("common.noTitleWindow") 換成目前語言。
公告與更新記錄的 Markdown 算繪
公告(清單與啟動對話方塊)與更新記錄的內文按 Markdown 算繪,由 lib/markdown.js(純函式,配 markdown.test.js)與 components/Markdown.svelte(樣式 + 連結攔截)承擔,不引入第三方相依套件。
支援 GitHub 風格的常用子集:標題、粗體/斜體/刪除線、行內程式碼與圍籬程式碼區塊、有序/無序/工作清單(含縮排巢狀)、引用、分隔線、連結與裸連結。段落內的軟換行算繪成 <br>,與 GitHub 留言一致。不支援表格、註腳、行內 HTML 與語法醒目提示。
內文來自遠端,算繪前必須逸出
Verhub 回傳的內容不可信。renderMarkdown() 先整體逸出 & < > " 再組標籤,輸出裡出現的標籤全部由算繪器自己產生,原始文字中的 HTML 只會作為字面值顯示;連結目標僅放行 http(s) 與 mailto,其餘(javascript:、data: 等)按純文字保留。改動該模組時勿繞過這兩條。
另有兩處與執行環境相關的取捨:
- 圖片退化成連結:Tauri 的 CSP 中
img-src只允許self與data:,遠端圖片載入不了,因此![]()一律算繪為連結。 - 連結不走 webview 導覽:
Markdown.svelte攔截點擊並轉交open_external,由系統瀏覽器開啟——webview 真的導覽走了就回不到設定介面。
狀態輪詢不卡介面
- 狀態取得合併為單一
GetStatus管道命令,並使用連線快速失敗(不重試)。 - Tauri 命令用
spawn_blocking非同步化,避免阻塞。 - 前端每 2 秒輪詢一次狀態(頁面不可見時暫停)。
前端不相依於 dev server
最終產物中,前端在編譯期被內嵌進 zonedeck-config.exe,靜態執行,不需要任何本機伺服器。
- 開發前端 UI:
npm run dev在瀏覽器裡預覽(mock 資料、熱重新載入)。 - 驗證 Tauri 整合:
npm run build後cargo run -p zonedeck-config。
與核心的連動範例
- 核心通知區域的「視窗復原工具」/「關於」會帶參數開啟設定介面:冷啟動從啟動參數讀取,已執行時由單一執行個體外掛程式傳來事件。
- 首次啟動若核心未執行,設定介面會自動
startCore啟動核心。