JavaScript on Tarragon

JS/TS 平台適配

Fri, 19 Jun 2026 00:00:00 +0000

瀏覽器環境中的監控 SDK 面臨三個平台特有的限制：跨域請求被 CORS 攔截、Service Worker 可以攔截和修改請求、SPA 的路由變換不觸發頁面載入事件。每個限制需要 SDK 在設計層面做適配。

CORS 限制

瀏覽器的同源政策限制網頁向不同 origin 發送請求。SDK 的 HTTP POST 送到 collector endpoint 時，如果 collector 和網頁不在同一個 origin（protocol + domain + port 都相同），瀏覽器會先發送 preflight OPTIONS 請求確認 server 允許跨域存取。

SDK 端的適配：

使用 navigator.sendBeacon(url, data) 代替 fetch / XMLHttpRequest。sendBeacon 不受 CORS 限制（瀏覽器對 beacon 請求不做 preflight），且在頁面 unload 時仍能可靠送出 — 適合 close flush 場景。

sendBeacon 的限制：payload 大小有上限（通常 64KB），不能自訂 Content-Type header（固定為 text/plain 或 application/x-www-form-urlencoded），沒有回應 — 送出後無法知道 server 是否收到。

如果需要 fetch（例如需要讀取回應或送出大 payload），collector 端需要設定 CORS header：Access-Control-Allow-Origin、Access-Control-Allow-Methods: POST、Access-Control-Allow-Headers: Content-Type。

Service Worker 攔截

Service Worker 可以攔截頁面發出的所有 HTTP 請求（包括 SDK 的 POST 請求到 collector）。如果應用程式的 Service Worker 有 cache 策略（cache-first、network-first），SDK 的監控請求可能被快取而非送到 collector。

SDK 端的適配：

在 fetch 請求中加 cache: 'no-store' 防止 Service Worker 快取監控請求。或在請求 URL 加唯一的 query parameter（?_t=timestamp）讓每次請求的 URL 都不同，繞過 cache 比對。

如果 SDK 本身提供 Service Worker 模組（在 Service Worker 內攔截 error），需要注意 Service Worker 的生命週期和頁面不同 — Service Worker 可能在頁面關閉後仍在執行，也可能在空閒時被瀏覽器終止。

SPA 路由變換偵測

Single Page Application 的路由變換（React Router、Vue Router、Angular Router）不觸發頁面重新載入。從監控角度看，使用者在不同「頁面」之間切換，但 window.onload 只在首次載入時觸發一次。

SDK 需要偵測 SPA 路由變換來記錄 lifecycle.view.change 事件。偵測方式：

History API 攔截：monkey-patch history.pushState 和 history.replaceState，在呼叫前後記錄路由變換。同時監聽 popstate 事件處理瀏覽器的上一頁/下一頁。

MutationObserver：監聽 DOM 變化偵測頁面內容更新。但 MutationObserver 觸發頻率高，需要 debounce 並搭配 URL 變化檢查，避免把 DOM 微調誤判為路由變換。

框架特定的 hook：如果 SDK 提供框架整合套件（React / Vue / Angular plugin），可以用框架的 router 事件（useNavigate hook、router.afterEach guard）直接取得路由變換資訊，比 monkey-patch History API 更可靠。

JS/TS 的平台限制理解後，其他平台各有各的挑戰 — Flutter 平台適配處理 isolate 和 platform channel 的問題。所有平台共同面對的 timestamp 一致性問題（時區、精度、clock drift）在獨立章節中展開。SDK 的跨平台公開 API 設計見模組三 SDK 公開 API。

客製 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 領地。

排版精度的工具選擇：CSS-only vs JS-assisted

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

核心原則

CSS 處理 build-time 可決定的 layout、JS 處理 runtime 才知道的尺寸與 stateful DOM 移動。 邊界誤判：硬要 CSS 解決 runtime 問題會反覆試錯；硬要 JS 解決 layout 問題會跟 framework 渲染競爭。

選擇問題簡化為兩問：

這個值在 build time 能定下來嗎？能 → CSS；不能 → JS 量測寫回 CSS 變數。
這個 DOM 變動是 framework 管的嗎？是 → 不要動；不是 → JS 可動。

為什麼分工是必要的

商業邏輯

CSS 的設計假設是「規則在 build time 決定、瀏覽器渲染時應用」。CSS 沒有 reactive 機制 — 沒辦法「等元素渲染完才知道高度然後對齊」。

JS 的設計假設是「runtime 可以讀寫 DOM 與 style」。JS 可以在元件渲染後量測尺寸、可以隨 viewport 變動 reparent 節點。

用錯工具不只「不太優雅」、是直接做不到。要 CSS 解決動態尺寸只能寫 magic number（猜的）；要 JS 解決靜態 layout 寫了一堆 imperative 代碼還可能跟 framework 衝突。

這次任務的工具分配

CSS 處理的部分

任務	CSS 寫法	為什麼用 CSS
H1 / search input 的固定高度	`height: 64px` 寫死	Build time 可決定的設計 token
搜尋頁主欄置中、breakpoint 切換	`@media (min-width: 1400px)`	純宣告式 layout
Filter sidebar absolute 定位	`position: absolute; right: calc(100% + 2rem)`	靜態定位關係
Drawer 留出 scope 空間	`margin-top: calc(var(--search-scope-h) + 8px)`	引用變數的 calc

JS 處理的部分

任務	JS 寫法	為什麼用 JS
量測 scope 高度寫回 CSS 變數	ResizeObserver	Runtime 才知道（字型、換行）
Filter sidebar 切換到 mobile drawer	matchMedia + appendChild	跨 viewport 的 stateful DOM 移動
Scope filter（regex 比對標題 / 內文）	event listener + setProperty	純 runtime 邏輯、無 build time 解
Scope UI 寫死值與量測值的橋	`style.setProperty('--search-scope-h', ...)`	JS 寫回讓 CSS 用

兩問判斷法

問 1：這個值在 build time 能定下來嗎

值	Build time 知道嗎	工具
設計 token（spacing、typography scale）	是	CSS 變數寫死
元件固定尺寸（icon size、button height）	是	CSS height / width
響應式 breakpoint	是（設計決定）	`@media` query
動態文字塊高度（受字型 / 換行）	否	JS ResizeObserver
元件位置（隨 viewport 變化）	否	JS getBoundingClientRect

知道 → CSS 解。不知道 → JS 量測寫回 CSS 變數、CSS 從變數計算。

問 2：這個 DOM 變動是 framework 管的嗎

變動	Framework 管	工具
自家 DOM 內元素加 / 移 / 改	否	JS 自由動
Framework 元素的整節點 reparent	不管內部	JS 可搬
Framework 元素內部的子節點	是	不要動
Framework 元素的 attribute	視 framework 而定	通常不要動

是 → 不要動，用 CSS 視覺解。不是 → JS 可動。

內在屬性比較：兩種工具的特性

屬性	CSS-only	JS-assisted
知識成本	低（語言簡單）	中（需要 DOM API）
執行時機	渲染前 / 樣式重新計算	DOMContentLoaded 後 / 事件觸發
是否阻塞首次渲染	是（CSS 是 render-blocking）	否（async）
Framework 衝突風險	無	有（若動到 framework 管的 DOM）
可維護性	高（純 declarative）	中（imperative）
跨瀏覽器一致性	高（CSS 標準清楚）	中（API 差異）

優先 CSS — declarative、無 framework 衝突、首次渲染就生效。JS 補 CSS 做不到的部分。

邊界誤判的兩種失敗

CSS 解 runtime 問題

例：用 CSS magic number 寫死 scope-h（猜 56px），實際渲染 73.5px、對齊壞掉。

修法：認知到「scope-h 是 runtime 才能知道的值」、改用 ResizeObserver 量測寫回 CSS 變數。

JS 解 framework-managed layout

例：用 JS appendChild 把 scope UI 注入 .pagefind-ui 內、Svelte 重繪時清掉。

修法：認知到「.pagefind-ui 是 framework 邊界內」、改用 CSS absolute 把 scope 浮在外部。

設計取捨：CSS / JS 工具分配策略

四種做法、各自機會成本不同。這個專案以 A（CSS-first、JS 透過變數補）為主、其他做法在特定情境合理。

A：CSS-first、JS 透過 CSS 變數補 runtime 值（這個專案的預設）

機制：CSS 處理 build time 可決定的 layout、JS 量測 runtime 值寫回 CSS 變數、CSS 從變數計算
選 A 的理由：CSS 是 declarative 不阻塞首次渲染、跟 framework 不衝突；變數是 JS-CSS 介面、單向資料流
適合：絕大多數客製情境
代價：需要明確分辨「值能在 build time 定下來嗎」、JS 寫法要是「寫回變數」而不是「直接改 inline style」

B：純 CSS-only（無 JS）

機制：純宣告式、不寫 JS
跟 A 的取捨：B 完全無 JS 維護成本、A 多一層 JS；但 B 對 runtime 才知道的尺寸（內容動態）束手無策
B 比 A 好的情境：所有值都能 build time 確定、layout 完全靜態

C：JS-imperative layout（每次重算）

機制：JS 監聽變動、每次重新計算所有元素位置、寫 inline style
成本特別高的原因：imperative 代碼難維護、首次渲染慢（要等 JS 跑）、跟 framework 渲染衝突
C 才合理的情境：CSS 表達不出的複雜 layout（極罕見、現代 CSS 已涵蓋大多數）

D：CSS magic number 估算 runtime 值

機制：CSS 內寫死「應該差不多」的值（不量測）
跟 A 的取捨：D 看似省 JS、實際對齊在邊界情境（字型 / theme）必壞
D 是反模式：「runtime 才知道的值」用 CSS 估算是錯誤工具選擇 — 對齊在邊界情境（字型 / theme）必壞

判讀徵兆

訊號	工具誤用方向	修正動作
CSS 寫了 magic number、改字型後對不齊	用 CSS 解 runtime 問題	量測該值、改 ResizeObserver 寫回變數
JS 寫了 100+ 行做 layout	用 JS 解靜態 layout 問題	退回 CSS、用 grid / flex / absolute 達成
JS 改 framework DOM 後，framework 更新就失效	JS 動到 framework 管的領域	改用 CSS 視覺定位、不動 framework DOM
Inline style 散落多處難 debug	JS 直接寫 style 而非透過變數	重構成「JS 寫 CSS 變數、CSS 從變數計算」

核心原則：選工具不是品味問題、是「值能不能在 build time 定下來」「DOM 是不是我管」兩個技術問題的答案。問清楚再選。

JS 操作 framework 元件：邊界辨識與安全規則

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

核心原則

JS 操作 framework 元件前先界定邊界、選對應的安全規則執行。 邊界 = 契約 = 安全範圍。整節點搬遷安全、改節點內部不安全、改節點 attribute 是灰區。每類操作有對應的安全規則 — 不是「能不能動」、是「動了之後 framework 會不會 revert」。

本篇焦點：framework 元件本身需要動時的安全規則。「客製 UI 該放哪」由 #5 客製 UI 留 framework 邊界外處理 — 預設應該完全不動 framework、需要動時才參考本篇。

為什麼邊界要先界定

商業邏輯

每個元件（自家或 framework 提供）有「對外契約」與「內部實作」。對外契約包括：

契約類型	內容
DOM identity	哪些 class / id / attribute 是穩定的
State 來源	元件內部 state 由誰寫、何時改
渲染週期	元件何時重繪、重繪時影響哪些 DOM
對外介面	提供哪些 props / events / API hooks

JS 操作前不知道這些 = 黑箱操作。動了什麼、會觸發什麼、誰會被影響、不可預測。

邊界宣告的格式

開始 JS 操作之前、寫一段註解或 mental note：

1動什麼：filter-panel 的 parent
2邊界：filter-panel 整個節點 OK，內部子節點屬於 pagefind 管
3State：checkbox 勾選狀態存在 panel 子節點上、由 pagefind 維護
4動作：appendChild 整節點 reparent
5為什麼安全：節點 identity 不變、pagefind 在下次 patch 時看到節點還在

這段宣告把「動什麼」「不能動什麼」「為什麼安全」說清楚 — 不是儀式、是強迫自己想清楚再動。

三類操作的安全度

從最安全到最不安全：

1. 整節點 reparent（安全）

把 framework 管的整個節點搬到別處 — 節點 identity 不變、framework 在下次 patch 時仍認得它。

1// 安全 — 整節點搬位置
2sidebar.appendChild(filterPanel);
3drawer.insertBefore(filterPanel, drawer.firstChild);

2. 改節點內部子節點（不安全）

在 framework 管的節點內 appendChild / removeChild / 改子節點屬性 — framework 會 revert。

1// 不安全 — 在 framework 子樹內加東西
2filterPanel.appendChild(myCustomDiv);
3filterPanel.querySelector('.x').setAttribute('data-y', 'z');

3. 改節點自身的 attribute / inline style（灰區）

改 framework 管的節點本身的 attribute、看 framework 是否認為這屬於 reactive：

1// 灰區 — 看 framework 怎麼處理
2el.style.display = 'none';
3el.classList.add('my-state');
4el.setAttribute('aria-hidden', 'true');

下節展開三類各自的設計細節。

整節點 reparent：為什麼安全、怎麼做才安全

為什麼安全

Framework 的 reconciliation 通常以「節點 identity」為依據 — 同一個節點在哪裡不重要、節點存不存在才重要。

把 .pagefind-ui__filter-panel 從 drawer 移到外部 aside：

Framework 看到	反應
節點還在（identity 沒變）	繼續更新它的內部
節點的 parent 變了	Framework 不關心 — parent 不在 component tree 內
節點內的 children 不變	Framework 不需要重建

reconciliation 不會因為「位置變了」而重建節點 — 重建只發生在「節點消失了 + 新節點出現」的情境。

安全 reparent 的 do / don’t

Do	Why
`parent.appendChild(node)` 整節點搬	identity 保留
`parent.insertBefore(node, ref)` 整節點搬到特定位置	identity 保留
搬之前 `node.cloneNode(true)` 為複本（如果要保留原位）	複本是新 identity、原節點仍由 framework 管
搬完後不動 node 內部	framework 繼續正常更新

Don’t	Why
`parent.appendChild(node.firstChild)` 搬 framework 子節點	把節點抽出原 parent、framework 認為消失了
`node.innerHTML = node.innerHTML` 重設內部	創造一堆新 identity、framework 認不得
搬完後在 node 內 appendChild 加東西	加的東西不在 framework 認知中、被清
搬完後改 node 內子節點的 text / attribute	framework 在下次 patch 時 revert

核心規則：搬節點 = 操作 node 本身；不要操作 node 的 children。

跟 framework reactivity 的對齊

某些 framework 對節點的「內部值」是 reactive 的（例如的 value），改了會被 reconcile 回來。對這類屬性：

屬性類型	操作策略
Reactive value（input.value、textContent）	透過 framework API 改、不要直接改 DOM
純展示 attribute（class、aria-* 多數情境）	直接改 DOM 通常 OK、但仍是灰區（見下節）
Layout-relevant style（display、position）	直接改 DOM 通常 OK、可能需要 fail-safe

不確定某屬性是否 reactive：讀框架 source / 文件確認、或加 fail-safe 防意外。

改節點內部：為什麼不安全、有什麼例外

為什麼不安全

在 framework 管的節點內 appendChild / removeChild — framework 不認得這些操作的結果、下次 patch 時：

Framework 比對 component tree 的目標狀態
看到 DOM 多了不該有的節點 → 移除
或看到 DOM 少了該有的節點 → 重建

我們手動加的節點屬於前者、被移除。我們手動移除的子節點屬於後者、被重建（且重建的 identity 不同）。

唯一的例外：靜態元件 + 確認 patch 不重設

如果該 framework 子樹「初次 mount 後不再 patch」、改內部可能安全。但這是框架實作細節、隨版本可能變動。

例：當前 pagefind 的 filter 順序在初次 mount 時生成、後續 patch 不重排 — 所以 reorder filter 子節點實際安全。但這是「當前版本碰巧」、不是「框架保證」。

操作規則：不要依賴「碰巧安全」。如果必須改內部、加 MutationObserver 監聽 framework 是否 revert、必要時補打。

改節點 attribute / inline style：灰區的 fail-safe 設計

為什麼是灰區

Framework 通常不主動管理節點的 inline style 與非 reactive attribute — 但「通常」不是「永遠」。某些 framework 會在 patch 時把 inline style 重設、或把 attribute 跟 component state 強制同步。

Fail-safe 工具 1：`!important` 提升優先級

1el.style.setProperty('display', 'none', 'important');

important 把 inline style 的優先級提升 — 即使 framework 套了同屬性的低優先 style、也蓋不過。

Fail-safe 工具 2：MutationObserver 補打

1function reapply() {
2  el.style.setProperty('display', 'none', 'important');
3}
4reapply();
5new MutationObserver(reapply).observe(parent, {
6  childList: true, subtree: true,
7});

Framework 在重繪後可能把 element 替換成新的 — observer 監聽到變動、立刻補套 style。

詳細設計（observer 範圍 / 觸發頻率 / self-mutation 處理）由 #29 MutationObserver 範圍與觸發頻率處理。

Fail-safe 工具 3：CSS class toggle 取代 inline style

1// 不用 inline style
2el.classList.toggle('is-hidden');

1/* CSS 內定義行為、layered CSS 不需要 important */
2@layer base {
3  .is-hidden { display: none; }
4}

詳細展開由 #28 class toggle 取代 important 處理。

選擇順序：能用 class toggle 就用（最乾淨）；framework 會清 class 才用 inline + important + observer。

這次任務的邊界辨識實例

四個 JS 操作場景、各有不同邊界：

