台灣縣市方塊地圖（React）
22 縣市方塊格地圖的 React 元件，不需任何地理資料：依數值著色的 choropleth、hover 提示卡、點選回呼與鍵盤方向鍵巡覽，可當作視覺化篩選器。
這是 WebberUI Pro 元件
上線活動期間免費：註冊或登入後，在上方預覽區按「複製安裝指令」就能直接安裝，不需付費、不用綁信用卡。下方那條指令未登入時會回 401。
像美國州別 tile-grid map 那樣，用等大的圓角方塊排出台灣輪廓——本島由北到南、離島靠左，5 欄 × 11 列就是整張圖，不必載入任何 GeoJSON 或投影函式庫。傳入 data（縣市代碼或名稱 → 數值）即依大小內插上色，沒有資料的縣市留淡灰；hover 或聚焦格子時抬升並浮出名稱與數值，點選則加上外框與勾選徽章並回呼，天生適合當門市分佈、疫情或銷售統計的視覺化篩選器。內建 22 個行政區的代碼、全名、縮寫與預設格位（TAIWAN_REGIONS），格位可用 layout 逐一覆寫。
載入預覽⋯
npx shadcn@latest add "https://webberui.com/r/taiwan-tile-map.json?t=<安裝 token>"Playground
即時調整 props、程式碼片段同步更新——直接試出你要的樣子再複製。
<TaiwanTileMap />
安裝
npx shadcn@latest add "https://webberui.com/r/taiwan-tile-map.json?t=<安裝 token>"或在 components.json 設定 registries 後，改用 @webberui/taiwan-tile-map 安裝。
使用
import { TaiwanTileMap, TAIWAN_REGIONS } from "@/components/ui/taiwan-tile-map";
// 鍵可以是代碼（TPE）或縣市名（臺北市／台北市），沒列出的縣市會顯示為無資料
const storeCounts = { 臺北市: 128, 新北市: 176, TXG: 104, KHH: 98, 澎湖縣: 3 };
<TaiwanTileMap
data={storeCounts}
labels="short"
onSelect={(code, selected) => console.log(code, selected)}
/>
// 多選當篩選器，並固定色階範圍（跨月份比較時顏色才一致）
<TaiwanTileMap
data={storeCounts}
multi
domain={[0, 200]}
colors={["#e0f2fe", "#075985"]}
labels="value"
tooltipFormatter={(region, value) => `${region.name}：${value ?? 0} 家`}
/>
// 內建常數可拿來產生選單、對照表或自訂格位
TAIWAN_REGIONS.map((r) => r.code); // ["LIE", "KIN", "PEN", "TPE", ...]Props
| Prop | 型別 | 預設值 | 說明 |
|---|---|---|---|
data | Record<string, number> | — | 各縣市數值，鍵可為代碼（TPE）或縣市名（臺北市／台北市）；沒有資料的縣市以淡灰呈現 |
colorScale | (t: number) => string | — | 自訂色階函式：輸入 0..1 的正規化值，回傳任意 CSS 顏色；提供時優先於 colors |
colors | [string, string] | ["#d1fae5", "#047857"] | 兩端顏色 [最淺, 最深]（hex），以 RGB 線性內插 |
domain | [number, number] | — | 固定色階的 [min, max]；不提供時自動取資料的最小／最大值 |
labels | "name" | "short" | "value" | "none" | "short" | 格內文字顯示模式：全名、縮寫、數值或不顯示 |
selected | string | string[] | null | — | 受控選取：縣市代碼（或名稱）；multi 時為陣列，null 表示未選取 |
defaultSelected | string | string[] | null | null | 非受控模式的初始選取 |
onSelect | (code: string, selected: string[]) => void | — | 點選格子時回呼：code 為剛切換的縣市代碼，selected 為切換後的完整選取清單 |
multi | boolean | false | 是否允許多選（再次點選同一格可取消） |
showLegend | boolean | true | 是否顯示底部的漸層圖例（min／max 與無資料色塊） |
noDataLabel | string | "無資料" | 無資料時在提示卡與圖例顯示的文字 |
tooltipFormatter | (region: TaiwanRegion, value: number | undefined) => React.ReactNode | — | 自訂 hover 提示卡內容；回傳節點會取代預設的「名稱＋數值」 |
valueFormatter | (value: number) => string | zh-TW 千分位 | 數值格式化，用於格內 value 標籤、提示卡與圖例 |
layout | Partial<Record<string, readonly [number, number]>> | — | 覆寫個別縣市的格位：代碼 → [col, row]；未列出的縣市沿用預設 |
size | "sm" | "md" | "lg" | "md" | 尺寸預設：控制地圖最大寬度、格距、圓角與字級 |
aria-label | string | "台灣縣市方塊地圖" | 最外層群組的無障礙標籤 |
className | string | — | 透傳到最外層容器 |
TaiwanRegion
TAIWAN_REGIONS 常數的每一筆，也是 tooltipFormatter 的第一個參數。
| 欄位 | 型別 | 預設值 | 說明 |
|---|---|---|---|
code | string | — | 縣市代碼（採 ISO 3166-2:TW 的三碼英文，例如 TPE） |
name | string | — | 官方全名，例如「臺北市」 |
short | string | — | 一至二字縮寫，例如「北」「竹市」 |
layout | readonly [col: number, row: number] | — | 預設格位，左上為 [0, 0]、往右往下遞增 |
另外具名匯出 TAIWAN_REGIONS（22 筆 TaiwanRegion）、resolveTaiwanRegion(key)（以代碼或縣市名查詢，「臺」「台」皆可）以及 TaiwanTileLabel、TaiwanTileMapSize 型別。
細節
- 預設格位：連江
[0,1]、金門[0,2]、澎湖[0,7]；臺北[3,0]、基隆[4,0]；桃園[2,1]、新北[3,1]、宜蘭[4,1]；新竹市[1,2]、新竹縣[2,2]；苗栗[2,3]；臺中[2,4]、南投[3,4]、花蓮[4,4]；彰化[1,5]；雲林[1,6]；嘉義市[1,7]、嘉義縣[2,7]、臺東[4,7]；臺南[1,8]；高雄[1,9]；屏東[2,10]。格網用 CSS grid（repeat(5, minmax(0, 1fr))搭配aspect-square），欄數依格位自動計算，覆寫layout時整張圖跟著重排。 - 著色：先把每個值正規化到 0..1（
(value − min) / (max − min)，範圍來自資料或domain），再交給colorScale，或在colors兩端之間做 RGB 內插；只有一個值時直接視為最深色。格內文字會依方塊顏色的 WCAG 相對亮度自動切換深淺，自訂色階回傳無法解析的顏色（如hsl()）時退回依 t 值判斷。 - 提示卡：由 hover 或鍵盤聚焦觸發，頂端兩列往下開、其餘往上開，最左／最右欄靠邊對齊，不需量測也不會超出地圖範圍。
- 進場動畫：各格依
row交錯淡入放大，同列再依col微幅錯開，視覺上像由北到南鋪開；覆寫layout或切換size時，格子位置以 layout 動畫平滑移動。
可及性
- 格網為
role="group"並帶aria-label（可自訂），顯示圖例時以aria-describedby連到圖例；每個縣市是type="button"的按鈕，aria-label包含全名與數值（或無資料文字），aria-pressed反映選取狀態 - 採 roving tabindex：整張圖只佔一個 Tab 停點，方向鍵優先沿同欄／同列移動、該方向沒有格子時斜向跳到最近的一格，
Home/End跳到第一／最後一格，Enter/Space切換選取，Esc收起提示卡；焦點格有focus-visible外框 - 選取狀態變化寫入
aria-live="polite"的隱藏區域（例如「已選取 臺北市、桃園市」），選取格另加勾選徽章，不只靠顏色辨識；提示卡與圖例色條標記aria-hidden - 使用者系統開啟「減少動態效果」時，停用進場交錯、hover 抬升與 layout 位移動畫，提示卡改為直接顯示／隱藏，顏色與外框回饋不變