Chrome 外掛程式載入與部署教學

🛡️ 黑科技一：事件攔截與防衝突機制 (Event Propagation Bypass)

開發痛點： 當您點選自製遙控器的按鈕、或拖曳自製的播放進度條時，點擊事件會「冒泡 (Bubble)」傳遞給底層 Instagram 原生的影片容器，觸發 IG 本身的 Click 事件，導致影片又被暫停或靜音，操作感極度不流暢。

黑科技小技巧： 外掛在自製的 progress-container 與遙控器按鈕上註冊 pointerdown 與 click 事件，並在第一時間調用：

e.stopPropagation(); // 阻止事件冒泡，不讓點擊穿透
e.preventDefault();  // 阻止瀏覽器的預設點擊暫停行為

這就像是在 IG 原有介面之上，強行蓋了一層「事件防護罩」，確保遙控器的指令是單向且獨立地直接送給 HTML5 <video>，完全隔絕 IG 原生 JS 監聽器的干擾。

🎯 黑科技二：多影片視區計算與自動定位 (Viewport Visibility Algorithm)

開發痛點： 當使用者快速上下滑動 IG 牆時，DOM 中其實會殘留好幾個 <video> 標籤。這時按下快捷鍵（如「1」播放暫停），外掛要如何精準判定此時該控制哪一個影片，而不是讓看不見的影片在背景亂播？

黑科技小技巧： 外掛並不固定綁定單一 Video，而是在事件觸發時動態計算！透過實時調用 getBoundingClientRect() 計算當前所有影片在 Viewport 中的可見面積：

// 計算可見寬高乘積，找出目前佔螢幕面積最大的 video
const visibleHeight = Math.max(0, visibleBottom - visibleTop);
const visibleWidth = Math.max(0, visibleRight - visibleLeft);
const visibleArea = visibleHeight * visibleWidth;
if (visibleArea > maxVisibleArea) { ... }

這套算法能在毫秒間定位出「目前畫面上可見佔比最大」的 Reels 影片，將熱鍵操作目標動態綁定在它身上，完美解決滑動時的多影片控制衝突。

⚙️ 黑科技三：雙模式儲存適配器 (Dual-Mode Storage Wrapper)

開發痛點： Chrome 擴充功能的 chrome.storage.sync 只能在被載入成正式外掛時運行。如果在一般網頁（例如本地教學測試頁面 mock_instagram.html）測試，就會因為找不到 chrome API 而直接報錯崩潰。

黑科技小技巧： 外掛實作了巧妙的介面適配器模式 (Adapter Pattern)：

const storage = {
  get: (defaults, callback) => {
    if (typeof chrome !== 'undefined' && chrome.storage) {
      chrome.storage.sync.get(defaults, callback);
    } else {
      // 降級 fallback 支援普通網頁的 localStorage
      // ...
    }
  }
};

這使同一份程式碼同時具備「外掛端」與「網頁 PoC 端」的相容性，讓學生即使不載入外掛，也能在本地測試網頁上完整體驗遙控器的倍速、主題切換等功能！

🔄 黑科技四：跨標籤同步與 OLED 即時渲染 (OLED Screen Loop)

開發痛點： 遙控器上的 OLED 螢幕需要顯示目前影片的精確播放進度和倍速。如果每個 DOM 更新都綁定高頻率的 timeupdate 事件，可能導致網頁重繪 (Repaint) 過度頻繁而產生掉幀、卡頓。

黑科技小技巧： 程式在遙控器內部使用了一個 250ms 的輕量級定時循環，實時渲染 OLED 螢幕：

setInterval(() => {
  const video = getActiveVideo();
  if (video) {
    screenSpeed.textContent = `SPEED: ${video.playbackRate.toFixed(2)}x`;
    screenTime.textContent = `${formatTime(video.currentTime)} / ${formatTime(video.duration)}`;
  }
}, 250);

配合 chrome.storage.onChanged 的全域監聽，當使用者在分頁 A 調整了速度或靜音狀態，設定會瞬間寫入 Storage 並廣播，讓所有分頁的遙控器狀態即時同步。

🤝 原版功能重點與致謝 (Acknowledgement & Feature Spotlight)

在此特別致謝 Chrome 線上應用程式商店的 Progress Bar for Instagram 外掛，其創新的設計為本教學專案奠定了關鍵的思路。我們在保留原版優良基礎的同時，透過與 AI 協同進行了深度功能重構與進化：

📄 Content Script (頁面植入腳本)

執行環境： 網頁瀏覽分頁中（宿主網頁環境）。
核心能力： 可以讀取、修改目標網頁的 HTML (DOM) 與 CSS。
AI 開發關鍵： 它是外掛中唯一能碰觸到網頁播放器、加上控制條的元件。如果需要讓 AI 對網頁元素進行修改，請明確命令 AI 將代碼寫在 content.js。
獨立世界機制 (Isolated World)： 它與網頁共用同一個 HTML DOM，但雙方的 JavaScript 變數完全隔離，網頁原生的 JS 腳本無法讀取或竄改外掛腳本的變數，確保安全。

🎨 Popup (控制選單彈出視窗)

執行環境： 點擊工具列圖示時顯示的獨立沙盒視窗。
核心能力： 具備自己獨立的 HTML、CSS 與 JS，相當於一個微型網頁。
限制： **無法直接存取目標網頁的 DOM！** 如果 Popup 內的按鈕需要控制影片，必須透過訊息發送給 content.js。
AI 開發關鍵： 當要讓使用者切換設定（如：是否顯示遙控器、是否啟用快速鍵）時，請叫 AI 在 Popup 中建立 UI 控制項與訊息傳遞發送器。

⚙️ Background (背景 Service Worker)

執行環境： 瀏覽器後台。
核心能力： 監聽全域事件（如安裝、更新、特定分頁建立與關閉）。
重要限制： **不支援 window 或是 document 物件**，沒有 UI 畫面，在 MV3 中以 Service Worker 運行，閒置時會自動暫停釋放記憶體。
AI 開發關鍵： 外掛載入、初始化設定值（如音量或快照）、處理跨網域的 background 網絡請求等全域不間斷邏輯，才需要寫在 background.js。

📦 manifest.json (擴充功能清單)

功能用途： 設定外掛的基本屬性、註冊元件、以及聲明安全權限。
AI 開發關鍵： AI 每次撰寫新的外掛，一定要最先要求它提供 manifest.json。如果在代碼中使用 chrome.storage 卻發現無效，通常是因為 AI 忘記在 manifest 的 permissions 陣列中加上 "storage"。