場景	動的對象	操作類別	安全度	處理
把 filter-panel 從 drawer 搬到 sidebar	整節點 reparent	1（安全）	高	直接搬、不動內部
Reorder type / tag filter	filter 子節點順序	2（不安全）	中 — 視 framework 而定	確認框架不 reset 順序、加 observer 防護
注入 scope UI	自家新元件	N/A（自家領域）	高	放 framework 邊界外（#5）
Filter 結果 hide / show	pagefind 結果元素的 display	3（灰區）	中	inline + important + observer 補打

每個場景操作前的 mental check：「這是哪一類？該用什麼安全規則？」

設計取捨：操作 framework 元件的策略

四種策略、各自機會成本不同。預設追求「最高安全度的方式達成需求」、成本太高再降級。

A：完全不動 framework、客製留邊界外（這個專案的預設）

機制：把客製 UI 放在 framework sibling 位置、用 CSS 達成視覺效果
選 A 的理由：跟 framework 完全解耦、命運自主
適合：需求是「在 framework 旁加東西」（多數情境）
代價：CSS 定位可能複雜
詳細：#5 客製 UI 留 framework 邊界外

B：整節點 reparent

機制：把 framework 管的節點搬位置、不動內部
跟 A 的取捨：A 不動 framework、B 搬 framework 元件本身；B 換到的是「能改變 framework 元件位置」、付出的是「節點內部仍由 framework 管、外部行為仍可能變」
B 比 A 好的情境：framework 元件位置決定權需要奪回（例如 sidebar 切換）

C：改節點 attribute + fail-safe

機制：改 inline style / class、加 important + observer 補打
跟 A/B 的取捨：A 不碰 framework、C 介入 framework 元件本身的視覺行為；C 比 A 侵入性高、但比直接改內部安全
C 比 B 好的情境：需要的不是搬位置、是改顯隱 / 顏色 / state

D：改節點內部（最後手段）

機制：在 framework 子樹內 appendChild、改子節點屬性
成本特別高的原因：跟 framework reconciliation 直接競爭、bug 不可預測、升級可能徹底打破
D 才合理的情境：當前 framework 確認「該子樹不 reconcile」+ 升級時會重新驗證 — 通常不值得

邊界宣告的實踐

寫成 JSDoc 或 inline 註解

 1/**
 2 * 把 .pagefind-ui__filter-panel 從 drawer 搬到外部 sidebar。
 3 *
 4 * 邊界：
 5 *   - 動：filter-panel 整節點的 parent
 6 *   - 不動：filter-panel 內部子節點（由 pagefind 管）
 7 *   - State：checkbox 勾選由 pagefind 維護、跟著節點走
 8 *
 9 * 為什麼安全：節點 identity 不變、pagefind 在下次 patch
10 * 時看到節點還在、繼續更新內部。
11 */
12function place() {
13  if (mql.matches) sidebar.appendChild(filter);
14  else drawer.insertBefore(filter, drawer.firstChild);
15}

註解是給未來的自己 / 同事看的「契約備忘」 — 看到操作時知道為什麼安全。

跟其他原則的關係

抽象層原則	關係
#45 跟外部組件合作的層次	本篇是「邊界內 DOM 層」操作的具體規則 — 接受要進入這層、用本篇規則限制傷害
#43 最小必要範圍	操作範圍越小越安全 — 整節點 reparent 比改內部範圍小、改 attribute 比改子樹範圍小
#5 客製 UI 留邊界外	互補關係 — #5 處理「不動 framework 的策略」、本篇處理「必須動 framework 時的安全規則」

判讀徵兆

訊號	邊界問題	第一個該檢查的事
JS 操作後 framework 行為異常	動到內部子節點	確認操作只動「整節點 identity」、不動內部
Inline style 在某些互動後消失	動到 framework 管的 attribute	加 observer 補打、或改用 CSS class toggle
reparent 後 framework state 重置	整節點移動但 framework 看作刪除	確認框架對節點 identity 的追蹤機制（少數框架不靠 identity）
某些 querySelector 命中不該命中的元素	Selector 範圍超過自家元件	把 query 限縮到 self 元件根節點下（#14 selector 精準度）
「再加一段防禦邏輯應該就好了」第 2 次	整體策略可能該換層級（從 D 升到 C 或 B）	#42 2 次門檻、考慮換策略

核心原則：JS 動 framework 元件前、邊界先界定、選對應的安全規則。預設追求「完全不動 framework」(A)、必須動時用層級遞減的策略（B / C / D）— 每往下一層付的是「跟 framework 競爭」的成本。

Selector 精準度：讓 query 只命中你想要的元素

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

核心原則

JS 的 DOM query 從具體開始、發現不夠用再放寬。 Selector 涵蓋「最少必要範圍」、避免誤命中其他元素、避免未來頁面結構變動讓 query 撈到不該撈的東西。精準度有三個收斂維度：起點（從哪開始找）、範圍（找多深）、過濾（哪些不要）— 三者一起設計才完整。

為什麼精準度是 default

商業邏輯

DOM selector 的範圍越寬、被誤命中的可能性越高。寬泛 selector 像「網撈」 — 當下頁面只有一個目標元素時看不出問題、未來頁面結構變動（加第二個同類元件、加 demo 區塊、加 widget）就壞。

精準度的成本是「寫 selector 時多想一點」、收益是「行為可預測、不會被未來變動打破」。這不是優化、是 sanity 防線。

寬泛 selector 的失敗模式

失敗模式	表現	根因
跨元件誤命中	該動的動了、不該動的也動了	沒指定 ancestor scope
同名 class 誤命中	demo 區塊 / 文檔截圖也被處理	沒過濾「處於展示用途」的元素
未初始化元素被處理	元件還沒 mount 完就被操作	沒過濾「狀態未就緒」的元素
已處理元素重複處理	apply 被 observer 觸發又處理一次	沒標記「已處理」

四種失敗都來自「query 範圍 > 真實需要的範圍」。從具體開始就避免。

三層收斂維度

Selector 精準度不是單一參數、是三個維度的組合。每個維度都該設計、不能只想其中一個。

維度 1：起點（從哪個 root 開始找）

核心定義：query 的起點決定「最大可能範圍」。從 document 起 = 全頁面；從元件根起 = 子樹內。

1// 寬：全頁面搜尋
2document.querySelector('.pagefind-ui__result');
3
4// 收斂：從元件根開始
5var shell = document.querySelector('.search-shell');
6shell.querySelector('.pagefind-ui__result');

從元件根開始等於把 selector 的作用範圍收斂到「我管的子樹」 — 即使未來頁面其他地方出現同名元素、跟我無關。

起點選擇的決策：

起點	適用情境
`document`	確定全頁只有一個目標、且未來不會增加同類
元件根（變數存好）	一般情境（推薦預設）
函式參數傳入根	同頁面有多個元件實例、各自獨立 setup
事件 `closest` 反向找根	動態多實例、用事件驅動

多元件 setup pattern：

1function setupSearchShell(shell) {
2  var ui     = shell.querySelector('.pagefind-ui');
3  var input  = shell.querySelector('.pagefind-ui__search-input');
4  var drawer = shell.querySelector('.pagefind-ui__drawer');
5  // ... 其他 setup
6}
7
8document.querySelectorAll('.search-shell').forEach(setupSearchShell);

頁面有 N 個 shell、自動 setup N 次、各自獨立。當前只一個也適用、未來加更多無痛 — 這是「起點當參數」帶來的擴展性。

例外處理：當目標元素不在元件子樹內（例如同層的 sibling），保留 document.querySelector 但加註解說明：

1// slot 是 main 的子節點、跟 shell 同層、不能從 shell 找
2var slot = document.querySelector('.search-filter-slot');

註解讓未來維護者知道這是「明知故為」的例外、不是疏忽。

維度 2：範圍（找多深）

核心定義：起點確定後、要找直接子、特定層、還是任意深度。

querySelector 預設找任意深度 — 大部分情況沒問題、但結構穩定時可以更精準：

1// 預設：任意深度
2shell.querySelector('.pagefind-ui');
3
4// 限縮：只找直接子
5shell.querySelector(':scope > .pagefind-ui');
6
7// 限縮：只找特定層
8shell.querySelector(':scope > div > .pagefind-ui');

:scope 在 querySelector 內表示 query 的起始元素 — 配合 > 就能精準匹配「直接子」。

範圍選擇的決策：

範圍	適用情境
任意深度（預設）	結構可能變動、目標可能搬位置
直接子 `:scope > X`	結構穩定、避免深層誤命中
特定路徑 `:scope > A > B`	結構非常穩定、想要結構變動立即察覺

選太寬未來誤命中、選太窄未來結構微調就壞 — 預設選任意深度、結構穩定的關鍵 query 才用 :scope >。

維度 3：過濾（哪些元素不要）

核心定義：起點 + 範圍確定後、可能還是命中過多 — 用 attribute filter 與否定 selector 排除不要的。

1// 寬：所有 result
2shell.querySelectorAll('.pagefind-ui__result');
3
4// 過濾：只取已 rank 過的（排除初始化中的）
5shell.querySelectorAll('.pagefind-ui__result[data-pagefind-rank]');
6
7// 過濾：排除已處理過的
8shell.querySelectorAll('.pagefind-ui__result:not([data-scoped])');

過濾技巧：

技巧	用法
Attribute filter	`[data-state="ready"]` 只取狀態就緒的
`:not()` 排除	`:not([data-scoped])` 排除已處理
Attribute exists	`[data-pagefind-rank]` 只取有特定屬性的
處理後標記	處理完 `el.setAttribute('data-scoped', 'true')` 避免重複處理

「處理後標記」是 idempotency 工具：apply 函式可能被多次呼叫（observer 觸發、event 觸發），標記 + :not() 過濾確保每個元素只處理一次。

三維度的組合範例

完整的精準 selector 設計：

 1var shell = document.querySelector('.search-shell');           // 維度 1：起點
 2if (!shell) return;
 3
 4var results = shell.querySelectorAll(                          // 維度 2：任意深度
 5  '.pagefind-ui__result[data-pagefind-rank]:not([data-scoped])'  // 維度 3：過濾
 6);
 7
 8results.forEach(function (el) {
 9  // ... 處理
10  el.setAttribute('data-scoped', 'true');                      // 處理後標記
11});

每個維度都有意識地選擇 — 不是把所有預設值疊一起。

內在屬性比較：四種 selector 設計

設計	誤命中風險	未來結構變動的容忍度	多元件支援
`document.querySelector('.x')`	高	低 — 任何同名出現就壞	否（只取第一個）
`shell.querySelector('.x')`	低	中 — shell 內變動才影響	部分
`shell.querySelector(':scope > .x')`	最低	低 — 結構微調就壞	部分
起點當參數 + 過濾 + 標記	最低	高 — 顯式聲明所有假設	完整

推薦：起點當參數 + 過濾。:scope > 只在「結構保證穩定」的關鍵 query 用。

進階技巧

1. 把元件根存成變數一次

1var shell = document.querySelector('.search-shell');
2if (!shell) return;
3// 之後所有 query 都從 shell 開始

避免每次 query 都重新從 document 找元件根 — 一是效能（小）、二是 query 範圍仍維持在 shell 內。

2. 用 closest 反向找根

1function getShell(el) {
2  return el.closest('.search-shell');
3}
4
5document.addEventListener('click', function (e) {
6  var shell = getShell(e.target);
7  if (!shell) return;
8  // 在這個 shell 內處理
9});

事件委派 + closest 適合「多元件實例 + 動態事件處理」 — 各 shell 不需要各自綁 listener、共用一個 listener 用 closest 區分。

3. 起點不存在時提早 return

1var shell = document.querySelector('.search-shell');
2if (!shell) return;

頁面可能沒有 shell（不是搜尋頁），所有後續 query 都會失敗。提早 return 比後續一連串 null check 乾淨。

4. WeakMap 替代 attribute 標記

當不想污染 DOM attribute 時、用 WeakMap 紀錄已處理的元素：

1var processed = new WeakMap();
2
3shell.querySelectorAll('.pagefind-ui__result').forEach(function (el) {
4  if (processed.has(el)) return;
5  // ... 處理
6  processed.set(el, true);
7});

WeakMap 在元素 GC 時自動清理、不留下 DOM 痕跡。適合短生命週期的 idempotency。

設計取捨：起點選擇

Selector 的「起點」有四種做法、各自機會成本不同。這個專案選 B（元件根存變數）當預設、其他做法在特定情境也合理。每張卡片獨立展開該做法的設計細節。

A：`document.querySelector` 全文件搜

機制：每處 query 都從 document 開始、靠 class name 唯一性命中目標
適合：原型階段、demo 程式碼、確定全頁只有一個目標且未來不會變
代價：未來頁面結構變動（加同類 widget、加 demo 區塊）就壞、且失敗模式是安靜地操作錯元素、不報錯
選 A 的時機：「快速看會不會動」的探索期

B：元件根存變數、之後從變數 query（這個專案的預設）

機制：var shell = document.querySelector('.search-shell') 一次、之後所有 query 用 shell.querySelector(...)
選 B 的理由：當前頁面只有一個 shell、未來可能加（站內搜尋 widget、相關搜尋）— 用變數隔離成本低、提早預防
適合：一般客製情境、預期未來結構可能擴展
代價：多一個變數、多一次 query;函式內邏輯變得依賴外部變數

C：函式接受元件根當參數

機制：function setup(shell) { shell.querySelector(...) }、外部呼叫 document.querySelectorAll('.shell').forEach(setup)
跟 B 的取捨：B 假設只有一個 shell、C 直接支援多 shell；C 的設計成本前期較高（每函式多一個參數）、但多實例支援是免費的
C 比 B 好的情境：頁面同時有多個 shell（例如多語切換頁面）、或計劃中要重用組件到不同頁面

D：事件 + `closest` 反向找根

機制：監聽全域事件、事件處理時 e.target.closest('.shell') 反向找元件根
跟 B/C 的取捨：B/C 是「初始化時綁定」、D 是「事件發生時動態判斷」— D 適合元件動態出現 / 消失（SPA 路由切換、AJAX 注入）
D 比 C 好的情境：元件實例在 runtime 動態增減、用 mutation observer 補打成本反而更高
代價：事件委派的調試比直接綁定難（不知道事件實際從哪傳上來）

設計取捨：範圍深度

querySelector 預設找任意深度、可以收緊到直接子。三種做法：

A：任意深度（這個專案的預設）

機制：shell.querySelector('.target') — 子樹任何深度都接受
選 A 的理由：結構可能因 framework 升級微調、容忍微調換取維護彈性
代價：深層結構意外多出同名元素時可能誤命中

B：直接子 `:scope > X`

機制：shell.querySelector(':scope > .target') — 只找直接子
跟 A 的取捨：A 容忍結構微調、B 強制結構穩定 — B 帶來「結構變動立即報錯」的早期偵測
B 比 A 好的情境：自家完全控制的結構、想用 selector 失敗當回歸測試訊號

C：特定路徑 `:scope > A > B`

機制：強制一條精確路徑
代價：結構任何微調都壞、維護成本高
C 才合理的情境：寫整合測試的結構斷言、不是 production query

設計取捨：過濾與 idempotency

apply 函式可能被多次觸發（observer / event / 初始化）、過濾保證每元素只處理一次。三種做法：

A：DOM attribute 標記（這個專案的預設）

機制：:not([data-scoped]) 過濾 + 處理後 el.setAttribute('data-scoped', 'true')
選 A 的理由：標記跟著 DOM 元素走、元素被移除時自動清理；標記在 devtools 可見、debug 直接
代價：DOM 上多了一個自家用的 attribute（命名衝突風險小）

B：WeakMap 紀錄

機制：var processed = new WeakMap(); processed.set(el, true)
跟 A 的取捨：B 不污染 DOM、適合「不想留 attribute 痕跡」的場景；A 在 devtools 可見、debug 較直接
B 比 A 好的情境：寫成第三方函式庫、不想對使用者 DOM 加屬性

C：依賴外部呼叫者保證只呼叫一次

機制：apply 內不防護、依賴 init 時只綁一次 listener
成本特別高的原因：observer 觸發 / 事件觸發 / 初始化任一處多呼叫、就產生重複處理 bug；錯誤難以追蹤
C 才合理的情境：apply 本身是 idempotent 的（例如 set class 設成已是的值、無副作用）— 此時不需過濾

判讀徵兆

訊號	Selector 精準度問題	修正動作
多處 `document.querySelector` 同類元素	起點太寬	把元件根存變數、之後 query 從變數開始
同頁加第二個元件實例後行為錯亂	起點 hardcode	改「起點當參數」pattern
Selector 命中了不該命中的元素	範圍 / 過濾不足	加 ancestor scope、或加 attribute filter
Apply 被多次呼叫產生重複處理	沒 idempotency 防線	加 `:not([data-flag])` + 處理後標記
結構微調後 selector 失效	`:scope >` 用得太死	換成任意深度（預設）
事件處理時不知是哪個元件實例	沒反向找根機制	用 `closest`

核心原則：Selector 精準度不是極致最佳化、是 sanity 防線。三維度（起點 / 範圍 / 過濾）一起設計、每個維度都顯式選擇 — 比從寬泛開始一路追 bug 容易得多。

寬 selector（querySelectorAll('.title')）是「便利位置」、窄 selector 是「對齊位置」 — 這個反相關的更高層原則見 #67 寫作便利度跟意圖對齊反相關。

runtime 量測模式統一

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

核心原則

對齊基準上的尺寸值、要嘛統一寫死、要嘛統一 runtime 量測 — 不要混搭。 混搭時某些變化（字型替換、scale 改變、theme 切換）會打破對齊、且問題只在特定情境出現、難以重現。選一邊走到底。

為什麼混搭會不穩

商業邏輯

對齊問題本質是「方程組」 — 每個變數的值都要正確、結果才對。

寫死值的特徵：

來源是 build time 設計決定
變動需要手動改 CSS
假設某個渲染條件成立（特定字型、特定 scale）

量測值的特徵：

來源是 runtime DOM 量測
自動跟著實際渲染走
不依賴特定渲染條件

