BUILD-TIME OUTPUT

完整的靜態制縣元件。

這個頁面只由 Node 在建置時輸出 HTML。沒有 custom element、hydration 或瀏覽器端 JavaScript，地圖、統計、分級與 attribution 都已在原始碼內。

Renderer SSR / SSG 0 scripts · 2 SVG maps

先選擇要輸出的範圍

每頁只載入一次對應的 *Styles

renderWidget() 完整制縣卡片 分數、統計、地圖、圖例與 attribution 都交給套件，搭配 widgetStyles。 renderMap() + renderLegend() 地圖加標準分級 頁面已有標題、分數或版面，只保留 SVG 與 0–5 說明。 renderLegend() 只放分級說明 把旅行等級、方法說明與 attribution 放到 sidebar 或 footer。

renderWidget(levels, 'zh-TW', options)

此區塊由 renderWidget() 產生，包含分數、統計、SVG 地圖、0–5 分級與 JapanEx 歸屬。

可組合的 SSR 輸出

不同 idPrefix 可安全共存於同一頁

renderMap()

renderLegend()

0–5 分級

Level 0 · 未踏尚未到訪
Level 1 · 通過交通路過，未下車
Level 2 · 接地下車、轉乘或短暫休息
Level 3 · 到訪觀光或一日活動，未過夜
Level 4 · 住宿至少過夜一次
Level 5 · 居住曾長期生活或工作

同一都道府縣只記最高等級。

Made by HeiTang · Map geometry based on JapanEx (MIT)

三種建置時範例

展開一種，貼進你的 Astro、SSG 或 server component

renderWidget() 完整卡片，適合個人頁、旅行頁與不想寫額外版面的文章。 widgetStyles

這是最短的完整輸出。選擇 theme 與唯一的 idPrefix，其餘內容在建置時完成。

---
import type { PrefectureLevels } from 'japan-prefecture-map/data';
import { renderWidget, widgetStyles } from 'japan-prefecture-map/render';

const levels = { '01': 4, '13': 4, '27': 5 } satisfies PrefectureLevels;
---

<style is:inline set:html={widgetStyles}></style>
<div class="my-japan-map" set:html={renderWidget(levels, 'zh-TW', {
  theme: 'auto',
  idPrefix: 'profile-map',
})} />

只插入一次：widgetStyles 已包含地圖與圖例樣式，不要再插入 mapStyles 或 legendStyles。

renderMap() + renderLegend() 保留你自己的分數、統計與外層版面，只拿標準地圖和圖例。 mapStyles + legendStyles

兩個 renderer 可並排、分欄或放入既有文章版面。它們各自輸出 light DOM HTML。

---
import type { PrefectureLevels } from 'japan-prefecture-map/data';
import {
  legendStyles, mapStyles,
  renderLegend, renderMap,
} from 'japan-prefecture-map/render';

const levels = { '01': 4, '13': 4, '27': 5 } satisfies PrefectureLevels;
---

<style is:inline set:html={mapStyles}></style>
<style is:inline set:html={legendStyles}></style>

<div set:html={renderMap(levels, 'zh-TW', {
  idPrefix: 'article-map',
})} />
<div set:html={renderLegend('zh-TW', { open: true })} />

圖例本身可互動：renderLegend() 輸出原生 <details>。你正在上方看到的圖例不靠任何 client script。

renderLegend() 只需要旅行等級、方法說明與 attribution 時，放進 sidebar 或 footer。 legendStyles

不需要地圖也能使用。這條路徑適合既有頁面已經有自己的地圖或資料視覺化。

---
import { legendStyles, renderLegend } from 'japan-prefecture-map/render';
---

<style is:inline set:html={legendStyles}></style>
<div set:html={renderLegend('zh-TW', { open: true })} />

樣式載入只有一條規則

每頁或共用 layout 只插入一次

mapStyles

純 SVG 地圖的唯一樣式來源。使用 map-only 輸出時，每頁載入一次。

legendStyles

可獨立搭配圖例使用，保留原生 details 與完整 attribution。

widgetStyles

完整卡片的自足樣式，內含 map 與 legend 樣式，適合直接搭配 renderWidget。

再往下客製

CSS token、light DOM selector 與 SVG ID 安全性

--jpm-* 將 token 設在包住 renderer output 的容器上。外層容器

Static renderer 是 light DOM，輸出會直接繼承外層容器的 token。

.my-japan-map {
  --jpm-level-4: #3c9b7c;
  --jpm-level-5: #17684e;
  --jpm-map-font: "Noto Sans TC", sans-serif;
}

idPrefix 同頁輸出兩張以上地圖時，每張都要使用不同前綴。 SVG a11y IDs

這會避免 SVG 的 title、description 與 pattern ID 重複，讓每張地圖仍可被正確標示。

renderMap(homeLevels, 'zh-TW', {
  idPrefix: 'home-map',
});

renderMap(articleLevels, 'ja', {
  idPrefix: 'article-map',
});

:global(.jpm-*) Static output 是 light DOM，可直接選取輸出的 class。 Astro scoped CSS

一般 CSS 可直接使用 .jpm-widget。Astro 的 set:html output 沒有 scoped attribute，因此在元件的 scoped style 內需要用 :global()。

.my-japan-map :global(.jpm-widget) {
  max-width: 56rem;
  border-radius: 1.5rem;
}

.my-japan-map :global(.jpm-summary) {
  padding-block: 2rem 1rem;
}

.my-japan-map :global(.jpm-map-stage) {
  padding-inline: 2rem;
}

需要完整 API、Astro / Next 範例與 class/token 對照時，查看 README 與 Styling guide。

READY TO BUILD?

用自己的旅行資料開始

你已確認頁面要保持零 client JavaScript。回到 Editor 後可設定全部 47 縣，並直接取得這條 Static HTML renderer 路徑的程式碼。

用零 JavaScript 路徑建立地圖需要即時互動？

完整的靜態制縣元件。

先選擇要輸出的範圍

完整靜態 widget

可組合的 SSR 輸出

三種建置時範例

樣式載入只有一條規則

再往下客製

用自己的旅行資料開始