Svelte on Tarragon

在外部組件上加客製功能：以邊界為中心的方法選擇

Sat, 25 Apr 2026 00:00:00 +0000

核心原則

客製外部組件的穩定性與「離組件邊界多近」成正比。 組件作者維護組件內部的一致性；客製貼著組件的對外介面（CLI 參數、CSS reset 邊界、CSS layer）做，組件升級不會打到客製。深入組件內部（注入子節點、改 source 行為）的客製則仰賴組件的內部實作，作者不保證下個版本還相容。

這條原則對應到 Pagefind 整合時的三個具體情境，本文逐一拆解。

邊界概念：為什麼用「邊界」看外部組件

這類問題的本質（商業邏輯）

組件 = 一組對外契約 + 內部實作。對外契約是作者保證的東西（CLI 參數、CSS class name、CSS variable hooks），內部實作是達成契約的手段、可能在版本之間變動。

客製貼著對外契約做，等於跟作者站在同一邊；客製動到內部實作，等於跟作者每個版本對抗。

「邊界」這個概念把組件分成「契約面」與「實作面」 — 客製選位置時，依離邊界遠近排序：

客製位置	跨越時的依賴
組件對外介面	介面契約（穩定）
組件 DOM 邊界外	邊界元素的 class / id 名稱（半穩定）
組件 DOM 邊界內	內部 DOM 結構（隨框架渲染週期變動）
組件內部邏輯	source code（升級時必衝突）

這次任務涉及的邊界（CASE）

Pagefind 提供三條值得辨識的邊界：

邊界名稱	介面形式	範圍
索引邊界	`--root-selector` 參數	「組件看到什麼資料」
重置邊界	`.pagefind-ui--reset` class	對 UA 樣式的覆寫範圍
specificity 邊界	svelte hash class（雙寫到 30）	組件 CSS 的權重起點

每條邊界各有對應的客製介面 — 緊貼這些介面比繞道進內部安全得多。

索引邊界：用 root-selector 限縮搜尋範圍

核心定義：Pagefind 的索引流程透過 --root-selector 參數控制「哪些 HTML 進索引」。這是組件預期的客製介面。

這次的觀察

theme 的 site header 包含

`{{ .Site.Title }}`

，每一頁 DOM 上的第一個 h1 都是站名「Tarragon」。Pagefind 預設取頁面第一個 h1 當搜尋結果 title — 結果所有結果都顯示「Tarragon」。

判讀

第一個 h1 是站名而非文章名 — 索引「看到」的範圍跟我們以為的不同。要修的不是 theme（影響其他頁面），是 Pagefind 的 input 範圍。

執行

1npx -y pagefind --site public --root-selector main

內才包含文章 h1；site header 在直接子節點、不在

內，自然被排除。

完成標準：每一筆結果的 title 顯示文章 h1，而非站名。

重置邊界：在落腳處重建 UA 樣式

核心定義：CSS reset 的有效範圍與 ancestor class 綁定。元素換位置就換 reset context — 這是 CSS 的基本機制，不是 bug。

這次的觀察

Filter UI（.pagefind-ui__filter-panel，本質是

）需要從 .pagefind-ui 搬到外部 aside（左側 sidebar）。搬完後 fieldset 的瀏覽器預設邊框冒出來。

判讀

.pagefind-ui--reset 用 all: unset 重置所有後代元素的 UA 樣式。fieldset 搬出 .pagefind-ui 後，這個 ancestor 不在了，UA 樣式（包括 fieldset 預設邊框）回到原樣。

執行

在 fieldset 落腳處（aside 內）重新關掉 UA 樣式：

1.search-filter-slot fieldset {
2  border: 0;
3  padding: 0;
4  margin: 0;
5}

完成標準：fieldset 在新位置看起來跟在 .pagefind-ui 內一樣 — 沒有多餘邊框。

specificity 邊界：跳出線性比較戰場

核心定義：當組件透過 hash class 把 specificity 拉高到一般客製寫法蓋不過時，邊界落在 CSS 樣式分層機制 — 不在個別 selector 數字。

這次的觀察

Pagefind 透過 svelte 把 class name 加 hash 重複寫進 selector（.x.svelte-y.svelte-y），把 specificity 從 10 提升到 30。一般客製 CSS specificity 10-20、蓋不過去。