混搭時的失敗模式：寫死值依賴的渲染條件變了、但量測值跟著變、寫死值沒跟 — 兩者錯位、對齊壞掉。

統一往一邊靠的選擇

統一策略	適合
全部寫死（鎖渲染條件）	設計 token 穩定、組件提供 scale hook 可鎖定
全部量測（runtime 同步）	內容動態、字型 / 排版可能變動

選擇看「願意接受多少不確定性」 — 全寫死要鎖很多條件、全量測要寫多個 ResizeObserver。

這次任務的混搭問題

觀察

對齊基準上四個值的處理：

值	來源
`--search-title-h` (H1)	寫死 64px
`--search-form-h` (input)	寫死 68px、靠 `--pagefind-ui-scale: 1.0` 鎖定
`--search-gap` (drawer 上方)	寫死 20px
`--search-scope-h`	ResizeObserver 量測寫回

混搭：前三個寫死、第四個量測。

判讀

當前情境穩定 — pagefind scale 鎖在 1.0、theme h1 高度可預測。但若：

Theme 升級改 h1 line-height → 寫死 64px 不準
使用者裝置字型不同 → form 內容寬度變動可能間接影響高度
pagefind 升級 input 高度算法 → 寫死 68px 不準

寫死值「假設某些條件成立」、條件變了寫死值就錯。

執行：兩種統一方向

方向 1：全部寫死、鎖更多渲染條件

 1body.page-search {
 2  --search-title-h: 64px;
 3  --search-form-h: 68px;
 4  --search-gap: 20px;
 5  --search-scope-h: 56px;            /* 不再 JS 量測 */
 6  --pagefind-ui-scale: 1.0;
 7}
 8
 9.search-title {
10  height: var(--search-title-h);
11  line-height: var(--search-title-h);
12  margin: 0;                         /* 鎖 H1 margin */
13}
14
15.search-scope {
16  height: var(--search-scope-h);     /* 鎖 scope 高度、超過裁掉 */
17  overflow: hidden;
18}

代價：scope 內容超過時被裁、UI 可能不適合動態內容。

方向 2：全部量測、ResizeObserver 同步所有

 1function measureAll() {
 2  setVar('--search-title-h', titleEl.offsetHeight);
 3  setVar('--search-form-h', formEl.offsetHeight);
 4  setVar('--search-scope-h', scopeEl.offsetHeight);
 5  // gap 是 pagefind drawer 內建、無法從外部量測
 6}
 7function setVar(name, val) {
 8  document.body.style.setProperty(name, val + 'px');
 9}
10
11[titleEl, formEl, scopeEl].forEach(el => {
12  new ResizeObserver(measureAll).observe(el);
13});

代價：JS 多了一層、初始載入時 fallback 值不對齊（直到 JS 跑完）。

內在屬性比較：四種對齊值來源策略

策略	穩定性	維護成本	對動態內容適應
全寫死 + 鎖渲染條件	高 — 條件鎖死後值穩定	低 — 純 CSS	低 — 動態內容超過值會裁
全量測 ResizeObserver	高 — 值跟著實際走	中 — JS 多一層	高
混搭（部分寫死、部分量測）	中 — 邊界 case 壞	中	中
Magic number 估算	低	不適用	低

選擇順序：內容靜態 → 全寫死；內容動態 → 全量測；不要混搭。

鎖定渲染條件的具體技巧

1. 使用組件提供的 scale hook

1.search-shell { --pagefind-ui-scale: 1.0; }

讓組件按我們指定的 scale 渲染、寫死值才有意義。

2. 寫死 H1 height + line-height + margin

1.search-title {
2  height: 64px;
3  line-height: 64px;
4  margin: 0;
5  /* 確保 box height 永遠是 64、不受 font / padding 影響 */
6}

不留任何「看 box-sizing 與 inheritance 決定」的空間。

3. 用 box-sizing: border-box 確保 padding 不影響 box height

1.search-scope {
2  box-sizing: border-box;
3  height: var(--search-scope-h);
4  padding: 8px 16px;
5  /* total height 還是 var(--search-scope-h)、padding 算在內 */
6}

設計取捨：對齊基準上來源機制的選擇

四種做法、各自機會成本不同。預設依內容性質選 — 內容靜態 → A、內容動態 → B、混搭 / 估算永遠不是答案。

本篇是 #44 SSoT 抽象原則在「來源機制統一」這個面向的應用。

A：全寫死 + 鎖渲染條件（內容靜態的預設）

機制：所有對齊基準值用 CSS 變數寫死、同時鎖定相關渲染條件（pagefind scale、H1 line-height、box-sizing）
選 A 的理由：純 CSS 不依 JS、值 build time 確定、改 token 自動跟上
適合：對齊內容靜態、可預測（設計穩定的搜尋頁、文章頁）
代價：需要鎖很多渲染條件（scale / line-height / box-sizing 等）、scope 內容超過寫死值會被裁

B：全量測 ResizeObserver 寫回變數（內容動態的預設）

機制：所有對齊基準值用 ResizeObserver 量、寫回 CSS 變數、其他元素引用
跟 A 的取捨：B 自動跟著實際渲染、A 假設條件穩定；B 多 JS 一層、初始 fallback 值不對齊（直到 JS 跑完）
B 比 A 好的情境：內容動態（字型可能變、theme 切換、跨環境部署）

C：混搭（部分寫死、部分量測）

機制：「主要值寫死、邊界值量測」混合策略
C 是反模式：邊界情境（字型變、scale 變、theme 切換）下兩者錯位、對齊在某些 case 壞、難以重現
看起來吸引人的原因：「主要情境寫死、邊界情境量測」聽起來合理、實際「主要 vs 邊界」判斷不可靠
實際發生的代價：邊界常常變主要、混搭策略下 debug 範圍從「某情境」擴張到「整套是不是錯」

D：Magic number 估算

機制：執行者依感覺給數字、不寫變數、不量測
D 是反模式：任何「沒來源」的值都會在邊界情境爆掉 — 跨情境（字型 / scale / theme）必壞
看起來吸引人的原因：執行者依感覺給數字最快、不用 query 也不用 query DevTools
實際發生的代價：估錯時錯誤被視覺接受、ship 後在邊界情境暴露、信任損失

判讀徵兆

訊號	Refactor 動作
對齊在某些字型 / 主題 / 縮放下壞掉	找出依賴的渲染條件、鎖定或改量測
改了某個 token 要去多處驗證對齊	統一來源（全寫死 or 全量測）
ResizeObserver 量了 A、B 卻寫死	評估 B 是否也需要量、避免混搭
寫死值跟實際渲染差距 > 2px	該值依賴的條件沒鎖、改量測或鎖條件

核心原則：對齊問題的根因常常是「混搭」 — 用統一策略消除這個根因、debug 範圍從「某個情境」縮到「整套策略對嗎」。

混搭通常是便利驅動的結果（每處用最快的方式）、統一策略需要先對齊原則 — 同 #44 SSOT 跟 #67 便利 vs 對齊反相關。

以 class toggle 取代 inline `display: none !important`

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

核心原則

JS 改 DOM 元素的視覺狀態、用 class toggle、不用 inline style.setProperty important hack。 Class toggle 的好處：CSS 規則集中可讀、devtools 看到語意化的 class 名而非神秘 inline style、未來改視覺只動 CSS 不動 JS。

為什麼 class toggle 比 inline style 好

商業邏輯

兩種方式都能達成「JS 控制視覺」、差別在「視覺規則的家在哪」：

方式	視覺規則住址	維護成本
`el.style.display = 'none'`	散在 JS 各處	高 — 改視覺要找 JS、不在 CSS
`el.classList.toggle('is-hidden')` + `.is-hidden { display: none }`	集中在 CSS	低 — 改視覺改 CSS

集中在 CSS = 設計系統的單一來源、devtools Element 面板看 class 知道狀態、code review 容易理解。

!important 的需求消失：只要 CSS Layers 把 vendor CSS 包進低權層、自家 unlayered CSS 自然贏、不需要 important。

何時 inline style 是必要的

情境	inline style 必要
動態值（隨 runtime 計算）	是 — 如 `el.style.top = scrollY + 'px'`
動畫起點 / 終點	是 — `el.style.transform = ...`
切換 boolean 狀態（顯示/隱藏）	否 — 用 class toggle
套用設計系統一致樣式	否 — 用 class toggle

「狀態切換」是 class toggle 的場景、不是 inline style 的場景。

這次任務的重構機會

觀察

Scope filter 用：

1items.forEach(function (el) {
2  var show = scope === 'title' ? re.test(title) : re.test(excerpt);
3  if (show) {
4    el.style.removeProperty('display');
5  } else {
6    el.style.setProperty('display', 'none', 'important');
7  }
8});

setProperty important 是為了壓過 Svelte 重繪可能 reset 的 inline style。CSS Layers 之後、important 不再必要。

判讀

改用 class toggle + layered CSS：

1/* assets/search.css，unlayered（pagefind 在 layer(pagefind) 內） */
2.pagefind-ui__result.is-scope-filtered {
3  display: none;
4}

1items.forEach(function (el) {
2  var show = scope === 'title' ? re.test(title) : re.test(excerpt);
3  el.classList.toggle('is-scope-filtered', !show);
4});

更乾淨：

CSS 規則集中
DevTools Element 面板看到 .is-scope-filtered 就知道為什麼隱藏
JS 邏輯簡化（classList.toggle 一行解兩種狀態）
不需要 !important

執行 prerequisite

要這個 refactor 生效、先做 #24（CSS Layers）：

1@import url("/blog/pagefind/pagefind-ui.css") layer(pagefind);
2
3/* unlayered，自動勝過 pagefind 的所有 specificity */
4.pagefind-ui__result.is-scope-filtered { display: none; }

否則 layered 的 pagefind CSS 可能用 specificity 30 蓋過 .is-scope-filtered（specificity 20）。

內在屬性比較：四種 JS 控制視覺方式

方式	維護成本	DevTools 可讀性	Important 需求
`el.style.display = 'none'`	中 — 規則散在 JS	中 — 看到 inline style	否
`el.style.setProperty('display','none','important')`	高 — important 散在 JS	中	是 — 跟 framework 競爭
`el.classList.toggle('is-hidden')` + CSS	低 — 規則在 CSS	高 — 看 class 知狀態	否（CSS Layers 環境下）
`el.dataset.state = 'hidden'` + `[data-state=hidden]` CSS	低 — 規則在 CSS	高 — attribute 也表達狀態	否

優先選 class toggle（或 dataset） — CSS-first、可讀、可維護。

Class toggle 的命名慣例

用 `is-X` / `has-X` 表狀態

1.is-scope-filtered { display: none; }
2.is-loading { opacity: 0.5; }
3.has-error { border-color: red; }

is- / has- 前綴讓「狀態 class」跟「結構 class」（如 .search-shell）視覺區分、code review 一眼看出哪些是動態狀態。

用 BEM modifier

1.search-result--filtered { display: none; }

BEM 風格也可以、看專案 convention。重點是有規律、不要混雜。

DevTools 可讀性的具體差異

Inline style 視角

1<div class="pagefind-ui__result svelte-j9e30" style="display: none !important;">

DevTools 顯示「inline style 設了 important」 — 但不知道為什麼。要 grep JS 找出哪段邏輯設的。

Class toggle 視角

1<div class="pagefind-ui__result svelte-j9e30 is-scope-filtered">

DevTools 顯示「有 .is-scope-filtered class」 — class 名本身解釋為什麼隱藏。CSS 面板也直接顯示對應規則。

設計取捨：JS 控制視覺狀態的策略

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

A：Class toggle + CSS 規則（這個專案的預設）

機制：el.classList.toggle('is-scope-filtered')、CSS 內定義 .is-scope-filtered { display: none }
選 A 的理由：CSS 規則集中、devtools 看 class 知狀態、改視覺只動 CSS、配 CSS Layers 不需 !important
適合：布林狀態切換（顯示 / 隱藏 / 啟用 / 停用）
代價：需要在 CSS 預先定義 class 規則（多一份 CSS）

B：Inline `style.X = ...`

機制：el.style.display = 'none'
跟 A 的取捨：B 一行 JS、A 需要 CSS 規則；但 B 規則散在 JS 各處、devtools 看到 display: none inline 不知道為什麼
B 比 A 好的情境：runtime 計算的動態值（el.style.top = scrollY + 'px'）— 這類值無法預先寫進 CSS

C：Inline + `setProperty('important')`

機制：el.style.setProperty('display', 'none', 'important')
跟 A/B 的取捨：C 比 B 多 important、為了壓過 framework 重繪 reset 的 inline；但 C 進入 !important 戰、未來新 important 對撞 debug 困難
C 才合理的情境：framework 強制 reset 自家 inline style、且不能用 layered CSS（極罕見）
更好的解：用 #24 CSS Layers 解 specificity 戰、本卡片 A 即可

D：Dataset attribute + CSS attribute selector

機制：el.dataset.state = 'hidden'、CSS [data-state="hidden"] { display: none }
跟 A 的取捨：D 用 attribute 表狀態、A 用 class；D 在「狀態值多種」時更合適（例如 data-state="loading|ready|error"）
D 比 A 好的情境：狀態有多個值（不只 boolean）、需要 CSS attribute selector 表達多分支

判讀徵兆

訊號	Refactor 動作
JS 用 `style.setProperty(..., 'important')`	改用 class toggle、用 CSS Layers 解決 specificity
`el.style.display = 'none'` 散落多處	集中為 `.is-X` class、JS 只 toggle
DevTools 看到 inline style 不知為什麼	改用語意化 class、devtools 看 class 自帶解釋
視覺改動要改 JS（不是 CSS）	Refactor 為 class toggle、視覺改動只動 CSS
改視覺需要對抗 framework reset	用 CSS Layers 把 framework 規則降層、自家規則不需 important

核心原則：CSS 是視覺規則的家、JS 控制狀態 - 兩者透過 class toggle 介面共處、不互相侵入。

Inline style + !important 是「立刻生效」的便利、class toggle 是「樣式留 CSS」的對齊 — 這個反相關的更高層原則見 #67 寫作便利度跟意圖對齊反相關。

MutationObserver 範圍與觸發頻率：監聽最少必要的變動

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

核心原則

MutationObserver 監聽最少必要的變動 — 從「監聽哪個 root」「觀察什麼類型」「多久觸發一次」三維度收斂。 範圍寬會頻繁觸發、option 勾多會在不關心的變動上跑邏輯、apply 自己改 DOM 會引發無限循環。三維度都該顯式設計、不能只丟預設。

為什麼 observer 需要獨立議題

跟 selector 的差異

Observer 與 selector 都涉及「DOM 範圍」、機制完全不同：

維度	Selector	Observer
時機	同步、當下查詢	非同步、回應未來變動
執行頻率	一次或顯式重呼叫	隨 DOM 變動自動觸發
失敗模式	撈太多 / 撈太少	觸發太頻繁 / 漏觸發 / 無限循環
設計重點	起點 + 範圍 + 過濾	監聽範圍 + option + 頻率

把 selector 與 observer 綁同一篇討論會混淆 — 兩者解決的是不同問題、有不同失敗模式、需要不同的設計工具。

Observer 寬範圍的失敗模式

失敗模式	表現	根因
過度觸發	短時間觸發數十次	subtree 太深 + option 太多
在錯時機跑	layout 還沒穩就跑 apply	沒等 framework patch 結束
無限循環	apply 自己改 DOM 又觸發 observer	沒 disconnect/observe 保護
漏掉變動	預期會觸發但沒觸發	option 沒勾對、或 root 選錯

四種都來自「沒精細設計 observer 的監聽形狀」。

三維度收斂

維度 1：監聽哪個 root（範圍）

核心定義：observer 的 root 元素決定「哪些範圍內的變動會被看到」。

1// 寬：監聽整個 .pagefind-ui
2new MutationObserver(apply).observe(ui, { childList: true, subtree: true });
3
4// 收斂：只監聽結果列表
5var results = shell.querySelector('.pagefind-ui__results');
6new MutationObserver(apply).observe(results, { childList: true });

寬範圍把無關變動也帶進來 — pagefind 重繪 input、調整 filter、重排 chip 都會觸發 apply、但 apply 只關心結果變動。

Root 選擇的決策：找到「包含所有目標變動、但不包含其他無關變動的最小元素」。

太大 → 帶進無關變動、過度觸發
太小 → 漏掉真正關心的變動
剛好 → 只關心的變動觸發

問自己：「我關心的變動發生在哪些元素？這些元素的最小共同 ancestor 是誰？」答案就是 observer root。

維度 2：觀察什麼類型（option flag）

核心定義：MutationObserver 提供四種 option、每種對應不同類型變動：

1{
2  childList: true,        // 子節點增 / 減 / 重排
3  attributes: true,       // 屬性變動
4  attributeFilter: ['data-state'],  // 只看特定屬性
5  characterData: true,    // 文字內容變動
6  subtree: true,          // 上面三種往子樹深處看
7  attributeOldValue: true,  // 屬性變動時記錄舊值
8  characterDataOldValue: true,
9}

預設只勾需要的、不要全部 true：

Option	用途	觸發頻率
`childList: true`	子節點增減	中
`childList + subtree`	任何深度的子節點增減	高
`attributes` 全屬性	任何屬性變動	最高
`attributes + attributeFilter`	只特定屬性	低
`characterData`	文字內容（少用）	低

避免勾 subtree：subtree 把監聽從「直接子」擴展到「整個子樹」、觸發頻率可能爆炸。只在「真的需要看深層變動」時用。

避免無 filter 的 attributes：DOM 屬性變動很頻繁（class 改、style 改、aria-* 改），不過濾會被淹沒。用 attributeFilter: [...] 縮到只看你關心的屬性。

維度 3：多久觸發一次（頻率）

核心定義：observer 的回呼可能短時間內被連續呼叫、用 debounce 把多次合併成一次。

