第八章：行動裝置優化 - 解救手機版地圖地獄

當你在電腦的瀏覽器上開發完地圖，覺得一切都很完美、滑鼠滾輪縮放也很順暢時，你興高采烈地用手機打開它準備驗收... 然後災難就發生了。

當你想要往下滑動網頁看地圖下方的營區介紹文字時，你的手指只要一碰到地圖的區域，整個網頁就不動了，變成只有地圖在瘋狂平移！你被困在地圖裡，永遠滑不到網頁的最底部。這是所有網頁地圖開發者在手機版上最常見、也最讓人崩潰的「滾動陷阱 (Scroll Trap)」。

🎯 本章目標

深入理解為何手機版地圖會干擾頁面滑動。
實作業界標準的「雙指縮放」與「雙指平移」防呆機制。
確保你的地圖專案在交付給客戶時，不會因為 UX 極差而被退貨。

📱 為什麼手機版地圖會卡住整個網頁？

在電腦螢幕上，使用者的行為邊界非常清晰：

游標在視窗旁邊：捲動網頁。
游標在地圖內部滾動滾輪：縮放地圖。

但在手機那狹小的直立螢幕上，使用者習慣用單指在螢幕正中央「上下滑動」來瀏覽整個長網頁。如果你的地圖剛好佔了手機螢幕的一大半面積 (例如高度佔了 60%)，使用者的單指滑動就會立刻被 Leaflet 地圖引擎攔截。 Leaflet 會以為使用者是想要「往下拖曳地圖」，而不是「往下捲動網頁」。導致網頁捲軸死當，使用者體驗極度糟糕。

🛠️ 第一步：請 AI 實作雙指手勢防呆機制

要解決這個問題，我們需要做一點客製化邏輯：「在手機版上，單指滑動不會拖曳地圖 (讓網頁正常捲動)，必須明確使用兩根手指頭，才能移動或縮放地圖。」

在傳統開發中，要自己去抓原生瀏覽器的 touchstart 與 touchmove 事件來判斷有幾根手指頭，會寫出幾百行非常複雜的程式碼。但身為 Vibe Coder，我們只要一句話就能解決。

🔥【Vibe Prompt 實戰咒語】 我正在用 React-Leaflet 開發地圖，但我遇到了手機版的「滾動陷阱 (Scroll Trap)」問題。 當地圖在手機上顯示時，使用者的單指滑動會被地圖攔截，導致無法上下捲動網頁。 請幫我引入業界標準的解決方案 (如 leaflet-gesture-handling)。 需求如下： 1. 當使用者在手機上用單指觸碰地圖時，地圖不要移動，網頁正常捲動。並且在地圖中央浮現一個半透明的暗色遮罩，顯示提示文字「請使用雙指移動地圖」。 2. 當使用者在電腦上用滑鼠滾輪滾動時，提示「請按住 Ctrl 鍵並捲動以縮放地圖」。 3. 給我完整的安裝指令，以及要在 <MapContainer> 裡修改的 props 與 CSS import。

AI 收到指令後，通常會推薦你使用 leaflet-gesture-handling 這個超強的開源套件，它就是為了解決這個痛點而生的。

實作步驟概覽：

終端機安裝套件：

npm install leaflet-gesture-handling

在你的地圖元件中引入與啟用：

// 記得引入 css，否則遮罩提示字出不來
import 'leaflet-gesture-handling/dist/leaflet-gesture-handling.css';
// 匯入套件使其掛載到 Leaflet 引擎上
import 'leaflet-gesture-handling';

export default function MyMap() {
  return (
    <MapContainer
      center={[23.5, 121.0]}
      zoom={7}
      // 關鍵！開啟手勢處理魔法
      gestureHandling={true} 
      className="w-full h-[600px]"
    >
      <TileLayer url="https://{s}.tile.openstreetmap.org/{z}/{x}/{y}.png" />
    </MapContainer>
  )
}

就這麼簡單加上一個參數！現在，拿起你的手機測試看看。當你用單指滑過地圖時，網頁會非常順滑地上下捲動，而地圖上會浮現一個優雅的灰色遮罩提示：「使用雙指移動地圖」。只有當你老老實實用兩根手指放上去時，地圖才會開始平移或縮放。

⚠️ [常見地雷區] 忘記引入 CSS 導致黑屏

在實作 leaflet-gesture-handling 時，新手最常犯的錯就是忘記引入它的 CSS 檔案 (import 'leaflet-gesture-handling/dist/leaflet-gesture-handling.css')。

如果你只設了 gestureHandling={true} 卻沒有引入 CSS，當使用者用單指滑動時，雖然成功阻擋了地圖移動，但因為沒有 CSS 樣式，那個用來提示使用者的半透明遮罩會變成一個醜陋的黑色方塊，或者文字排版整個大亂，導致使用者完全不知道發生了什麼事，以為網站壞掉了。請務必確保 CSS 正確載入！

💼 [商業應用場景] UX 決定了你的專案報價

在開發任何面對大眾的應用程式 (B2C) 時，永遠要記住一個殘酷的數據：超過 70% 到 85% 的使用者，是用手機開啟你的網站的。

如果你幫客戶做的地圖網站，在電腦上看起來很炫，但客戶用自己的 iPhone 點開時，滑兩下就卡在地圖裡出不來，客戶會立刻認定這是一個「廉價的半成品」，並要求扣你的尾款。

這個看似不起眼的 gestureHandling 設定，正是區分「業餘大學生作品」與「商業級企業產品」的關鍵細節！當你在提案時，主動拿著手機向客戶展示：「老闆你看，我們的系統有特別為手機用戶做手勢防呆，不會卡住網頁。」客戶會覺得你無比專業，你的 10 萬塊報價也就顯得合情合理了。

下一章，我們將帶你直擊 Leaflet 開發中最常出現的靈異現象，並教你如何快速 Debug！