判讀

Specificity 是線性數字比較 — 跟組件作者比 specificity 是無贏的軍備競賽。要真正解這類覆寫戰、需要跳出「線性比較」這個維度本身。

執行

具體做法（@import url(...) layer(...)）與升級兼容性、其他外部組件的 layer 策略，由 #24 CSS Layers 取代 specificity 戰完整展開。在邊界辨識上、本篇要記住的是：遇到 specificity 30+ 的覆寫戰、不要往 !important / .x.x 雙寫的方向加碼、改去看 layer 維度。

完成標準：所有原本需要 !important 或 .x.x 雙寫的覆寫，可以用單純的 class selector 寫。

客製深度的內在屬性比較

選擇客製位置時，用三個內在屬性比較 — 不用「實作要多久」這類時間維度：

位置	依賴前提	升級風險	可逆性
組件對外介面	介面 stable across 版本	低 — 介面是公開契約	高 — 改一個參數即可還原
DOM 邊界外（class hooks）	邊界元素 class / id 穩定	中 — class 改名才打破	中 — 改選擇器即可
DOM 邊界內	內部 DOM 結構穩定	高 — 框架重繪可能即時打破	低 — 客製跟內部結構深度耦合
內部邏輯（fork / patch）	整個組件 source	最高 — 升級必衝突	最低 — 重新 merge

選擇順序：先試最外層；不夠用再往內推一層。每往內一層、依賴前提增加、升級風險上升、可逆性下降。

設計取捨：客製位置的層次選擇

四種做法、各自機會成本不同。預設選最外層（A）、不夠用才往內推一層。

本篇是 #45 跟外部組件合作的層次抽象原則在「客製位置選擇」這個面向的應用。

A：組件公開介面層（最佳）

機制：用組件提供的 CLI 參數、props、CSS variable hook、event API 客製
選 A 的理由：作者保證跨版本相容、客製跟組件升級無關
適合：能被介面覆蓋的客製需求（多數常見場景）
代價：受介面範圍限制、超出範圍只能往內推

B：鄰接層（class hooks、reset 邊界）（這個專案的次選）

機制：用組件邊界元素的 class / id / data attribute 寫客製 CSS、注意 CSS reset 邊界
跟 A 的取捨：B 介面外但仍貼著組件邊界、A 在介面內；B 在 class 名穩定時 OK、改名就壞
B 比 A 好的情境：組件未提供對應介面、但有穩定的 class 邊界可掛勾

C：邊界內 DOM 操作

機制：JS 改組件內部 DOM 結構 / 節點屬性 / 注入元素
跟 A/B 的取捨：C 直接操控、跟 framework reconciliation 競爭；風險顯著上升
C 才合理的情境：A/B 都無法達成、且能容忍每次升級重做（#13 的安全規則必看）

D：Fork / patch 組件 source

機制：fork 整個組件、改 source code、自家維護版本
成本特別高的原因：每次升級都要 merge upstream、客製永久綁在 fork
D 才合理的情境：客製需求超過所有其他選項、且願意承擔 fork 維護成本

判讀徵兆

下次遇到組件整合任務、看到這些訊號就走「找邊界」的路：

訊號	對應邊界類型	第一個該嘗試的動作
組件抓到的資料超過你想要的範圍	索引邊界	找組件的 `root` / `scope` / `selector` 參數
同一段 CSS 在不同位置表現不一致	重置邊界	比對兩個位置的 ancestor class、看 reset 是否還在
`!important` 寫了還是沒蓋過	specificity 邊界	看組件 CSS 是否用 hash class 提升 specificity；考慮 CSS Layers
組件渲染後客製 UI 消失	DOM 結構邊界	把客製 UI 搬出組件、用 CSS 控制視覺位置
組件升級後客製失效	內部邏輯邊界	把客製重寫到組件介面層

使用順序：訊號出現 → 對應邊界 → 嘗試該邊界提供的介面 → 介面不夠用、才考慮往內推一層。

客製 UI 留 framework 邊界外、用 CSS 控制視覺位置

Sat, 25 Apr 2026 00:00:00 +0000

核心原則