1var timer;
2function schedule() {
3  clearTimeout(timer);
4  timer = setTimeout(apply, 80);
5}
6new MutationObserver(schedule).observe(root, { childList: true });

Debounce 80ms 表示「最後一次變動後 80ms 沒再變、才跑 apply」 — 把連續變動合併。

Debounce vs Throttle：

機制	行為	適合
Debounce	安靜後執行	等 framework 連續 patch 結束
Throttle	固定頻率執行	UI 同步要立即反應、但限速
立即執行	每次都跑	變動頻率本來就低、且每次都要處理

大部分 observer 場景適合 debounce — framework patch 是突發性、不是持續的。

Debounce 時間選擇：

時間	適合
16ms（一個 frame）	跟 paint 同步、最即時
50-100ms	一般 UI 反應、肉眼感受不到延遲
200-300ms	等使用者輸入結束
1000ms+	後台處理、不影響 UI

預設 50-100ms — 比一個 frame 寬、又不會讓使用者感受延遲。

Self-mutation 循環的處理

問題場景

apply 函式自己也改 DOM 時、會再次觸發 observer：

1function apply() {
2  // 改了某個元素的 class（attribute 變動）
3  someEl.classList.add('processed');
4}
5new MutationObserver(apply).observe(root, {
6  attributes: true, subtree: true,
7});
8// → apply 改 class 觸發 observer → observer 又呼叫 apply → 無限循環

這不是邏輯錯、是 observer 機制的特性：observer 不會區分「是不是 apply 自己改的」。

解法：disconnect / observe 配對

1var observer = new MutationObserver(function () {
2  observer.disconnect();      // 暫停監聽
3  apply();                    // 自己改 DOM 不會觸發
4  observer.observe(root, options);  // 恢復監聽
5});
6observer.observe(root, options);

apply 期間 observer 暫停、apply 結束後恢復 — 自己的改動不會觸發自己。

解法替代：用 attribute 標記區分

1function apply() {
2  isApplying = true;
3  someEl.classList.add('processed');
4  isApplying = false;
5}
6new MutationObserver(function () {
7  if (isApplying) return;
8  apply();
9}).observe(root, options);

但這個解法有時序風險 — observer 是非同步、isApplying 可能在錯時間被讀。disconnect/observe 配對更穩。

解法替代：root 與目標分離

如果 apply 改的是 A、observer 監聽的是 B（A 跟 B 沒交集），自然不循環：

1new MutationObserver(apply).observe(resultsEl, { childList: true });
2function apply() {
3  // 改的是 input 而不是 results — 不會觸發 observer
4  inputEl.value = '...';
5}

設計時讓 observer 看的範圍跟 apply 改的範圍結構上分離 — 是最乾淨的解法、不需要 disconnect 配對。

觀察的時機問題

Observer 跟 framework 渲染週期競爭

Observer 在 framework 連續 patch 中段觸發、可能在 layout 還沒穩時就跑 apply、造成短暫視覺錯位：

1// framework 連續 patch：
2//   patch 1 → observer 觸發 → apply 跑 → 視覺 A
3//   patch 2 → observer 觸發 → apply 跑 → 視覺 B
4//   patch 3 → observer 觸發 → apply 跑 → 視覺 C（最終）
5// 使用者看到 A → B → C 的閃爍

Debounce 是這個問題的解 — 讓 observer 等 patch 完成才跑 apply。

確認時機正確

寫 observer 時自問：

問題	答案決定
Apply 跑的時候 layout 是否已穩定？	是否需要 debounce
Apply 自己改 DOM 嗎？	是否需要 disconnect 配對
我關心的變動類型是什麼？	option flag 怎麼勾
變動發生在哪一層？	是否需要 subtree
Framework 的渲染週期會干擾嗎？	debounce 時間取多久

每個問題都該有顯式答案、不能丟預設。

內在屬性比較：四種 observer 設計

設計	觸發頻率	Layout 穩定性	維護成本
全勾 + subtree + 無 debounce	最高	低 — patch 中段觸發	低（短期）/ 高（debug 噩夢）
收斂 root + 必要 option + 無 debounce	中	中	中
收斂 root + 必要 option + debounce	低	高	中
結構分離 + 收斂 + debounce	最低	最高	中（前期設計成本）

推薦：收斂 root + 必要 option + debounce。apply 不改 DOM 時不需要 disconnect；改的話用結構分離優先、退而求其次用 disconnect。

進階技巧

1. 動態調整 observer 範圍

當監聽目標可能還沒 mount 時、用兩階段 observer：

 1// 階段 1：等目標 mount
 2var bootstrap = new MutationObserver(function () {
 3  var target = shell.querySelector('.pagefind-ui__results');
 4  if (!target) return;
 5  bootstrap.disconnect();
 6
 7  // 階段 2：mount 後監聽目標
 8  new MutationObserver(apply).observe(target, { childList: true });
 9});
10bootstrap.observe(shell, { childList: true, subtree: true });

階段 1 用寬範圍找到目標、階段 2 切到精準範圍 — 把寬範圍的觸發限制在「找目標」這個短時間。

2. 用 `takeRecords` 主動取出累積變動

1var observer = new MutationObserver(function () { /* ... */ });
2observer.observe(root, options);
3
4// 之後某時間點、想立刻處理累積的變動
5var records = observer.takeRecords();
6processRecords(records);

takeRecords 取出尚未觸發回呼的變動記錄、主動處理 — 適合「我想在某時間點同步處理累積變動」場景。

3. 多 observer 各管一塊

不要用一個 observer 監聽全部、各分一個：

1new MutationObserver(applyA).observe(elA, { childList: true });
2new MutationObserver(applyB).observe(elB, { attributes: true });

各自獨立 — 一個 observer 出錯不影響另一個、debug 範圍小、option 各自最佳化。

設計取捨：MutationObserver 的設計策略

四種做法、各自機會成本不同。這個專案選 A（收斂 root + 必要 option + debounce）當預設、其他做法在特定情境合理。

A：收斂 root + 必要 option + debounce + 結構分離（這個專案的預設）

機制：root 取最小共同 ancestor、option 只勾真正關心的變動、加 50-100ms debounce、apply 改的範圍跟 observer 看的範圍結構上分離
選 A 的理由：觸發頻率最低、layout 穩定、無 self-mutation 循環風險
適合：絕大多數 observer 設計
代價：前期設計成本中（要思考 root / option / 結構）

B：收斂 root + 必要 option（無 debounce）

機制：縮範圍與 option、但不加 debounce
跟 A 的取捨：B 即時反應、A 等 debounce；但 B 在 framework patch 中段觸發、layout 不穩時跑 apply 結果不可靠
B 比 A 好的情境：apply 不依賴 layout（純改 attribute、不讀 bounding rect）

C：寬範圍 + subtree + 全勾 option（預設配置）

機制：observe(elem, { childList: true, subtree: true, attributes: true, …})
C 是反模式：「以防萬一全勾」會觸發數十倍頻率的 callback、framework 環境必撞效能 / 競態 bug
看起來吸引人的原因：寫法簡單、不用想要監聽什麼、「全部都看就不會漏」
實際發生的代價：CPU 100%、layout thrashing、self-mutation 引發無限迴圈

D：disconnect / observe 配對處理 self-mutation

機制：apply 前 disconnect、apply 後 reconnect
跟 A（結構分離）的取捨：D 處理 callback 必須改 observer 監聽範圍的情境、A 從設計上避免；A 更乾淨
D 比 A 好的情境：無法做結構分離（apply 必須改 observer 看的範圍）— 唯一情境

判讀徵兆

訊號	Observer 問題	修正動作
短時間觸發數十次	範圍 / option 太寬	縮 root、移除不需要的 option、加 debounce
Apply 跑時 layout 抖動	在 framework patch 中段觸發	加 debounce 50-100ms
Apply 內改 DOM 進入無限循環	沒處理 self-mutation	用結構分離 / disconnect 配對
預期變動沒觸發	option 沒勾對、root 選錯	對照變動類型確認 option
Subtree 用了但只關心直接子	過度監聽深度	移除 subtree、改用直接子監聽
屬性監聽觸發太頻繁	沒用 attributeFilter	加 filter 限縮屬性

核心原則：MutationObserver 是非同步監聽、跟同步 selector 設計工具完全不同。範圍 / option / 頻率三維度都要顯式設計 — 預設組合會在 framework 環境中過度觸發、且難以 debug。

subtree: true + attributes: true 是「監聽全部」的便利、窄 root + 最少 option 是「精準監聽」的對齊 — 同 #43 最小必要範圍跟 #67 便利 vs 對齊反相關。

setTimeout 輪詢換 MutationObserver

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

核心原則

等待元素出現用 MutationObserver、不用 setTimeout 輪詢。 Observer 是 event-driven、元素出現的瞬間觸發、無延遲；輪詢是 time-based、最快回應時間 = 輪詢間隔、且 CPU 一直跑。

輪詢只在「沒有事件可監聽」時才用。

為什麼 observer 比輪詢好

商業邏輯

「等待某個 DOM 元素出現」這件事的本質是「監聽 DOM 變化、出現時觸發」 — 完全是 event-driven 場景。

setTimeout 輪詢的特徵：

每隔 N ms 檢查一次、最快 N ms 才能回應
即使元素已經出現、要等到下次檢查才知道
CPU 持續被佔用（即使元素永遠不出現）

MutationObserver 的特徵：

元素出現的瞬間觸發 callback
0 延遲
DOM 沒變動時 observer 不耗 CPU

兩者效能差異在現代設備上不明顯、但設計上 observer 才是「適合這個場景」的工具。

何時輪詢是必要的

情境	輪詢必要
等待 DOM 元素出現	否 — 用 MutationObserver
等待元素尺寸變化	否 — 用 ResizeObserver
等待元素進入 viewport	否 — 用 IntersectionObserver
等待外部 API 結果	否 — 用 promise / async
等待全局變數出現（無事件）	是 — 必要時輪詢

「無事件可監聽」時才輪詢 — 這類場景在現代 Web 開發少見。

這次任務的輪詢

觀察

search.html 用 setTimeout 等 pagefind UI mount：

 1function waitAndInit() {
 2  filter = document.querySelector('.pagefind-ui__filter-panel');
 3  drawer = document.querySelector('.pagefind-ui__drawer');
 4  if (!filter || !drawer) {
 5    setTimeout(waitAndInit, 100);
 6    return;
 7  }
 8  // 找到了、開始 setup
 9  place();
10  reorderFilters();
11  setupScopeFilter();
12  mql.addEventListener('change', place);
13}
14waitAndInit();

每 100ms 檢查一次、有延遲、CPU 一直跑（雖然輕）。

判讀

改用 MutationObserver 監聽 #search（pagefind mount target）的子節點變化：

 1function waitForPagefind(searchRoot, onReady) {
 2  // 已經存在則立即觸發
 3  if (searchRoot.querySelector('.pagefind-ui__drawer')) {
 4    onReady();
 5    return;
 6  }
 7  // 否則 observe DOM 變動
 8  var observer = new MutationObserver(function () {
 9    if (searchRoot.querySelector('.pagefind-ui__drawer')) {
10      observer.disconnect();
11      onReady();
12    }
13  });
14  observer.observe(searchRoot, { childList: true, subtree: true });
15}
16
17waitForPagefind(document.getElementById('search'), function () {
18  filter = document.querySelector('.pagefind-ui__filter-panel');
19  drawer = document.querySelector('.pagefind-ui__drawer');
20  place();
21  reorderFilters();
22  setupScopeFilter();
23  mql.addEventListener('change', place);
24});

特性：

pagefind 渲染完瞬間觸發、無延遲
disconnect() 後 observer 不再耗資源
已存在時 fast path 直接觸發

執行：通用 helper

 1/**
 2 * 等待 selector 在 root 內出現、觸發 callback。
 3 * 已存在則 sync 觸發；不存在則用 MutationObserver 等待。
 4 */
 5function waitForElement(root, selector, callback) {
 6  var existing = root.querySelector(selector);
 7  if (existing) {
 8    callback(existing);
 9    return;
10  }
11  var observer = new MutationObserver(function () {
12    var el = root.querySelector(selector);
13    if (el) {
14      observer.disconnect();
15      callback(el);
16    }
17  });
18  observer.observe(root, { childList: true, subtree: true });
19}
20
21// 用法
22waitForElement(searchRoot, '.pagefind-ui__drawer', function (drawer) {
23  // 開始 setup
24});

把 wait 抽成 helper、setup code 變得更簡潔。

內在屬性比較：四種等待機制

機制	延遲	CPU 使用	適用情境
`setTimeout` 單次	固定延遲	0	等已知時間
`setTimeout` 輪詢	平均 = 間隔 / 2	持續低使用	沒事件可監聽
`MutationObserver`	0 — 變動瞬間	DOM 變動時短暫	等待 DOM 元素
Promise / async	0 — resolve 瞬間	0	等待 async 操作

優先順序：event-driven > async > polling > timeout。輪詢是最後選擇。

MutationObserver 的細節

Observe option 選對

1observer.observe(root, {
2  childList: true,    // 直接子節點增減
3  subtree: true,      // 包含深層子節點
4  attributes: false,  // 不看 attribute 變動
5  characterData: false,
6});

只勾必要的、不要全部勾 — 觸發頻率影響效能。

找到目標後 disconnect

1var observer = new MutationObserver(function () {
2  if (found) {
3    observer.disconnect();   // 立刻停、不要繼續監聽
4    callback();
5  }
6});

不 disconnect 的話、observer 一直 active、未來任何 DOM 變動都觸發 callback。

已存在的 fast path

1if (root.querySelector(selector)) {
2  callback();   // 已存在則直接觸發、不需 observer
3  return;
4}

避免「元素已經存在但還是要等下次變動才觸發」的延遲。

設計取捨：等待 DOM 元素出現的策略

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

A：MutationObserver + already-exists fast path（這個專案的預設）

機制：先檢查目標是否已存在（直接觸發）、否則 observe DOM 變動、找到後 disconnect
選 A 的理由：0 延遲、CPU 不被輪詢吃、找到後立即停
適合：等待 framework / 第三方 library 動態 mount 的元素
代價：需要寫 fast path + observer + disconnect 三段邏輯（用 helper 包裝即可一行調用）

B：`setTimeout` 輪詢

機制：每隔 N ms 檢查、找到就停
跟 A 的取捨：B 寫法簡單、A 設計嚴謹；但 B 有最快回應 = N ms 的延遲、CPU 一直跑
B 比 A 好的情境：等待對象是無事件可監聽的狀態（全局變數出現、外部 API 結果且無 promise 介面），MutationObserver 無處掛載

C：Promise / async（如果 API 提供）

機制：await framework.ready() 等 framework 提供的 promise
跟 A 的取捨：C 是最乾淨的解、但需要 framework / library 提供 promise API
C 比 A 好的情境：等的目標有官方 promise 介面（避免自行 observe 內部 DOM）

D：`requestAnimationFrame` 迴圈

機制：每個 frame 檢查一次
跟 B 的取捨：D 跟著 frame、不會在 idle 時跑；但仍是輪詢、延遲 16ms
D 才合理的情境：等待動畫 frame 相關狀態（罕見）— 純等 DOM 元素仍應用 A

判讀徵兆

訊號	Refactor 動作
`setTimeout` 用來等 DOM 元素	改 `MutationObserver` + disconnect
`setInterval` 不停跑檢查元素狀態	改 `MutationObserver` 或 `ResizeObserver`
等待邏輯有「最快 X ms 才回應」的延遲	改 event-driven 機制、消除延遲
Observer 找到目標後沒 disconnect	加 disconnect、避免繼續觸發

核心原則：DOM 變動有對應的 event 機制可監聽 — 用對機制就有 0 延遲、無 CPU 浪費。輪詢是「沒辦法的辦法」、不是 default。

Init function 是 orchestrator、職責拆出獨立 function

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

核心原則

單一函式做 ≥ 3 件無關的事就拆。 每個函式只負責一個職責、有明確的 input / output、可以獨立 debug 與測試。Init function 變成「組合各職責 function 的 orchestrator」。

為什麼拆函式

商業邏輯

單一函式做多件事的成本：

規模	維護痛點
一函式 50 行做 1 件事	低 — 容易讀、職責清楚
一函式 100 行做 3 件事	中 — 邏輯交織、debug 要分辨哪段
一函式 200 行做 5+ 件事	高 — 沒人想動、改一處可能影響別處

拆函式的成本是「多寫幾個函式名與簽名」、收益是「每個函式範圍小、debug 容易、可單獨重用」。

拆的依據是「職責」、不是行數

拆法	結果
按行數機械拆	切出沒邏輯意義的片段、更亂
按職責拆	每個函式名能描述「做什麼」
按 input / output 拆	函式變得 testable、可組合

按職責拆的判斷：能不能用一個動詞片語描述函式做什麼？做不到 → 多個職責、該拆。

這次任務的拆分機會

觀察

setupScopeFilter() 現況做 5 件事：

 1function setupScopeFilter() {
 2  // 1. 找元素
 3  var scopeEl = document.querySelector('.search-scope');
 4  var input   = document.querySelector('.pagefind-ui__search-input');
 5  // ...
 6
 7  // 2. 量測 scope 高度寫回 CSS 變數
 8  function syncScopeHeight() { ... }
 9  syncScopeHeight();
10  new ResizeObserver(syncScopeHeight).observe(scopeEl);
11
12  // 3. 把 filter-panel 搬到 sidebar (position function)
13  function place() { ... }
14
15  // 4. 註冊 scope filter listener + apply
16  function apply() { ... }
17  scopeEl.addEventListener('change', apply);
18  // ...
19
20  // 5. Reorder filter blocks
21  function reorderFilters() { ... }
22  reorderFilters();
23}

5 個職責塞在一個函式：找元素、量高度、搬 slot、scope filter、reorder filter。

