今天要解的問題
我的私人旅行網站裡,每趟旅行都有一個「地區」分頁,每個地區上面有一張依座標畫出來的 SVG 示意圖(怎麼畫進去的,在旅途中只開一頁那篇)。它只畫車站和店家的相對位置,沒有街道,好處是離線也看得到。
但到了現場,常常不知道店在哪條巷子、要從哪個路口轉進去,只能跳出去開 Google 或 Naver 地圖,一家一家查,沒辦法一次看到這一區想去的店都在哪些街上。
所以在釜山的途中,我就想說在地區加入 OpenStreetMap 會不會很麻煩,或是有沒有其他地圖相關的做法;另外,目前在用的 Naver Map 有沒有辦法串進來。
想法與取捨
這次是先用 grill-with-docs 把決策樹走完才動手:它一輪問一題、每題附一個建議答案,我一題一題回。走完之後,主軸是這幾條:
- 示意圖不動:照樣離線可看,地圖只是補充。
- 沒點就不連外部:沒按「看地圖」之前,不載入任何地圖資料。
- 看街道和導航分開:看街道用頁面裡的地圖,導航交給外部 App 的地圖連結。
要解的是看街道,還是導航?
這兩個我其實都要。所以拆成兩件事:頁面裡放一張看得到街道的地圖,導航還是交給 Google、Naver 這類地圖連結。
示意圖要不要換掉,我選保留。它離線可看,而地圖要網路,兩個各有用處。
後面用三個詞把它們分開:
- 示意圖:原本的 SVG,只有相對位置,離線可看。
- 地圖:這次新增、可拖拉的地圖,需要網路。
- 地圖連結:開外部 App 的連結。
Naver 只做連結,而且只開 App
Naver 先做連結版,細節是這樣定的:
- 要不要放 Naver,寫在每趟旅行的
trip.json的guide.maps,沒寫就只有 Google。 - 搜尋字先用韓文名稱,沒有就用地址,再沒有才用店名。
- 網址只用
nmap://,只開 App,不用網頁版。
至於把 Naver 地圖整張嵌進頁面,spec 列在不做的範圍:要申請金鑰、登記網域,而且只適用韓國。嵌入的地圖我就直接選 OpenStreetMap(OSM)。
OSM 一定要連網嗎?Leaflet 又是什麼?
選了 OSM 之後,我其實有一串疑問:OSM 是不是固定要連上網路?Leaflet 是什麼?可以只限制在那個地區嗎?
Leaflet 是開源、免金鑰的地圖程式,我選把它放在自己的網站,從自己的網域載入,只在第一次按「看地圖」時才載。OSM 的圖磚要網路才拿得到;我選的做法是限定在該地區的範圍,只快取看過的圖磚,不自己切地圖檔。整區離線(例如 Protomaps 這類自己切的地圖檔)列在以後真的常遇到沒網路再考慮。
OSM 會知道我看了哪一區
後來重讀程式才注意到:點「看地圖」之後,OSM 會從圖磚的網址知道看了哪一區,再加上 IP 和網站的網域。這只在使用者自己點了按鈕之後才發生,我接受,並註明在專案的 CLAUDE.md。
測試直接套在已經結束的旅行
要測就要有完整座標和 Pass 店的資料,所以拿 10/29 那趟釜山來測。專案本來規定結束的旅行停在當時的版本,spec 也寫測完還原,但我覺得測完不需要還原,這趟就直接換上新版的頁面程式。
上線後用手機看,點都疊在一起
地圖上線後,我用手機寬度看了一下,西面站附近的店家點疊在一起,也蓋住了車站名稱,要放大一兩級才分得開。所以再加一個需求:密集的點改成點了才展開的群組。
實作
Naver 連結
guide.maps 決定放哪幾種地圖連結,Naver 的網址只用 nmap://:
// Naver 只開 App(nmap://),沒裝 App 的裝置點了不會有反應
const naverURL = q => 'nmap://search?query=' + encodeURIComponent(q) + '&appname=' + encodeURIComponent(location.hostname);
const MAPS = G.maps || ['google'];
// ...
const mapLinks = (g, nq, cls = '') => [
MAPS.includes('google') ? `<a${cls} href="${esc(g)}" target="_blank" rel="noopener">Google 地圖 ↗</a>` : '',
MAPS.includes('naver') && nq ? `<a${cls} href="${esc(naverURL(nq))}">Naver ↗</a>` : '',
].join('');
店家和住宿呼叫時,搜尋字照 it.kr || it.addr || it.n 的順序取。釜山這趟有 150 家店加 10 個住宿連結,搜尋字全部是韓文。
點了才載入的地圖
照前面「沒點就不連外部」的主軸,示意圖下面多一顆「看地圖」按鈕,點了才載入 Leaflet 和 OSM 圖磚。圖磚來源集中寫在一處,之後要換來源只改這裡:
// 圖磚來源集中在這裡,之後要換只改這裡
const TILE = {
url: 'https://tile.openstreetmap.org/{z}/{x}/{y}.png',
attr: '© <a href="https://www.openstreetmap.org/copyright" target="_blank" rel="noopener">OpenStreetMap</a> contributors',
minZoom: 15, maxZoom: 18,
};
地圖上的店家編號和 Pass 顏色沿用示意圖,範圍限定在該地區。西面的示意圖有 32 個點,其中 9 個沒有座標,地圖上畫出 23 個。Leaflet 1.9.4 從 npm 原樣複製,js 約 148 KB、css 約 15 KB。
看過的圖磚由 service worker 存起來,上限 2,000 張,超過就刪最舊的:
// 地圖的圖磚:只存看過的(OSM 規定不能整區預先下載),最多 TILE_MAX 張,超過就刪最舊的
const TILES = 'ts-tiles-v1';
const TILE_HOSTS = new Set(['tile.openstreetmap.org']);
const TILE_MAX = 2000;
// ...
async function tileFirst(event, url) {
const cache = await caches.open(TILES);
const hit = await cache.match(url.href);
const age = hit ? Date.now() - Number(hit.headers.get('X-Fetched-At') || 0) : Infinity;
const limit = hit ? tileAge(hit) : null;
if (hit && age < limit.fresh) return hit;
const refresh = fetchTile(event, cache, url);
if (hit && age < limit.stale) {
event.waitUntil(refresh.catch(() => {}));
return hit;
}
try {
const res = await refresh;
return !res.ok && hit ? hit : res;
} catch {
return hit || new Response('', { status: 504 });
}
}
tileAge 讀的是 OSM 回應的 Cache-Control:max-age 內直接用快取;過期但還在 stale-while-revalidate 內,先給快取、背景更新;再更舊就先問網路,沒網路才用舊的。離線時,沒看過的地方會出現「離線:只顯示看過的範圍,其他地方請看上面的示意圖」。
群組
群組用 Leaflet 的外掛 Leaflet.markercluster 1.5.3,跟 Leaflet 放在一起,點「看地圖」時一起載入。檔案約 34 KB,和 npm 上的版本逐位元組相同、sha512 相符。
// 店家點:擠在一起的併成群組(圈裡是家數),點群組放大到分得開,最大縮放仍重疊就攤開;車站不併
const group = Lf.markerClusterGroup({
// ...
maxClusterRadius: 30, showCoverageOnHover: false, spiderfyOnMaxZoom: true, removeOutsideVisibleBounds: false,
iconCreateFunction: c => {
// 群組裡有 Pass 店:只有一組就用那組顏色,A、B 都有就用雙色外圈
const ps = new Set(c.getAllChildMarkers().map(m => m.options.pass).filter(Boolean));
const pass = ps.size > 1 ? ' big3-mix' : [...ps].join('');
const n = c.getChildCount();
return Lf.divIcon({ className: 'om-cl', html: `<span class="ocl${pass}" title="${n} 家店,點了展開">${n}</span>`, iconSize: [32, 32], iconAnchor: [16, 16] });
},
});
只有真的擠在一起的點才併(半徑 30px),點了放大到分得開,到最大縮放還重疊就攤開。手機寬度下,西面的 23 家變成 4 個群組加 5 個單獨的點。
踩到的坑
OSM 的使用規定,是事後才補的
第一版圖磚快取寫好時,是「存了就永遠用」,也沒確認 Referer。之後我才想說:用 OSM 會有什麼著作權,或有什麼要注意的?才回頭去讀 OSM 的 tile usage policy,讀到的是這四條:
- 要標「© OpenStreetMap contributors」
- 要照
Cache-Control更新 - 不能擋 Referer
- 不能整區預先下載,或做離線包
整區預先下載本來就沒做,前三條都修。標示放在地圖右下角;快取改成上面那個照 Cache-Control 的 tileFirst。
Referer 比較麻煩:網站整體設了 Referrer-Policy: same-origin,跨站請求不帶 Referer,所以地圖的圖磚請求要另外改成只送網域:
Lf.tileLayer(TILE.url, {
attribution: TILE.attr, maxZoom: TILE.maxZoom,
// CORS 模式才存得進離線快取;OSM 規定要帶 Referer,網站預設不帶,這裡只送網域
crossOrigin: 'anonymous', referrerPolicy: 'strict-origin-when-cross-origin',
})
ETag 讀不到
照 Cache-Control 更新,要發條件式請求就需要 ETag,但 OSM 沒有 expose ETag,在 service worker 裡讀不到。最後改成讓瀏覽器自己的 HTTP 快取去發條件式請求,service worker 只看 max-age 和 stale-while-revalidate。OSM 回應的 max-age 約 15,000 秒、stale-while-revalidate=604800,也就是約 4 小時內直接用,7 天內可以先用舊的。
群組外掛漏畫點
加了群組之後,手機寬度下西面 23 家只畫出 18 家。查到是地圖設了 zoomSnap: 0.5,縮放會停在 14.5 這種半級,而群組外掛在非整數級會漏點,所以改成只用整數級縮放:
// 縮放只用整數級:群組外掛在 14.5 這種級數會漏畫點
const map = Lf.map(box, { maxBoundsViscosity: 1, maxZoom: TILE.maxZoom });
改成整數級之後,地圖拖不動
但改成整數級,窄螢幕上又出事:fitBounds 往下取整,看到的範圍比允許拖動的範圍還大,maxBoundsViscosity: 1 讓地圖直接卡死。這個修了三輪才穩:
- 先讓拖動範圍包住打開時的畫面。但重讀一次才發現,縮小或手機轉向後又會卡住。
- 改成縮小的下限跟著拖動範圍走。結果這樣一打開地圖,縮小鈕就被停用了。
- 最後改成拖動範圍是「地區外框往外 60%,再包住縮到最小時的畫面往外 30%」,版面大小改變時重算。
// 拖動範圍:地區外框往外留一點,並包住「縮到最小時、以地區中心為中心」的畫面再往外 30%。
// 範圍不比畫面大時 maxBoundsViscosity 會讓地圖拖不動;版面大小改變(轉向、跨過 sidebar 斷點)時重算
const limitRoam = () => {
const half = map.getSize().divideBy(2), p = map.project(bounds.getCenter(), low);
const view = Lf.latLngBounds(map.unproject(p.subtract(half), low), map.unproject(p.add(half), low));
map.setMaxBounds(bounds.pad(0.6).extend(view.pad(0.3)));
};
小結
現在地區頁有三種「地圖」:示意圖照樣離線可看;示意圖下面的「看地圖」點了才載入 OSM,看過的圖磚留在手機裡,擠在一起的店併成群組;導航交給 Google 和 Naver 的地圖連結,Naver 只開 App。