客製 UI 留在 framework 管轄的 DOM 邊界外、用 CSS（absolute、margin spacer、grid）達成想要的視覺位置。 注入 framework 子樹的客製元素會被 reconciliation 清掉、跟渲染週期競爭、行為不可預測。邊界外的客製跟 framework 解耦、命運由我們自己決定。

本篇焦點：客製 UI 該放哪。framework 元件本身需要動（搬節點、改順序、改 attribute）的安全規則由 #13 JS 操作 framework 元件：邊界辨識與安全規則處理。

為什麼 framework 管轄區會清外來節點

Reconciliation 機制

Svelte / React 等框架透過「component tree → DOM tree」的 reconciliation 機制保持 UI 與 state 同步。框架在 patch 時：

比對 component tree 的當前狀態與目標狀態
計算 DOM 需要的最小變動
套用變動到實際 DOM

關鍵是步驟 2：框架只認得自己 create 的節點。外來節點（我們手動 appendChild 進去的）不在它的 component tree 裡、被視為「該節點不該存在」、清掉。

這不是 bug、是 reconciliation 的正常行為 — 框架要保證 DOM 跟 component state 一致、外來節點屬於不一致的部分。

外來節點的命運是不可預測的

不同框架 / 不同 reconciliation 策略對外來節點的處理：

框架	外來節點命運
Svelte	多數情境清掉、視 patch 點而定
React	通常清掉（Virtual DOM diff 時）
Vue	通常清掉、但 v-pre 包裹可保留
Web Components	由 component 內部邏輯決定

「不可預測」本身就是問題 — 即使某次測試沒清、下次升級或 patch 時可能清。設計時不該依賴未明確保證的行為。

這次任務的具體情境

觀察

要把搜尋範圍切換 UI（scope radio group）放在「pagefind 搜尋輸入框與結果之間」 — 視覺上希望它就在 form 與 drawer 中間。

第一次嘗試：JS 把 scope element 用 form.insertAdjacentElement('afterend', scopeEl) 注入 .pagefind-ui 內部。

結果：使用者打字後 scope 消失。

判讀

Pagefind 用 svelte 構建 UI、reactivity 監聽 search query 變動。Query 改變時 svelte 會 patch .pagefind-ui 的子樹 — 我們注入的 scope 不是 svelte 認得的節點、被視為差異清掉。

執行：邊界外 + CSS 控制位置

策略改為「scope 留在 .search-shell 裡（framework 邊界外）、用 CSS absolute 浮在 form 上」：

1<div class="search-shell">
2  <h1>...h1>
3  <div class="search-scope">...div>      
4  <div id="search">...div>               
5div>

1.search-shell { position: relative; }
2.search-scope {
3  position: absolute;
4  top: calc(var(--search-title-h) + var(--search-form-h) + 4px);
5  /* ... */
6}
7.search-shell .pagefind-ui__drawer {
8  margin-top: calc(var(--search-scope-h) + 8px);  /* 為 scope 讓位 */
9}

scope 不在 svelte 管轄區、永遠不被清；視覺位置靠 absolute + drawer 的 margin-top 共同決定。

CSS 達成視覺位置的設計工具

工具 1：Absolute + 容器 relative

把客製 UI 設 position: absolute、容器設 position: relative 當定位基準。

1.search-shell { position: relative; }
2.search-custom { position: absolute; top: ...; left: ...; }

客製 UI 跟 framework 元素脫離 layout flow、各自獨立。

工具 2：Margin spacer 推開 framework 元素

要在 framework 元素之間插入空間放客製 UI、改 framework 元素的 margin / padding 推出空間：

1.framework-element { margin-top: var(--custom-height); }
2.custom-ui { position: absolute; top: 0; height: var(--custom-height); }

framework 元素留出空間、客製 UI 浮在空間上。

工具 3：Grid 容器讓 framework 元件當 grid item

1.search-shell {
2  display: grid;
3  grid-template-rows: auto auto 1fr;
4}
5.search-shell > .search-scope { grid-row: 2; }
6.search-shell > #search { grid-row: 3; }

把 framework 元件當 grid 的一個 item — grid 控制 layout、framework 不知道有 grid 在外層、繼續管它的子樹。

工具 4：用 CSS variables 共享尺寸

framework 元素的尺寸需要參考客製 UI 時、用 CSS variable 傳遞：