判讀

按職責拆成獨立函式：

 1function findSearchElements(shell) {
 2  return {
 3    shell:  shell,
 4    ui:     shell.querySelector('.pagefind-ui'),
 5    input:  shell.querySelector('.pagefind-ui__search-input'),
 6    drawer: shell.querySelector('.pagefind-ui__drawer'),
 7    filter: shell.querySelector('.pagefind-ui__filter-panel'),
 8    scope:  shell.querySelector('.search-scope'),
 9  };
10}
11
12function syncScopeHeight(scopeEl) {
13  function update() {
14    var h = scopeEl.offsetHeight || 56;
15    document.body.style.setProperty('--search-scope-h', h + 'px');
16  }
17  update();
18  new ResizeObserver(update).observe(scopeEl);
19}
20
21function setupFilterSlotSwap(filter, drawer, slot, breakpoint) {
22  var mql = window.matchMedia('(min-width: ' + breakpoint + 'px)');
23  function place() {
24    if (mql.matches) slot.appendChild(filter);
25    else drawer.insertBefore(filter, drawer.firstChild);
26  }
27  place();
28  mql.addEventListener('change', place);
29}
30
31function reorderFilters(filterPanel, desiredOrder) {
32  var blocks = filterPanel.querySelectorAll('.pagefind-ui__filter-block');
33  var byKey = {};
34  blocks.forEach(function (b) {
35    var key = b.querySelector('.pagefind-ui__filter-name').textContent.trim().toLowerCase();
36    byKey[key] = b;
37  });
38  desiredOrder.forEach(function (k) {
39    if (byKey[k]) filterPanel.appendChild(byKey[k]);
40  });
41}
42
43function setupScopeFilter(scopeEl, input, ui) {
44  function getScope() { ... }
45  function apply() { ... }
46  function schedule() { ... }
47  scopeEl.addEventListener('change', schedule);
48  input.addEventListener('input', schedule);
49  new MutationObserver(schedule).observe(ui, { childList: true, subtree: true });
50}

init() 變成 orchestrator：

 1function init() {
 2  var shell = document.querySelector('.search-shell');
 3  if (!shell) return;
 4
 5  waitForElement(shell, '.pagefind-ui__drawer', function () {
 6    var els = findSearchElements(shell);
 7    syncScopeHeight(els.scope);
 8    setupFilterSlotSwap(els.filter, els.drawer, document.querySelector('.search-filter-slot'), 1400);
 9    reorderFilters(els.filter, ['type', 'tag']);
10    setupScopeFilter(els.scope, els.input, els.ui);
11  });
12}
13init();

每個拆出的函式：

名字描述做什麼（動詞 + 名詞）
接受需要的元素當參數（不依賴全局）
不知道其他函式的存在（解耦）

內在屬性比較：四種函式拆分粒度

粒度	維護成本	Debug 範圍	可重用性
一個 mega init function	高 — 200+ 行交織	整個函式都要看	低 — 跟特定 setup 綁
按行數機械拆（每 30 行一份）	中 — 切出無意義片段	中	低
按職責拆	低 — 每函式單一職責	函式內部、範圍小	高
按職責拆 + class 包裝	低	範圍小	最高 — 多實例

優先按職責拆 — 函式名表達 intent、debug 範圍小、單獨可測。

拆函式的具體技巧

1. 函式名是動詞片語

1syncScopeHeight()           // 動詞 + 對象
2setupFilterSlotSwap()       // 動詞 + 對象
3reorderFilters()            // 動詞 + 對象
4findSearchElements()        // 動詞 + 對象

不要：

1filter()        // 動詞模糊（filter 是動詞還是名詞？）
2handle()        // 太抽象
3init()          // 只有 orchestrator 用、不要散在各處

2. 參數是該函式需要的、不傳一個 mega object

1// 好 — 函式知道它需要什麼
2function syncScopeHeight(scopeEl) { ... }
3
4// 較差 — 函式拿到一堆無關的東西、不清楚依賴
5function syncScopeHeight(allElements) {
6  var scope = allElements.scope;
7  ...
8}

明確參數 = 明確依賴 = 容易測試。

3. 副作用集中在一處

1function syncScopeHeight(scopeEl) {
2  function update() {
3    document.body.style.setProperty('--search-scope-h', scopeEl.offsetHeight + 'px');
4  }
5  update();
6  new ResizeObserver(update).observe(scopeEl);
7}

副作用（DOM 變動、event listener、observer）都在這個函式內。沒散到別處。

4. 不依賴外部變數

1// 好 — 純函式、依賴只在參數
2function reorderFilters(filterPanel, desiredOrder) { ... }
3
4// 較差 — 依賴外部全局變數
5var desiredOrder = ['type', 'tag'];
6function reorderFilters(filterPanel) {
7  // 用了 desiredOrder
8}

純函式 = 無隱式依賴 = 重用方便、測試方便。

設計取捨：大型 init function 的拆分策略

四種做法、各自機會成本不同。這個專案選 A（按職責拆 + 純函式）當預設、其他做法在特定情境合理。

A：按職責拆 + 純函式 + init 當 orchestrator（這個專案的預設）

機制：每職責一個函式（動詞 + 對象命名）、依賴透過參數傳入、init 組合各函式
選 A 的理由：debug 範圍小（職責 = 函式 = grep 範圍）、單獨可測、可重用
適合：> 50 行的 init function、預期長期維護
代價：多寫幾個函式名與簽名、檔案 LOC 略增

B：按行數機械拆（每 30 行一份）

機制：固定 LOC 拆檔、不考慮職責邊界
跟 A 的取捨：B 拆完後切片無邏輯意義、A 切片各自完整；B 更亂、debug 反而更難
B 是反模式：「行數」不是有意義的拆分判準 — 拆完後切片無邏輯意義、debug 反而更難

C：保持 mega init function

機制：所有 setup 邏輯塞在一個 init 內
跟 A 的取捨：C 一個函式看完所有 setup、A 散在多函式；但 C 在 200+ 行時改一處要小心整體
C 才合理的情境：< 50 行的 init、職責本來就單一

D：按職責拆 + class 包裝多實例

機制：把 setup 包成 class、new SearchShell(rootEl) 建立實例
跟 A 的取捨：D 多實例支援更乾淨（每實例自己的 state）、A 用純函式 + 起點當參數也能達成
D 比 A 好的情境：元件有複雜的內部 state、預期會被多次實例化（library 設計）

判讀徵兆

訊號	Refactor 動作
一個函式 100+ 行	列出做的事、按職責拆
函式名抽象（`init` / `handle` / `process`）	改名動詞 + 對象、表達 intent
函式內讀外部全局變數	把依賴改為參數、純函式化
Debug 時要 grep 整個函式找哪段邏輯	拆完後職責 = 函式 = grep 範圍縮小
同一段邏輯複製到別處	拆成獨立函式、兩處引用

核心原則：函式是「做一件事」的單位。一個函式越多職責、debug 與重用越難。拆 = 投資、回報是未來的維護成本下降。

Reactive 監聽器的效能 audit：跨 listener 類型盤點觸發頻率

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

核心原則

監聽器的「觸發頻率」是效能的第一道防線、跨多種 listener 類型一起盤點。 本篇是 audit 視角（「我有效能問題、reactive 監聽器是不是嫌疑」）— 設計新 observer 的細節由 #29 MutationObserver 範圍與觸發頻率處理。Audit 時把所有 reactive 監聽器列一張表、看哪些觸發頻率異常。

本篇焦點：跨 listener 類型的效能盤點。

MutationObserver 的設計細節（root / option / debounce / self-mutation）由 #29 處理

Selector 範圍的設計由 #14 處理

Runtime 計算成本（regex / textContent / forEach）由 #34 處理

為什麼觸發頻率主導效能

商業邏輯

Reactive 監聽器有三個獨立成本：

成本來源	單次量級	累積方式
觸發頻率	看範圍與 option	倍數疊加
Callback 內部運算	看實作	每次完整跑
Callback 引發的副作用	看 DOM 變動	可能反向觸發

把單次 callback 從 5ms 優化到 2ms 是 2.5x；把觸發次數從 100 次/秒降到 10 次/秒是 10x。觸發頻率優化的天花板更高 — audit 時優先看頻率。

三類觸發頻率風險（速覽）

類型	表現	詳細處理
範圍過寬（observer subtree）	無關變動也觸發	#29 root 與 option 設計
Option 全勾	多種變動類型同時觸發	#29 三維度收斂
自激迴圈	callback 自己改 DOM 觸發自己	#29 self-mutation 處理

本篇不展開設計細節（避免跟 #29 重複）、只談「audit 時怎麼識別這些 risk」。

跨 observer 類型的盤點

效能 audit 時、列出所有 reactive 監聽器、不只 MutationObserver。各類型觸發來源不同、需要分別評估。

類型	觸發來源	過頻訊號
MutationObserver	DOM 變動	一次操作觸發 10+ 次
ResizeObserver	元素尺寸變動	持續觸發（自激）/ resize 視窗時連發
IntersectionObserver	可視性變動	scroll 時連發
Event listener (input / scroll / resize)	使用者互動	高頻事件未 debounce
`setInterval` / `requestAnimationFrame` 迴圈	時間	持續跑、不只在需要時

盤點工具

DevTools Performance 面板錄一段使用者操作、看 callback 觸發次數：

 1// 在 callback 內加 console.count
 2new MutationObserver(function (mutations) {
 3  console.count('mutation observer fired');
 4  // ... 處理
 5}).observe(...);
 6
 7new ResizeObserver(function (entries) {
 8  console.count('resize observer fired');
 9  // ... 處理
10}).observe(...);

跑一次「使用者打字 + 等結果」的完整操作、看 console 各 listener 觸發幾次。

觸發次數	評估
1-3 次	正常
5-10 次	可能過頻、值得查
10+ 次	範圍 / option 太寬、需要收斂
持續觸發（不停）	自激迴圈、需要立刻處理

ResizeObserver 寫變數造成自激

ResizeObserver 的特殊風險是「寫 CSS 變數可能影響被觀察元素自己的尺寸」 — 這個 case 跟 #29 處理的 MutationObserver self-mutation 機制不同、值得獨立展開。

機制

1function syncScopeHeight() {
2  document.documentElement.style.setProperty(
3    '--search-scope-h', scopeEl.offsetHeight + 'px'
4  );
5}
6new ResizeObserver(syncScopeHeight).observe(scopeEl);

如果 --search-scope-h 在 CSS 中被用來計算 scopeEl 自己的 padding / margin / height — 寫入觸發 layout、layout 觸發 resize、resize 觸發 callback、callback 又寫入。

症狀

CPU 持續被佔
Performance 面板看到 ResizeObserver callback 連發（>60/秒）
元素尺寸持續微調

解法

結構分離：寫的變數不該影響被觀察元素自己。

1new ResizeObserver(syncScopeHeight).observe(scopeEl);
2// scopeEl 高度寫到 --search-scope-h
3// CSS 中 --search-scope-h 用來計算 drawer 的 margin-top
4// drawer 不是 scopeEl、不會反向觸發

設計時讓「觀察的元素」跟「受變數影響的元素」結構上分離 — 不會循環。

跟 MutationObserver self-mutation 的差異

觀察類型	self-mutation 機制	處理
MutationObserver	callback 改 DOM 結構 / attribute	disconnect + observe 配對
ResizeObserver	callback 改變數 → 反向影響尺寸	結構分離（觀察 A、影響 B）
IntersectionObserver	callback 改可視性 → 反向觸發	罕見、設計時避免

ResizeObserver 沒有 disconnect 配對的等價技巧（disconnect 後再 observe 仍會立即重觸發） — 必須靠結構分離。

盤點的標準格式

每個 reactive 監聽器寫成一段註解、audit 時讀這份「設定卡」即可：

 1/**
 2 * 監聽：.pagefind-ui 的子節點變動
 3 * 類型：MutationObserver
 4 * 範圍：subtree（深層也看）
 5 * Option：childList only
 6 * Callback 是否改 DOM：是（toggle class）
 7 * 自激風險：否（class change 不觸發 childList）
 8 * Debounce：80ms
 9 * 預期觸發頻率：使用者打字一次 < 5 次
10 */
11new MutationObserver(schedule).observe(ui, { childList: true, subtree: true });

audit 時、看註解就知道：

這個 observer 在做什麼
預期觸發頻率多少
實測超過預期 → 範圍太寬或 option 過勾

設計取捨：頻率管理策略選擇

當盤點發現某個 observer 觸發過頻、四種應對：

A：縮 observer 範圍 / option（這個專案的預設）

機制：subtree → 直接子；移除沒用的 option flag
選 A 的理由：成本最低、改一行；觸發頻率倍數降低
適合：絕大多數過頻 case
代價：需要重新確認哪些變動類型真的需要監聽
詳細：#29 三維度收斂

B：加 debounce / throttle

機制：高頻觸發合併成低頻 apply
跟 A 的取捨：B 不解問題的根（觸發仍發生）、A 解根；但 B 對「無法縮範圍」的 case（如 input event）必要
B 比 A 好的情境：使用者輸入事件、scroll 事件 — 本身高頻、無法縮範圍

C：Disconnect / reconnect 配對

機制：callback 改 DOM 前 disconnect、改完 reconnect
跟 A/B 的取捨：C 處理 self-mutation、A/B 不處理；C 比 A/B 複雜
C 比 A/B 好的情境：MutationObserver callback 必須改 DOM（沒有結構分離選項）
詳細：#29 self-mutation 處理

D：ResizeObserver 結構分離

機制：觀察 A、影響 B（B ≠ A）
跟 C 的取捨：ResizeObserver 沒 disconnect 等價技巧、必須用 D
D 是 ResizeObserver 自激的唯一解

不該套用「頻率管理」的情境

不是所有 reactive 監聽器都需要管：

情境	為什麼可以放任
開發階段、不上 production	效能不影響真實使用者
Callback 極輕（單次 < 0.1ms）	觸發 100 次也才 10ms
觸發頻率本來就極低（一次 setup 一次 callback）	沒有頻率問題

核心判準：實測有效能問題嗎？沒有就不必預先優化。Audit 是「找已存在的問題」、不是「預防所有可能」。

跟其他原則的關係

篇	關係
#29 MutationObserver 範圍與觸發頻率	互補 — #29 是設計指引（怎麼寫 observer）、本篇是 audit 視角（怎麼找問題）
#14 Selector 精準度	跟 observer 範圍同源 — selector 起點就是 observer root 的選擇基礎
#34 Runtime 計算成本	互補 — 本篇看「觸發次數」、#34 看「單次 callback 成本」
#43 最小必要範圍	「縮監聽範圍」是「最小必要範圍」原則的應用

判讀徵兆

訊號	該檢查的位置
使用者操作後瀏覽器卡頓	該操作觸發了哪些 observer、各自觸發次數
CPU 持續 100%	observer 自激迴圈（特別是 ResizeObserver）
`setTimeout(0)` 也來不及處理	observer / event 觸發頻率超過 schedule 處理速度
Callback 內加 console.count 數字爆炸	observer 範圍過寬 — 收斂方式由 #29 處理
ResizeObserver 在某 callback 後持續觸發	寫的變數反向影響觀察元素 — 結構分離

核心原則：reactive 監聽器的效能 audit = 列所有 listener + 量觸發次數 + 比對預期。發現問題後、設計修正方式由 #29 等設計指引篇展開 — 本篇只負責「找問題」這一步。

Runtime 計算成本：每筆迭代與正則

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

核心原則

每筆迭代的成本 = 單次計算 × 迭代次數。 兩個變數都會放大效能問題；單次計算便宜時、迭代次數變多仍可能爆掉 frame budget。盤點時兩維度一起看、不只看單筆。

為什麼迭代次數值得獨立看待

商業邏輯

開發階段測試的資料量通常少（10 筆結果）— 單次迭代 + 10 次 = 不痛。

上線後資料量放大（200 筆結果）— 同樣的單次計算 × 200 = 痛。

單次計算的最佳化收益是固定倍數、迭代次數的成長是線性放大 — 後者更值得關注。

三類迭代成本

類型	例
對 DOM 集合迭代	`forEach` over `querySelectorAll` 結果
對資料陣列迭代	`map` / `filter` over 大量物件
對 DOM 樹遞迴	`.contains()` 或 ancestor walk

每類有不同的優化策略、共通是「先量規模再決定動哪」。

搜尋頁的具體風險點

風險 1：scope filter 對每筆 result 跑 regex

位置：assets/search.js 的 apply()。

1items.forEach(function (el) {
2  var titleEl   = el.querySelector('.pagefind-ui__result-title');
3  var excerptEl = el.querySelector('.pagefind-ui__result-excerpt');
4  var title   = titleEl   ? titleEl.textContent   : '';
5  var excerpt = excerptEl ? excerptEl.textContent : '';
6  var show = scope === 'title' ? re.test(title) : re.test(excerpt);
7  // ...
8});

每筆 result 做的事：

兩次 querySelector（DOM 查詢）
兩次 textContent 讀取（DOM 屬性讀取）
一次 re.test（正則比對）
一次 classList.toggle（class 操作）

單筆 ~0.1ms 等級、看 DOM 大小。

判讀：

結果 10 筆 → 1ms、無感
結果 100 筆 → 10ms、接近 frame budget（16.67ms）
結果 500 筆 → 50ms、明顯卡頓

症狀：使用者打字時 input lag、scroll jank。

第一個該查的：DevTools Performance 面板錄一次 apply、看 forEach 那段佔多少。> 5ms 開始考慮優化。

風險 2：textContent 讀取的隱藏成本

位置：上述 titleEl.textContent。

判讀：textContent 看似簡單、實際在某些瀏覽器中要 traverse 整個子樹拼字串。對於有 highlight 標籤的結果、textContent 要組合多個 text node。

症狀：textContent 比預期慢、特別在 result 內結構複雜時。