1:root { --custom-height: 60px; }
2.framework-element { margin-top: var(--custom-height); }
3.custom-ui { height: var(--custom-height); }

或用 ResizeObserver 量測寫回 variable（#27 runtime 量測模式統一）。

設計取捨：客製 UI 的位置選擇

四種做法、各自機會成本不同。這個專案選 A（邊界外 + CSS）當預設、其他做法在特定情境合理。

A：framework 邊界外 + CSS 視覺定位（這個專案的預設）

機制：客製 UI 放在 framework 元件的 sibling 位置、用 CSS absolute / grid / margin spacer 達成視覺位置
選 A 的理由：跟 framework reconciliation 完全解耦、命運由自己決定、升級不影響
適合：絕大多數需要在 framework UI 旁 / 上 / 下加客製內容的情境
代價：CSS 定位邏輯比 DOM 巢狀複雜、需要正確處理 stacking context / z-index

B：framework 邊界外 + JS 量測位置

機制：用 ResizeObserver 量 framework 元素的 bounding rect、JS 算出客製 UI 該擺哪
跟 A 的取捨：A 用 CSS 表達靜態關係、B 處理 runtime 才知道的尺寸；B 多一層 JS、但能達成 CSS 表達不出的精確定位
B 比 A 好的情境：客製 UI 位置依賴 framework 元件的 runtime 尺寸（內容換行、字型變化）

C：framework 邊界內注入

機制：JS 把客製 element 直接 appendChild 到 framework 子樹內
跟 A 的取捨：C 看似省事（少一層 wrapper）、實際把客製命運綁在 framework reconciliation 上
C 才合理的情境：該 framework 子樹確認「不會被 reconcile」（極罕見、需要讀框架 source 確認）
代價：客製可能在任何 patch 時消失、需要 MutationObserver 補打、跟渲染週期賽跑

D：Fork framework source

機制：fork 整個 framework、改 reconciliation 行為讓它認得我們的客製
成本特別高的原因：每次升級都要重新 merge、客製永久綁在 fork 版本
D 才合理的情境：framework 已停止維護、且客製需求超過所有其他選項

不該套用「邊界外」的情境

A 是預設、但不是萬靈丹：

情境	為什麼不適合 A
客製內容必須在 framework 元件的內部視覺脈絡內（共享 inline flow）	Absolute 跳出 flow、達不到 inline 的視覺效果
Framework 元件本身就是要客製化（改 row、改 cell）	動的是 framework 本身、不是「在旁邊加東西」
Framework 提供了官方擴展介面（slot、render prop）	用官方介面更穩、不需要邊界外 hack
客製需要訪問 framework 的內部 state	邊界外的客製跟內部 state 隔離、訪問成本高

核心判準：客製是「在 framework 旁邊加東西」還是「改 framework 本身」？前者用本策略、後者另想辦法。

跟其他原則的關係

抽象層原則	關係
#45 跟外部組件合作的層次	「邊界外 + CSS」是「不要挖 framework 內部」的具體應用 — 客製貼著外部介面（DOM sibling）做、不挖內部
#42 2 次門檻	第 1 次注入失敗（被清掉）= 第 2 次該換策略到邊界外、不該繼續嘗試「換種方式注入」
#13 JS 操作 framework 元件：邊界辨識與安全規則	互補關係 — 本篇處理「客製 UI 該放哪」、#13 處理「framework 元件本身要動時怎麼動」

判讀徵兆

訊號	該怎麼處理
注入 framework DOM 的元素在使用者互動後消失	把該元素搬出 framework 邊界、用 CSS 控制視覺位置
客製 UI 在 framework 更新後 attribute 被 revert	客製 UI 不該在 framework 內、wrapper 在外、attribute 套 wrapper
看不出哪些 DOM 是 framework 管的	讀 framework 的 mount root、從那裡往內都是管轄區
Stacking context 衝突、z-index 失靈	確認 absolute 的 containing block 是預期的 relative parent
Framework 元件位置不固定、客製 UI 對不齊	用 ResizeObserver 量 framework 元素、寫回 CSS variable

核心原則：客製 UI 的存活壽命 = 「離 framework 管轄區多遠」。最遠 = 永遠不被清；注入內部 = 隨時可能消失。預設選邊界外、不要為了「省一層 wrapper」進入 framework 領地。