第一個該查的：用 console.time 量一次 textContent 讀取、看單次幾 ms。

風險 3：每次 apply 都重新 querySelector

位置：apply() 每次跑都 document.querySelectorAll('.pagefind-ui__result')。

判讀：querySelector 是 fresh 查詢、不快取。每次 apply 都重新掃 DOM 找到結果集合。

症狀：apply 觸發頻繁時、querySelector 是固定開銷。

第一個該查的：把結果集合 cache 一份、observer 觸發時更新 cache、apply 用 cache 不重查 DOM。

風險 4：Regex 編譯成本

位置：

1var re = new RegExp(escapeRegex(query), 'i');

每次 apply 編譯一次 regex。

判讀：Regex 編譯成本比想像中重 — 對複雜 pattern 可達數 ms。

症狀：query 字串長、apply 觸發頻繁時、regex 編譯佔 frame budget。

第一個該查的：把 regex cache 起來、query 變動才重編譯。

內在屬性比較：四種優化方向

方向	縮減幅度	複雜度	適用情境
縮迭代次數（IntersectionObserver 只處理可視區）	大	中	結果數量大、多數不在可視範圍
縮單次計算（cache textContent / regex）	中	低	重複計算同樣的東西
分批處理（requestIdleCallback / chunk）	大 — 攤開時間	中	一次處理量大但可延後
Web Worker	最大 — 獨立 thread	高	純計算密集、跟 DOM 無關

對 scope filter 的場景：IntersectionObserver 只處理可視區 + regex cache 是性價比最高的兩項。

規模放大的盤點

對每個迭代的 callback、預先估算「規模放大時會怎樣」：

當前規模	10x 規模	100x 規模
10 筆 result × 0.1ms = 1ms	100 筆 = 10ms（接近 16ms 上限）	1000 筆 = 100ms（明顯卡）

10x / 100x 的數字是「未來內容增長 1 個 / 2 個數量級」的預警。當前 fine 但 10x 後不 fine、值得提前考慮優化機制。

設計取捨：per-item 迭代成本的優化策略

四種做法、各自機會成本不同。預設先做 A（縮迭代次數）、A 不夠才考慮 B/C/D。

A：縮迭代次數（IntersectionObserver / 分頁 / 過濾）（這個專案的預設）

機制：用 IntersectionObserver 只處理可視區、用過濾條件預先排除大量項目
選 A 的理由：縮減幅度大（線性放大反向操作）、callback 內部不變
適合：結果數量大、但實際需要處理的部分少（多數在可視區外）
代價：增加 observer setup、需要設計「該處理什麼項目」的判斷

B：縮單次計算（cache textContent / regex / DOM query）

機制：把重複計算的結果 cache、避免每次重做
跟 A 的取捨：B 縮減幅度中等（看 cache 命中率）、A 縮減幅度大；兩者解不同問題、可並用
B 比 A 好的情境：迭代次數無法縮（必須處理所有項目）、但每項計算重複（regex 編譯、textContent 重讀）

C：分批處理（requestIdleCallback / chunk）

機制：把一次處理拆成多次、攤開到多個 frame
跟 A/B 的取捨：C 攤開時間、A/B 縮減總時間；C 在「總時間無法縮、但可以延後」時合理
C 比 A 好的情境：處理量大但可延後（initial render 時的非關鍵 enhancement）

D：Web Worker

機制：把計算搬到獨立 thread
跟 A/B/C 的取捨：D 完全不阻 main thread、但 setup 成本高（postMessage 序列化）
D 才合理的情境：純計算密集、跟 DOM 無關（搜尋 indexing、複雜資料處理）— 對 DOM 操作沒意義（Web Worker 不能直接動 DOM）

判讀徵兆

訊號	該檢查的位置
forEach over 大集合佔用 frame budget	用 IntersectionObserver 只處理可視區
每次 apply 重做相同的查詢 / 編譯	Cache 結果、變動觸發時更新 cache
Async 處理可接受時還在同步跑	改 requestIdleCallback / 分批 setTimeout
資料量比測試時大 N 倍後才發現問題	開發時做規模 10x / 100x 預估

核心原則：「每筆都做」的計算成本 = 每筆 × 筆數。優化時兩維度都看、不要只盯單次。

動態 DOM 移動時的 focus 管理

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

核心原則

JS 移動或隱藏 DOM 元素時、鍵盤 focus 的命運要主動處理 — 不處理會跑掉或停在不可見元素上、鍵盤使用者瞬間迷失方向。 多數動態 UI 的 focus 問題不是「某個元素該 focusable」、是「某個變動沒考慮 focus 該去哪」。

為什麼 focus 管理需要主動處理

商業邏輯

鍵盤使用者依 focus 知道「現在在哪」。focus 變動有三種來源：

來源	含義
使用者主動（Tab、Enter、方向鍵）	預期、無需處理
Focus 元素被移除	focus 跳到 body — 使用者迷失
Focus 元素被 reparent	看瀏覽器、可能 focus 仍在元素上、可能掉失

第二、三類是 JS 變動 DOM 引起的副作用、開發者要主動處理。

三類 DOM 變動對 focus 的影響

變動類型	Focus 行為
整節點 reparent（appendChild）	視瀏覽器、Chrome 多半保留 focus、Safari 可能掉
節點 remove	focus 跳到 body
節點 display: none	focus 跳到 body
節點 visibility: hidden	focus 仍在但元素不可見、使用者迷失

每類有對應的處理 — 主要是「事前 save、事後 restore」。

搜尋頁的具體風險點

風險 1：Filter slot 跨 viewport 切換

位置：matchMedia callback 的 place() 函式。

1function place() {
2  if (mql.matches) slot.appendChild(filter);
3  else drawer.insertBefore(filter, drawer.firstChild);
4}

判讀：使用者鍵盤 focus 在 filter 內某個 checkbox、視窗 resize 跨過 1400px、appendChild 把 filter 整個搬到別處。理論上 focus 跟著節點走、實際視瀏覽器。

症狀：使用者按 tab 進到 filter checkbox、調視窗寬度跨 breakpoint、focus 突然在 body 或其他位置。

第一個該查的：

1function place() {
2  var activeBefore = document.activeElement;
3  if (mql.matches) slot.appendChild(filter);
4  else drawer.insertBefore(filter, drawer.firstChild);
5  // 嘗試還原 focus
6  if (activeBefore && filter.contains(activeBefore)) {
7    activeBefore.focus();
8  }
9}

activeElement 在 reparent 前後仍指向同一個 DOM 節點（如果 focus 在 filter 內）。明確 .focus() 確保視覺一致。

風險 2：Scope filter 隱藏當前 focus 元素

位置：scope filter 的 apply()。

1items.forEach(function (el) {
2  el.classList.toggle('is-scope-filtered', !show);
3});

判讀：若使用者 focus 在某個 result（例如標題連結）、切換 scope 後該 result 被隱藏（display: none）— focus 跳到 body。

症狀：使用者 tab 到 result、切 scope、focus 不見了。

第一個該查的：

 1function apply() {
 2  var activeBefore = document.activeElement;
 3  // ... 套用 scope filter
 4  if (activeBefore && getComputedStyle(activeBefore).display === 'none') {
 5    // 該元素被隱藏、focus 移到下一個可見的同類元素
 6    var nextResult = findNextVisibleResult(activeBefore);
 7    if (nextResult) nextResult.focus();
 8    else input.focus();   // 沒有下一個就回到 search input
 9  }
10}

明確處理「focus 元素被隱藏時去哪」、不留給瀏覽器預設行為。

風險 3：Pagefind 重繪結果時 focus 流失

位置：使用者改 query 時、pagefind 重新渲染結果列表。

判讀：若使用者 tab 到第 1 個結果、修改 query、pagefind 替換整個結果列表 — 第 1 個結果被 remove、focus 跳到 body。

症狀：使用者打字過程中、tab 順序時不時被打回起點。

第一個該查的：這個情境較難解 — 框架管的 DOM 我們不能干預。可行的做法：

使用者打字時通常在 input 上、focus 不在結果列表 — 影響面小
若真有需要、用 tabindex / aria-activedescendant 模擬 focus 但不實際 focus DOM

風險 4：載入 pagefind UI 時 focus 行為

位置：頁面載入後 PagefindUI mount 約 200-500ms。

判讀：使用者開啟搜尋頁、瀏覽器把 focus 放 body、使用者按 tab — 應該到搜尋輸入框。

症狀：使用者開頁面立刻按 tab、focus 跳到網站其他部分（nav、其他 link）、不是搜尋框。

第一個該查的：考慮頁面載入後自動 focus 搜尋輸入框（auto-focus）— 對搜尋頁是合理 UX、不是干擾。

1waitForElement(searchRoot, '.pagefind-ui__search-input', function (input) {
2  input.focus();
3});

內在屬性比較：四種 focus 處理策略

策略	維護成本	涵蓋情境	風險
不處理（瀏覽器預設）	低	簡單情境	focus 掉失常見
Save / restore activeElement	中	DOM 移動、隱藏	大多有效
用 tabindex / aria-activedescendant 模擬 focus	高	框架管的 DOM	較複雜、視框架行為
Auto-focus 關鍵元素	低	頁面載入、modal 開啟	使用者預期才適用

選擇順序：簡單變動用 save / restore；framework 管的 DOM 用模擬 focus；關鍵元素用 auto-focus。

盤點 focus 影響的具體步驟

對每個 JS 變動 DOM 的位置、列三個問題：

這個變動會 reparent / remove / hide 哪些元素？
這些元素有可能是當前 focus 嗎？ （form input、checkbox、link 都是常見 focusable）
若是、focus 該去哪？ （restore / next sibling / 預設位置）

回答完三題、變動前後加 save / restore 邏輯。

設計取捨：DOM 變動時的 focus 處理策略

四種做法、各自機會成本不同。這個專案選 A（save / restore activeElement）當預設、其他做法在特定情境合理。

A：Save / restore activeElement（這個專案的預設）

機制：JS 變動 DOM 前 var activeBefore = document.activeElement、變動後 activeBefore.focus()
選 A 的理由：跨瀏覽器一致、簡單元件移動 / 顯隱都涵蓋
適合：自家管的 DOM 變動（reparent、display: none、remove）
代價：每個變動位置要顯式加 save / restore 邏輯（用 helper 包裝可一行）

B：不處理（依瀏覽器預設）

機制：JS 變動 DOM、不主動處理 focus
跟 A 的取捨：B 簡單、A 有額外邏輯；但 B 結果不一致（Chrome / Safari 不同）、多數預設是「focus 跳 body」、使用者迷失
B 才合理的情境：純展示元素變動（沒有 focusable 子元素）— 不會發生 focus 掉失

C：用 tabindex / aria-activedescendant 模擬 focus

機制：focus 物理上不動、用 attribute 標記「邏輯 focus」
跟 A 的取捨：C 比 A 複雜、但能處理 framework 管的 DOM（無法 save / restore）
C 比 A 好的情境：framework 持續重繪元素 identity、save / restore 失敗 — 用 attribute 表達 focus

D：Auto-focus 關鍵元素

機制：頁面載入後 / modal 開啟後自動 focus 預期的第一個元素
跟 A 的取捨：D 不依變動觸發、A 對應變動處理；D 適合「使用者預期」的初始 focus
D 比 A 好的情境：搜尋頁載入 → focus search input、modal 開啟 → focus 第一個 input — 使用者預期的場景才用

判讀徵兆

訊號	該檢查的位置
鍵盤使用者 tab 中途 focus 突然跳走	該時點是否有 JS 變動 DOM
Resize 視窗後 focus 不見	matchMedia callback 內加 save / restore
切 filter / mode 後 focus 在 body	apply 函式內處理被隱藏元素的 focus
開頁面立刻按 tab 跳到不對位置	評估是否該 auto-focus 主要互動元素

核心原則：JS 變動 DOM = focus 副作用。每個變動位置都該回答「focus 該去哪」、不留給瀏覽器預設。

跟 #57 Loading / Empty / End 三狀態共骨：兩者都是「狀態變動需要回答對應的 UX 問題」 — #57 講「使用者看到的訊號」、本卡講「鍵盤使用者的 focus 位置」。動態 UI 設計 = 狀態變動 + 狀態變動的 UX + 狀態變動的 a11y 三個維度同時設計。

Pattern：Document 全文件 query

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

核心做法

1document.querySelector('.target');
2document.querySelectorAll('.target');

從整個頁面找元素、不指定 ancestor scope。

這個做法存在的價值

簡潔。一行就能取到目標、不需要先建立元件根變數。在「我只想快速確認某個元素在不在 / 取它的某個屬性」這類情境下、寫一個 import shell 變數 + null check 是過度工程。

適合的情境

情境	為什麼合理
Devtools console 一行查詢	沒有「未來會壞」的問題、用完就丟
原型 / spike 階段程式碼	預期會被丟棄重寫、不需要長期維護考量
確定全頁唯一的單例（`document.body`、`<html>`）	從定義上不會多個、也不會被誤命中
Build-time script、不會在 runtime 跑	沒有「同頁多元件」的可能性

核心特徵：這段程式不會在多元件 / 動態 DOM 環境長期存活。

不適合的情境

情境	失敗模式
Production 客製、預期長期存活	未來頁面結構變動、誤命中或漏命中
同頁可能有多個同類元件	只取第一個、其他被忽略且不報錯
元件可能在 SPA 路由中動態增減	query 時機跟元件 mount 時機不對齊
寫入第三方函式庫	使用者頁面的其他 class 可能跟你的 selector 撞

安靜失敗是最危險的特徵 — 不報錯、操作了錯元素、bug 表現遠離 root cause。

跟其他起點做法的關係

#14 Selector 精準度的「起點」維度有四種做法、document query 是其中之一：

做法	比較
本卡片：document query	簡潔但不防護未來變動
元件根變數	多一行 setup、換到「shell 內隔離」
起點當參數	多實例支援、適合可能擴展的客製
closest 反向找根	事件委派情境、動態元件

選擇順序：production 客製預設用「元件根變數」、原型 / 探索 / 一次性才用 document query。

邊界：什麼時候 document query 在 production 也合理

幾個常見的 production 例外：

 1// 例外 1：操作的目標就是「全頁面唯一單例」
 2document.body.classList.add('page-search');
 3document.documentElement.setAttribute('data-theme', 'dark');
 4
 5// 例外 2：跨元件邊界的元素（不在任何元件內）
 6var slot = document.querySelector('.search-filter-slot');
 7// (slot 是 main 的子節點、不在 search-shell 內、不能從 shell 找)
 8
 9// 例外 3：頁面層級的 meta 元素
10document.querySelector('meta[name="description"]');

例外都共享一個特徵：目標元素本質上就在「頁面層級」、不是任何元件的內部。

不是例外的場景、即使「當前頁面只有一個」、也用元件根變數 — 預防未來擴展。

判讀徵兆

訊號	該換做法嗎？
「現在只有一個、之後再想」	是 — 換元件根變數
同檔案多處 `document.querySelector('.x')`	是 — 至少改成存變數重用
寫第三方 library 用 document query	是 — 改用根參數 pattern
操作 `document.body` / `<html>`	否 — 這就是合理場景
程式跑一次後丟棄（migration script）	否 — 簡潔優先

核心原則：document query 不是反模式、是有適用範圍的工具。判斷「這段程式預期活多久」 — 短命用 document、長命用元件根。

Pattern：元件根變數 query

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

核心做法

1var shell = document.querySelector('.search-shell');
2if (!shell) return;
3
4var input = shell.querySelector('.pagefind-ui__search-input');
5var drawer = shell.querySelector('.pagefind-ui__drawer');
6// ... 之後所有 query 都從 shell 開始

把元件根 query 一次存變數、所有後續 query 都從這個變數開始。

這個做法存在的價值

把 selector 的作用範圍從「全頁面」收斂到「元件內部」。即使未來頁面其他地方出現同名元素、跟我無關。成本只多一行 query + 一個 null check、防護收益大。

適合的情境

情境	為什麼合理
Production 客製、預期長期存活	未來頁面結構可能變動、需要隔離
當前只有一個元件實例、未來可能加	提早預防、改造成本最低
元件根 mount 後不會被移除	變數生命週期跟元件一致
程式跑在頁面 mount 後（DOMContentLoaded 後）	shell 可被找到

核心特徵：寫的時候只有一個元件、但希望程式碼能容忍未來頁面結構變動。

不適合的情境

情境	為什麼不夠	改用
同頁同時有多個元件實例	變數只存第一個 shell、其他被忽略	起點當參數
元件動態增減（SPA 路由切換）	變數指向 stale DOM	closest 反向找根
一次性 / 探索期程式	過度工程	document query

設計細節

Null check 的時機

1var shell = document.querySelector('.search-shell');
2if (!shell) return;

頁面可能沒有 shell（不是搜尋頁），所有後續 query 都會 null pointer。提早 return 比後續一連串 if (drawer) 乾淨。

等同於宣告：「這段程式只在有 shell 的頁面執行」。

變數的宣告位置

位置	適合
函式內 local 變數	預設、scope 最小
Module scope（IIFE 內）	多函式共用同一 shell
Class instance property	元件本身用 class 包裝時

避免全域變數 — window.shell 容易跟其他 script 撞。

等待 shell mount 的處理

如果 script 跑得太早（shell 還沒 mount），shell 會是 null：

 1// 解法 1：等 DOMContentLoaded
 2document.addEventListener('DOMContentLoaded', function () {
 3 var shell = document.querySelector('.search-shell');
 4 if (!shell) return;
 5 // ...
 6});
 7
 8// 解法 2：MutationObserver 等 mount
 9var bootstrap = new MutationObserver(function () {
10 var shell = document.querySelector('.search-shell');
11 if (!shell) return;
12 bootstrap.disconnect();
13 // ...
14});
15bootstrap.observe(document.body, { childList: true, subtree: true });

選擇取決於 shell 是 server-render 還是 client-render：server-render 用 DOMContentLoaded、client-render 用 observer。

跟其他起點做法的關係

#14 Selector 精準度的「起點」維度有四種做法：

做法	比較
document query	比本卡片簡潔、不防護未來變動
本卡片：元件根變數	多一行設定、隔離未來頁面變動
起點當參數	比本卡片多支援多實例、設計成本前移
closest 反向找根	適合動態元件、不依賴變數綁定的時間

預設用本卡片、需要多實例升級到「起點當參數」、需要動態升級到「closest」。

應用範例：完整 setup

 1function init() {
 2 var shell = document.querySelector('.search-shell');
 3 if (!shell) return;
 4
 5 var ui = shell.querySelector('.pagefind-ui');
 6 var input = shell.querySelector('.pagefind-ui__search-input');
 7 var drawer = shell.querySelector('.pagefind-ui__drawer');
 8
 9 if (!input || !drawer) return; // 元件未完整 mount
10
11 syncScopeHeight(shell.querySelector('.search-scope'));
12 setupFilterSlotSwap(shell, drawer);
13 setupScopeFilter(shell, input);
14}
15
16document.addEventListener('DOMContentLoaded', init);

shell 取一次、各 setup 函式從 shell 派生需要的子節點。

Pattern：起點當函式參數

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

核心做法

1function setupSearchShell(shell) {
2  var ui     = shell.querySelector('.pagefind-ui');
3  var input  = shell.querySelector('.pagefind-ui__search-input');
4  var drawer = shell.querySelector('.pagefind-ui__drawer');
5  // ... 所有 query 從參數 shell 開始
6}
7
8document.querySelectorAll('.search-shell').forEach(setupSearchShell);

元件根不在函式內 query、由呼叫者傳入。函式支援任意數量的元件實例。

這個做法存在的價值

兩件事：

多實例支援免費：forEach(setup) 自動處理多個 shell
純函式特性：函式行為只依賴參數、不依賴外部狀態 — 可單獨測試、可重用、副作用集中

跟元件根變數的關鍵差異：那個 pattern 假設「shell 唯一」、本 pattern 把這個假設外移到呼叫端、函式本身不假設。

適合的情境

情境	為什麼合理
同頁面有多個元件實例（多語切換、相關搜尋）	`forEach` 自動覆蓋全部
元件設計成可被重用到其他頁面	沒有 hardcoded 依賴、容易移植
寫成函式庫 / 第三方 component	使用者可以對任意根節點呼叫
想單元測試函式行為	傳入 mock root 即可測試

核心特徵：把「shell 從哪來」這個責任明確交給呼叫端、函式自己不關心。

不適合的情境

情境	為什麼過度工程	改用
確定全站只有一個元件實例	每函式多一個參數、收益不明顯	元件根變數
元件動態增減、生命週期不可預測	forEach 只跑一次、無法捕捉後加的元件	closest 反向找根
一次性探索程式碼	純函式設計成本不值得	document query

設計細節

函式簽名的設計

 1// 好：shell 是必填參數
 2function setupSearchShell(shell) { ... }
 3
 4// 較差：依賴外部變數
 5var shell;  // module scope
 6function setupSearchShell() {
 7  // 用了外部 shell
 8}
 9
10// 更差：mega object
11function setupSearchShell(allElements) {
12  var shell = allElements.shell;  // 不知道實際依賴什麼
13  // ...
14}

明確參數 = 明確依賴 = 容易測試、容易讀。

內部子函式也接受 shell

 1function setupSearchShell(shell) {
 2  syncScopeHeight(shell);
 3  setupFilterSlot(shell);
 4  setupScopeFilter(shell);
 5}
 6
 7function syncScopeHeight(shell) {
 8  var scope = shell.querySelector('.search-scope');
 9  // ...
10}

每層都明確接受 shell — 不依賴外層 closure。整套函式族都是純函式。

預先抓子節點 vs 每次重 query

 1// 方式 A：函式入口抓所有子節點
 2function setupSearchShell(shell) {
 3  var els = {
 4    ui:     shell.querySelector('.pagefind-ui'),
 5    input:  shell.querySelector('.pagefind-ui__search-input'),
 6    drawer: shell.querySelector('.pagefind-ui__drawer'),
 7  };
 8  // 後續用 els.ui / els.input / els.drawer
 9}
10
11// 方式 B：各子函式自己 query
12function setupSearchShell(shell) {
13  syncScopeHeight(shell);  // 內部自己 querySelector
14  setupFilterSlot(shell);
15}

A 比較有效率（只 query 一次）、B 比較解耦（子函式自包含）。選 B 為預設、效能瓶頸時才考慮 A。

跟其他起點做法的關係

#14 Selector 精準度的「起點」維度有四種做法：

做法	比較
document query	比本卡片簡潔、無多實例支援
元件根變數	比本卡片少一個參數、無多實例支援
本卡片：起點當參數	多實例支援、純函式、設計成本前移
closest 反向找根	比本卡片更動態、不依賴 forEach 時機

升級階梯：document → 元件根變數 → 起點當參數 → closest。複雜度遞增、能處理的情境也遞增。

應用範例：多實例 setup

1// 頁面有 N 個 search-shell（例如多語版面切換）
2document.querySelectorAll('.search-shell').forEach(setupSearchShell);
3
4// 跑完之後：每個 shell 各自獨立 setup、互不干擾

當前頁只一個 shell、上面這行也適用 —forEach 對 1 個元素跑一次、跟 hardcode 單例沒差。做了多實例設計、未來不需要重寫。

應用範例：單元測試

純函式可以對 mock DOM 測試：

1test('setupSearchShell 把 filter 移到 sidebar', function () {
2  var shell = createMockShell();  // 建立測試用 DOM
3  setupSearchShell(shell);
4
5  expect(shell.querySelector('.search-filter-slot').children.length).toBe(1);
6});

不需要全頁面 mount、只需要 mock 一個 shell — 測試成本低。

判讀徵兆

訊號	該套用本 pattern 嗎？
同頁要支援多個元件實例	是 — 直接的好處
想對函式寫單元測試	是 — 純函式才好測
函式內讀 module scope 變數	是 — 改成參數讓依賴顯式
確定永遠只一個實例、且不寫測試	否 — 元件根變數已夠
元件實例 runtime 動態增減	否 — 升級到 closest

核心原則：本 pattern 把「我從哪取得 shell」的答案從函式內搬到呼叫端 — 換到「函式可重用」+「測試容易」+「多實例免費」三個收益、代價是函式簽名多一個參數。當前情境只一個實例也適用、未來擴展不需重寫。

Pattern：closest 反向找根

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

核心做法

1document.addEventListener('click', function (e) {
2  var shell = e.target.closest('.search-shell');
3  if (!shell) return;
4  // 在這個 shell 內處理
5  handleSearchClick(shell, e);
6});

不在初始化時綁定 listener、而是頁面層級委派事件、事件處理時從 e.target 反向找元件根。

這個做法存在的價值

把「找元件根」從「初始化時綁定」延後到「事件發生時動態判斷」 — 換到三個能力：

元件動態增減免處理：新加的元件不需要重新綁 listener
多實例不需要 forEach setup：所有實例共用一個 listener
記憶體效率：N 個元件只綁 1 個 listener、不是 N 個

代價是事件處理邏輯多一層（每次都要 closest 反向找）。

適合的情境

情境	為什麼合理
SPA 路由切換、元件動態 mount/unmount	不需要在 mount 時重綁 listener
元件數量大（>10 個實例）	事件委派比每實例綁 listener 省記憶體
元件透過 AJAX 動態注入	注入後不需要任何 setup 動作
第三方 widget、不能控制元件生命週期	listener 綁在 document、跟 widget 解耦

核心特徵：元件的 mount 時機 / 數量 runtime 才知道、不是初始化時固定。

不適合的情境

情境	為什麼過度工程	改用
元件靜態 mount、生命週期跟頁面一樣	委派多一層、收益不明顯	起點當參數
一個元件實例、永不變動	完全沒必要	元件根變數
需要在元件 mount 時就跑邏輯（不只回應事件）	closest 只在事件發生時跑、無法當 init hook	起點當參數 + MutationObserver

設計細節

Closest 失敗的處理

1document.addEventListener('click', function (e) {
2  var shell = e.target.closest('.search-shell');
3  if (!shell) return;  // 點擊不在任何 shell 內
4  // ...
5});

closest 找不到時回 null、提早 return 是必要防護。沒這個 check 會在頁面其他地方點擊時報錯。

從 closest 結果再往下 query

1var shell = e.target.closest('.search-shell');
2var input = shell.querySelector('.pagefind-ui__search-input');

closest 找到 shell 後、可以從 shell 往下 query 同元件內的其他元素 — 這是「事件 + closest + 局部 query」的組合。

事件類型的選擇

事件	適合
`click`	點擊互動
`input`	輸入框文字變動（需要 bubble）
`change`	選項變動（select / radio / checkbox）
`keydown`	鍵盤快捷鍵
`focus` / `blur`	焦點移動（不 bubble、要用 `focusin` / `focusout`）

注意 focus / blur 不會 bubble — 事件委派要用 focusin / focusout。

委派的根節點選擇

1// 選項 1：document（最寬）
2document.addEventListener('click', handler);
3
4// 選項 2：特定容器（縮範圍）
5var pageContainer = document.querySelector('main');
6pageContainer.addEventListener('click', handler);

縮範圍的好處是「跟其他頁面區域的 listener 不互相干擾」。預設用 document、有干擾風險才縮。

跟其他起點做法的關係

#14 Selector 精準度的「起點」維度有四種做法：

做法	比較
document query	靜態、簡潔、無多實例支援
元件根變數	靜態、shell 唯一假設
起點當參數	靜態多實例、forEach 一次設定
本卡片：closest 反向找根	動態、事件驅動、無 init 時機綁定

複雜度遞增、能處理的動態程度也遞增。最動態的場景才用本 pattern。

應用範例：跨多 shell 的 scope filter

 1function setupGlobalScopeFilter() {
 2  document.addEventListener('change', function (e) {
 3    var shell = e.target.closest('.search-shell');
 4    if (!shell) return;
 5
 6    var scope = e.target.closest('.search-scope');
 7    if (!scope) return;  // 不是 scope 控制的 change
 8
 9    applyScope(shell, scope);
10  });
11}
12setupGlobalScopeFilter();

一個 listener 處理所有 shell 的 scope 變動 — 不論 shell 是初始 mount 的、還是 runtime 注入的。

應用範例：與起點當參數組合

 1// 初始化階段：對已存在的 shell 做 setup
 2document.querySelectorAll('.search-shell').forEach(setupSearchShell);
 3
 4// 事件階段：用 closest 處理可能新加的 shell
 5document.addEventListener('click', function (e) {
 6  var shell = e.target.closest('.search-shell');
 7  if (!shell) return;
 8  // 處理事件、不論 shell 是初始的還是後加的
 9});
10
11// MutationObserver：捕捉新加的 shell 做 setup
12new MutationObserver(function (mutations) {
13  mutations.forEach(function (m) {
14    m.addedNodes.forEach(function (node) {
15      if (node.matches && node.matches('.search-shell')) {
16        setupSearchShell(node);
17      }
18    });
19  });
20}).observe(document.body, { childList: true, subtree: true });

三個 pattern 組合：「靜態 setup」+「事件動態」+「mount 時 setup」 — 各 pattern 補不同時間點的需求。

判讀徵兆

訊號	該套用本 pattern 嗎？
元件 SPA 路由動態切換	是 — 直接對應使用情境
元件數量大、每實例都要綁 listener	是 — 委派省記憶體
AJAX / Web Component runtime 注入	是 — 不需要重綁
確定元件靜態、生命週期固定	否 — 起點當參數已夠
邏輯不是事件驅動（init 時就要跑）	否 — closest 只在事件發生時跑

核心原則：closest 反向找根把「定位元件」從綁定時延後到事件發生時 — 換到動態能力、付出的是事件處理多一層判斷。靜態場景用更簡單的做法、動態場景才升級到本 pattern。

Pattern：DOM attribute idempotency 標記

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

核心做法

1shell.querySelectorAll('.pagefind-ui__result:not([data-scoped])').forEach(function (el) {
2  // ... 處理
3  el.setAttribute('data-scoped', 'true');
4});

apply 函式入口用 :not([data-x]) 過濾掉已處理元素、處理完後設 attribute 標記。下次 apply 被觸發時、已處理的元素不會被命中。

這個做法存在的價值

把「保證只處理一次」的責任從呼叫端（要記得只呼叫一次）轉到元素本身（看自己有沒有被處理過）。

apply 函式可能被多個源觸發：

初始化時呼叫
MutationObserver 偵測到變動觸發
使用者事件觸發
Framework 重繪後重新呼叫

任一個源多呼叫就重複處理 — 無法靠呼叫端紀律避免。Idempotency 標記讓 apply 自己防護。

適合的情境

情境	為什麼合理
Production apply 函式、可能被多源觸發	標記在元素上、不依賴呼叫紀律
處理動作有副作用（綁 listener、改 class）	重複觸發會疊加副作用
元素生命週期跟 attribute 同步（不會被 reset）	標記跟著元素走、自然清理
Devtools debug 友善	attribute 在 inspector 可見

核心特徵：元素的 attribute 跟著元素 DOM 生命週期、元素移除時標記自動消失。

不適合的情境

情境	為什麼不夠	改用
寫第三方 library	在使用者 DOM 加自家 attribute、有命名衝突風險	WeakMap 紀錄
Framework 重繪會清掉 attribute	標記消失、防護失效	配合 disconnect/observe 或改 WeakMap
需要週期性 reset 標記	attribute 改回需要遍歷所有元素	WeakMap 可整批 `new WeakMap()`
多種獨立的 idempotency 維度	DOM 上多 attribute 互相干擾	WeakMap 各別管理

設計細節

Attribute 命名規範

1// 好：明確 namespace + 用途
2el.setAttribute('data-search-scoped', 'true');
3el.setAttribute('data-myapp-processed', 'true');
4
5// 較差：通用名、容易跟其他程式撞
6el.setAttribute('data-processed', 'true');
7el.setAttribute('processed', 'true');  // 不是 data-* 開頭、可能不被 HTML spec 接受

預設用 data-{appname}-{purpose} 格式 — 即使引入第三方 library 加 attribute、也不會撞名。

Attribute 值的選擇

 1// 用法 1：固定 'true'（最簡）
 2el.setAttribute('data-scoped', 'true');
 3
 4// 用法 2：紀錄處理時間 / 版本（debug 友善）
 5el.setAttribute('data-scoped', String(Date.now()));
 6el.setAttribute('data-scoped', 'v2');
 7
 8// 用法 3：boolean attribute（無值）
 9el.setAttribute('data-scoped', '');
10// CSS 用 [data-scoped] 即可選中

預設用 'true'、debug 困難時改 timestamp 看處理順序。

跟 framework 重繪共處

Svelte / React / Vue 重繪元素時、自家 attribute 通常會被保留（framework 只管自己的 attribute）— 但有例外：

情境	行為
Framework re-render 整段 DOM	元素被替換、新元素沒標記 → apply 重跑、合理
Framework patch 既有元素 attribute	自家 attribute 保留
Framework `replaceWith` / `innerHTML` 重設	元素被替換 → 標記消失、apply 重跑、合理

核心觀察：自家 attribute 跟著元素走 — 元素還在就有、元素被換就沒。這是「正確」行為、不是 bug。

例外：framework 主動清自家 attribute

少數 framework 會 strict 清非預期的 attribute（例如某些 Web Component lib）。檢查方式：

1el.setAttribute('data-scoped', 'true');
2// ... 等 framework patch 一次後
3console.log(el.getAttribute('data-scoped'));  // 還在嗎？

如果消失、改用 WeakMap 紀錄。

跟其他 idempotency 做法的關係

#14 Selector 精準度的「過濾」維度有三種做法：

做法	比較
本卡片：DOM attribute 標記	production 預設、devtools 可見、有命名衝突風險
WeakMap 紀錄	不污染 DOM、適合 library、debug 不便
依賴外部呼叫者保證	反模式、無防護、不可靠

預設用本卡片、第三方 library / framework 衝突情境升級到 WeakMap。

應用範例：完整 apply

 1function apply(shell) {
 2  var newResults = shell.querySelectorAll(
 3    '.pagefind-ui__result:not([data-search-scoped])'
 4  );
 5
 6  newResults.forEach(function (el) {
 7    bindClickHandler(el);
 8    addCustomBadge(el);
 9    el.setAttribute('data-search-scoped', 'true');
10  });
11}
12
13// 多源觸發都安全
14init.addEventListener('click', () => apply(shell));
15observer.observe(shell, ...);  // 觀察到變動觸發 apply
16apply(shell);  // 初始化時跑一次

三個觸發點任一個多跑、:not([data-search-scoped]) 都會過濾掉已處理元素。

應用範例：多維度標記

 1// 三個獨立 idempotency 維度、各自 attribute
 2el.setAttribute('data-search-scoped', 'true');     // scope filter 處理過
 3el.setAttribute('data-search-bound', 'true');      // event listener 綁過
 4el.setAttribute('data-search-decorated', 'true');  // 視覺裝飾加過
 5
 6// 各 apply 函式只看自己的 attribute
 7function applyScope(shell) {
 8  shell.querySelectorAll('.x:not([data-search-scoped])').forEach(...)
 9}
10function applyBindings(shell) {
11  shell.querySelectorAll('.x:not([data-search-bound])').forEach(...)
12}

每個 idempotency 維度獨立 — 互相不干擾。

判讀徵兆

訊號	該套用本 pattern 嗎？
Apply 被多源觸發、產生重複處理 bug	是 — 直接對應使用情境
寫第三方 library / 不能污染 DOM	否 — 改 WeakMap
Framework 會清自家 attribute	否 — 改 WeakMap
想在 devtools inspector 直接看處理狀態	是 — attribute 可見性是優點
同元素多種 idempotency 維度	是 — 多 attribute 各自管理

核心原則：把 idempotency 責任從呼叫端搬到元素本身、attribute 是「便宜可見的旗標」。Production apply 預設用本 pattern、特殊情境（library / framework 衝突）才升級到 WeakMap。

Pattern：WeakMap idempotency 紀錄

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

核心做法

1var processed = new WeakMap();
2
3shell.querySelectorAll('.pagefind-ui__result').forEach(function (el) {
4  if (processed.has(el)) return;
5  // ... 處理
6  processed.set(el, true);
7});

把「已處理」狀態紀錄在 JS 的 WeakMap 裡、不寫到 DOM 上。WeakMap key 是元素本身、元素被 GC 時自動清理。

這個做法存在的價值

兩件事 DOM attribute 標記做不到：

不污染 DOM：使用者 DOM 不會被加自家 attribute、適合第三方 library
跟 framework 完全解耦：framework 怎麼操作 DOM 都不影響 WeakMap 紀錄

代價是 debug 不便（看不到狀態）、紀錄跟 JS context 綁定（換頁就消失）。

適合的情境

情境	為什麼合理
寫第三方 library / npm package	不在使用者 DOM 加 attribute、避免命名衝突
Framework 會清非預期的 attribute	WeakMap 不在 DOM、framework 動不到
需要週期性 reset 紀錄	`processed = new WeakMap()` 一行重置全部
紀錄複雜資料、不只是 boolean	WeakMap value 可以是任何物件

核心特徵：紀錄獨立於 DOM 之外、跟 JS 物件 lifetime 綁定。

不適合的情境

情境	為什麼不夠	改用
自家 application、devtools debug 重要	看不到狀態、debug 困難	DOM attribute 標記
跨頁面 / 跨 session 的 idempotency	WeakMap 在 JS context 內、換頁就消失	LocalStorage / 後端紀錄
元素生命週期短、頻繁 GC	WeakMap 自動清理可能比預期早	改用 Map（但要手動清理）
紀錄要跟 SSR 同步	WeakMap 只活在 client	結合 attribute（SSR 階段標記）

設計細節

為什麼用 WeakMap 不用 Map / Set

1// WeakMap：key 是元素、元素被 GC 時 entry 自動消失
2var processedW = new WeakMap();
3processedW.set(el, true);
4// el 從 DOM 移除 + 沒其他 reference → GC → WeakMap entry 消失
5
6// Map / Set：強引用、阻止 GC
7var processedS = new Set();
8processedS.add(el);
9// el 從 DOM 移除、但 Set 還抓著 → 永久 leak

DOM 元素可能動態移除（filter、SPA 路由切換、framework 重繪）— Map / Set 會造成 memory leak。處理 DOM 元素 idempotency 預設用 WeakMap。

Value 的設計

 1// 用法 1：純 boolean（最簡）
 2processed.set(el, true);
 3
 4// 用法 2：紀錄處理版本（升級時偵測 stale 紀錄）
 5processed.set(el, { version: 2, time: Date.now() });
 6if (processed.has(el) && processed.get(el).version === currentVersion) return;
 7
 8// 用法 3：紀錄相關 metadata（避免重複查詢）
 9processed.set(el, {
10  bindingsId: registerListener(el),
11  initialClass: el.className,
12});

WeakMap value 可以儲任何資料 — 比 attribute（只能存字串）更彈性。

Debug 替代方案

attribute 標記可以在 devtools inspector 直接看；WeakMap 看不到。debug 時的替代：

1// 開發模式同步寫一份 attribute（production build 時拿掉）
2function markProcessed(el) {
3  processed.set(el, true);
4  if (DEV_MODE) {
5    el.setAttribute('data-debug-processed', 'true');
6  }
7}

或暴露到 console：

1window.__debug_processed = processed;
2// console: __debug_processed.has($0)  // 檢查當前選中元素

這些都是 workaround、不如 attribute 標記直觀。選 WeakMap 的人通常已經接受這個 debug 成本。

Reset 紀錄

1// WeakMap 整批 reset
2processed = new WeakMap();
3
4// 對比 attribute 整批 reset 要遍歷
5shell.querySelectorAll('[data-scoped]').forEach(el => {
6  el.removeAttribute('data-scoped');
7});

需要週期性 reset（例如 user 切換 mode、所有元素該重新處理）— WeakMap 一行解決、attribute 要遍歷。

跟其他 idempotency 做法的關係

#14 Selector 精準度的「過濾」維度有三種做法：

做法	比較
DOM attribute 標記	production 預設、devtools 可見、有命名衝突風險
本卡片：WeakMap 紀錄	不污染 DOM、適合 library、debug 不便
依賴外部呼叫者保證	反模式、無防護

選擇順序：自家 application → attribute；library / framework 衝突 → WeakMap；反模式不選。

應用範例：library 設計

 1// 第三方 library export 的 init 函式
 2function initSearchEnhancement(shell) {
 3  var processed = new WeakMap();
 4
 5  function apply() {
 6    shell.querySelectorAll('.search-result').forEach(function (el) {
 7      if (processed.has(el)) return;
 8      enhanceResult(el);
 9      processed.set(el, true);
10    });
11  }
12
13  apply();
14  new MutationObserver(apply).observe(shell, { childList: true, subtree: true });
15}
16
17// 使用者：
18initSearchEnhancement(document.querySelector('.my-search'));
19// 不會在使用者 DOM 上加任何 data-* attribute

使用者 DOM 完全乾淨、library 行為內聚。

應用範例：版本化處理

 1var processed = new WeakMap();
 2var CURRENT_VERSION = 3;
 3
 4function apply() {
 5  shell.querySelectorAll('.x').forEach(function (el) {
 6    var record = processed.get(el);
 7    if (record && record.version === CURRENT_VERSION) return;
 8
 9    // 升級到新版本（可能需要清舊綁定）
10    if (record) cleanup(el, record);
11    enhance(el, CURRENT_VERSION);
12    processed.set(el, { version: CURRENT_VERSION, time: Date.now() });
13  });
14}

版本變動時 — 不需要遍歷 DOM 清舊 attribute、直接用 WeakMap value 比對。

判讀徵兆

訊號	該套用本 pattern 嗎？
寫第三方 library / npm package	是 — 不污染使用者 DOM
Framework 會 strict 清自家 attribute	是 — WeakMap 跟 framework 解耦
紀錄需要儲複雜資料（不只 boolean）	是 — WeakMap value 可任意
自家 application、debug 重要	否 — attribute 標記在 inspector 可見
紀錄要跨頁面持久化	否 — 改用 storage / 後端

核心原則：WeakMap idempotency 是 attribute 標記的「不污染 DOM 替代品」 — 在 library / framework 衝突情境必要、在自家 application 通常用 attribute 即可。GC 自動清理是 WeakMap 的特性、預設不用 Map / Set 是因為它們會 memory leak。

Pattern：跨 slot 同節點搬遷

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

核心做法

 1var mql = window.matchMedia('(min-width: 1400px)');
 2function place() {
 3  if (mql.matches) {
 4    desktopSlot.appendChild(filter);
 5  } else {
 6    drawer.insertBefore(filter, drawer.firstChild);
 7  }
 8}
 9mql.addEventListener('change', place);
10place();  // 初始化

同一個 DOM 節點在兩個 slot 之間搬移、不複製成兩份。

這個做法存在的價值

Stateful UI（內含 checkbox 勾選、表單值、scroll 位置等 state）跨兩個顯示位置切換時、複製兩份會造成 state 分歧 — 使用者在 desktop 勾的 filter、切到 mobile 看不到勾選狀態。

搬同一份節點 = state 永遠跟著節點走 = 切換無感。

適合的情境

情境	為什麼合理
Filter UI 跨 viewport 切換顯示位置	checkbox state 跟著節點
Modal 內容 vs 側邊抽屜	同一份表單在兩種展示方式間
Tab UI 跨 desktop / mobile 重新組織	各 tab 內 state 不重置
任何「同 UI、不同位置」的 responsive 切換	不需要 state 同步邏輯

核心特徵：UI 內含 state、兩個位置展示的是「同一個邏輯單位」、不是「兩個獨立元件」。

不適合的情境

情境	為什麼不夠	改用
兩個位置展示的是不同元件（雖然視覺類似）	搬遷會把錯誤元件搬到錯位置	各自獨立掛載、不搬
UI 純 stateless（純圖示、純文字）	複製兩份成本低、無 state 風險	CSS-only 雙顯示 + display 切換
Framework 管的節點	整節點搬安全、但複製不安全（id duplicate / framework 困惑）	必須搬整節點、不複製
兩個位置視覺差異大	搬遷後 UI 不適配新位置	各自獨立元件

設計細節

`appendChild` 是搬遷、不是複製

1parentA.appendChild(node);  // node 從原位置消失、出現在 parentA

DOM API 的 appendChild / insertBefore 是 move、不是 copy — 同一個節點不能同時存在於多個位置。這個特性正是搬遷 pattern 的基礎。

初始放在哪

1
2<div class="pagefind-ui">
3  <div class="drawer">
4    <div class="filter-panel">...div>  
5  div>
6div>
7
8
9<aside class="desktop-filter-slot">aside>

預設放在 fallback 位置 — 當 JS 失敗時仍可見。

跨 slot 切換的時機

matchMedia event 是 viewport 跨過 breakpoint 的瞬間：

1var mql = window.matchMedia('(min-width: 1400px)');
2mql.addEventListener('change', place);
3place();  // 初始也跑一次

不要用 resize event — 太頻繁、會在 breakpoint 邊界震盪。matchMedia 只在 cross 的瞬間觸發。

搬遷時 framework 的 reactivity

如果搬遷的節點是 framework 管的（如 Pagefind 的 svelte 元件）— 整節點搬通常安全、framework 在下次 patch 時看到節點還在、繼續更新內部。

詳細安全規則由 #13 JS 操作 framework 元件：邊界辨識與安全規則處理。

Focus 跟著搬

搬遷可能讓鍵盤 focus 暫時失去（視瀏覽器）— 加 save/restore：

1function place() {
2  var activeBefore = document.activeElement;
3  if (mql.matches) desktopSlot.appendChild(filter);
4  else drawer.insertBefore(filter, drawer.firstChild);
5  if (activeBefore && filter.contains(activeBefore)) {
6    activeBefore.focus();
7  }
8}

詳細處理由 #37 動態 DOM 移動時的 focus 管理處理。

設計取捨：兩個 slot 的 stateful UI 共用

四種做法、各自機會成本不同。預設選 A（搬同節點）、其他做法在特定情境合理。

A：搬同一節點（這個專案的預設）

機制：matchMedia + appendChild 在兩 slot 間搬同一份節點
選 A 的理由：state 跟著節點、切換無感、不需要 sync 邏輯
適合：stateful UI、需要在兩個位置展示同樣內容
代價：搬遷 callback 在 viewport 跨 breakpoint 時觸發、需要處理 focus / 動畫
詳細：本卡片

B：CSS-only 雙顯示 + display 切換

機制：兩個位置都放同一份節點 (寫兩遍 HTML)、用 @media + display: none 切換顯示
跟 A 的取捨：B 純 CSS 簡單、A 需要 JS；但 B 對 stateful UI 失敗（兩份 state 各自獨立）
B 比 A 好的情境：UI 純 stateless（純圖示）、純 CSS 解就夠

C：CSS-only + JS 同步 state

機制：兩份節點 + JS 監聽 state 變動同步
跟 A 的取捨：C 比 B 解 state 問題、但同步邏輯複雜（雙向更新、避免循環）
C 比 A 好的情境：兩個位置的 UI 視覺需要差異（不只是位置不同）

D：JS 完全重建 UI

機制：viewport 變動時拆掉舊 UI、在新位置重建一份
成本特別高的原因：state 在重建時遺失、UI 閃爍、輸入中斷
D 才合理的情境：UI 是 stateless 的、且重建成本低

跟其他 pattern 的關係

#14 Selector 精準度的「起點」維度有四種做法、本卡片是「跨 slot 搬遷」這個專門情境的補充：

議題	對應 pattern
Query 的起點	#46 document / #47 元件根變數 / #48 起點當參數 / #49 closest 反向
Idempotency 過濾	#50 attribute 標記 / #51 WeakMap
跨 slot 搬遷（本卡片）	同節點 vs 雙節點 + state 同步

應用範例：跨 viewport filter 切換

 1function setupResponsiveFilter(shell, breakpoint) {
 2  var filter = shell.querySelector('.pagefind-ui__filter-panel');
 3  var drawer = shell.querySelector('.pagefind-ui__drawer');
 4  var desktopSlot = document.querySelector('.search-filter-slot');
 5
 6  if (!filter || !drawer || !desktopSlot) return;
 7
 8  var mql = window.matchMedia('(min-width: ' + breakpoint + 'px)');
 9
10  function place() {
11    var activeBefore = document.activeElement;
12
13    if (mql.matches) {
14      desktopSlot.appendChild(filter);
15    } else {
16      drawer.insertBefore(filter, drawer.firstChild);
17    }
18
19    if (activeBefore && filter.contains(activeBefore)) {
20      activeBefore.focus();
21    }
22  }
23
24  place();
25  mql.addEventListener('change', place);
26}

完整 pattern：取元件根 + matchMedia + 搬遷 + focus 處理。

判讀徵兆

訊號	該套用本 pattern 嗎？
兩份節點各自 state、用 sync 邏輯保持一致	是 — 改成搬同節點、移除 sync
Stateful UI 在 mobile / desktop 兩種 layout 間	是 — 直接的應用
切換 viewport 時 UI 閃爍 / 重建	是 — 改成搬而非重建
兩個位置展示完全不同的 UI（不是同邏輯）	否 — 各自獨立元件
Framework 管的節點	是 — 整節點搬安全、但要遵守 #13 的規則

核心原則：Stateful UI 的兩個展示位置共用同一份節點、state 自然跟著走 — 比「兩份節點 + sync 邏輯」乾淨。複製兩份是「state 來源從一變二」的隱形多源（違反 #44 SSoT）。

CSS / JS Boundary — CSS / JS 邊界與 specificity 處理

Sun, 26 Apr 2026 00:00:00 +0000

CSS 跟 JS 各自負責什麼、邊界由「值能不能 build-time 定下來」決定。!important / inline style / specificity 戰是訊號、不是工具。

適用：寫 / 改 CSS 規則、決定 styling 該放 CSS 還是 JS、跟 vendor CSS 共存、檔案組織。不適用：純 logic JS（沒涉及 styling）。

自包含聲明：閱讀本文件不需要先讀其他 reference。本文件涵蓋 CSS-only vs JS-assisted 判準、class toggle 模式、CSS layers、variable 單一位置、檔案拆分。

何時參閱本文件

訊號	該做的第一件事
不確定值該寫進 CSS 還是 JS	問「能 build-time 定下來嗎」
即將寫 `!important`	停 — 換 CSS layers 思路
即將寫 `el.style.setProperty(..., 'important')`	停 — 換 class toggle
Inline

JavaScript on Tarragon

JS/TS 平台適配

CORS 限制

Service Worker 攔截

SPA 路由變換偵測

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

核心原則

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

Reconciliation 機制

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

這次任務的具體情境

觀察

判讀

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

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

工具 1：Absolute + 容器 relative

工具 2：Margin spacer 推開 framework 元素

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

工具 4：用 CSS variables 共享尺寸

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

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

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

C：framework 邊界內注入

D：Fork framework source

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

跟其他原則的關係

判讀徵兆

排版精度的工具選擇：CSS-only vs JS-assisted

核心原則

為什麼分工是必要的

商業邏輯

這次任務的工具分配

CSS 處理的部分

JS 處理的部分

兩問判斷法

問 1：這個值在 build time 能定下來嗎

問 2：這個 DOM 變動是 framework 管的嗎

內在屬性比較：兩種工具的特性

邊界誤判的兩種失敗

CSS 解 runtime 問題

JS 解 framework-managed layout

設計取捨：CSS / JS 工具分配策略

A：CSS-first、JS 透過 CSS 變數補 runtime 值（這個專案的預設）

B：純 CSS-only（無 JS）

C：JS-imperative layout（每次重算）

D：CSS magic number 估算 runtime 值

判讀徵兆

JS 操作 framework 元件：邊界辨識與安全規則

核心原則

為什麼邊界要先界定

商業邏輯

邊界宣告的格式

三類操作的安全度

1. 整節點 reparent（安全）

2. 改節點內部子節點（不安全）

3. 改節點自身的 attribute / inline style（灰區）

整節點 reparent：為什麼安全、怎麼做才安全

為什麼安全

安全 reparent 的 do / don’t

跟 framework reactivity 的對齊

改節點內部：為什麼不安全、有什麼例外

為什麼不安全

唯一的例外：靜態元件 + 確認 patch 不重設

改節點 attribute / inline style：灰區的 fail-safe 設計

為什麼是灰區

Fail-safe 工具 1：!important 提升優先級

Fail-safe 工具 2：MutationObserver 補打

Fail-safe 工具 3：CSS class toggle 取代 inline style

這次任務的邊界辨識實例

設計取捨：操作 framework 元件的策略

A：完全不動 framework、客製留邊界外（這個專案的預設）

B：整節點 reparent

C：改節點 attribute + fail-safe

D：改節點內部（最後手段）

邊界宣告的實踐

寫成 JSDoc 或 inline 註解

跟其他原則的關係

判讀徵兆

Selector 精準度：讓 query 只命中你想要的元素

核心原則

Fail-safe 工具 1：`!important` 提升優先級

A：`document.querySelector` 全文件搜

D：事件 + `closest` 反向找根

B：直接子 `:scope > X`

C：特定路徑 `:scope > A > B`

用 `is-X` / `has-X` 表狀態

B：Inline `style.X = ...`