模板:OSM Location map/sandbox/doc

模板功能概覽

此模板提供：

1. 靜態定位地圖： 在框架內顯示來自 OpenStreetMap (OSM) 的地圖，覆蓋全球到單個建築的任意位置和比例。
2. 豐富的標註：
   • 可選的多個標記點（圖像或內置形狀）。
   • 文本標籤（可帶維基連結）。
   • 編號點（圓形、方形、三角形、菱形）。
   • 其他圖形元素（線條、框、箭頭等）。
3. 交互式連結： 右上角提供連結，可打開全屏交互式地圖版本，包含所有標記點的詳細資訊。
4. 上下文微縮圖： 可在地圖一角顯示小型定位地圖（Minimap），提供地理上下文。
5. 比例尺： 右下角顯示粗略的比例尺（注意：地圖投影導致比例隨緯度變化）。

核心優勢： 框架地圖能直接展示精心選擇和編輯的細節與上下文，無需用戶額外交互即可理解主題。全屏地圖則提供探索性交互功能。

核心用法與範例

基礎用法：顯示位置

僅需中心坐標和縮放級別即可顯示一個簡單的地圖。

{{OSM Location map
| coord = {{coord|53.4146|-4.3341}}    <!-- 地图中心点的纬度/经度 -->
| zoom = 15    <!-- 缩放级别：0 (全球) 到 19 (街道) -->
}}

添加標記點與標籤

添加一個預設的紅色標記點 (Red pog) 及其文本標籤。mark-title, mark-image, 和 mark-description 參數用於增強全屏地圖的交互體驗。

{{OSM Location map
| coord = {{coord|53.4146|-4.3341}}
| zoom = 15
<!-- 标记点 -->
| mark-coord = {{coord|53.3966|-4.46204}}  <!-- 标记点的坐标 -->
| label = [[Llanfechell#Llanfechell Triangle|Llanfechell Triangle]]  <!-- 标签文本（可含维基链接） -->
| label-pos = right  <!-- 标签位置：right, left, top, bottom 或方位点如 south, southeast, east -->
| mark-title = [[Llanfechell#Llanfechell Triangle|Llanfechell Triangle]]  <!-- 全屏地图的工具提示/可点击链接 -->
| mark-image = The Llanfechell Triangle - geograph.org.uk - 1260817.jpg  <!-- 全屏显示的图片（Commons文件名，无File:） -->
| mark-description = Located in [[Llanfechell]] <!-- 全屏显示的描述文本 -->
}}

• 標籤連結： 標籤中的維基連結會在框架地圖上顯示為連結。如果連結指向章節（如 #Llanfechell Triangle），框架地圖顯示連結文本，全屏地圖則可能顯示特徵圖片（如果相關頁面存在）。

• 空白模板參考：

  {{OSM Location map
  | coord = {{coord|}}
  | width = 
  | height = 
  | caption = 
  | label = 
  | mark-coord = {{coord|}}
  | label-pos = 
  | mark-title = 
  | mark-image = 
  | mark-description = }}

添加多個標記點

支持無限個編號的標記點。每個標記點有自己的參數集（mark-coord1, label1, label-pos1 等）。mark1 參數集的值會被後續編號點繼承（除非被覆蓋），markD 參數集可提供更通用的預設值。

{{OSM Location map
| coord = {{coord|...}}
| zoom = ...
| mark-coord1 = {{coord|...}}  | label1 = Point 1 | ... <!-- 标记点 1 -->
| mark-coord2 = {{coord|...}}  | label2 = Point 2 | ... <!-- 标记点 2 -->
| mark-coord3 = {{coord|...}}  | label3 = Point 3 | ... <!-- 标记点 3 -->
}}

• 繼承規則： 對於某個標記點參數（如 shape3），查找順序為：shape3 > shapeD > shape1 > 底層預設值。

使用編號點與自動標題

使用 shape = n-circle（或 n-square, n-triangle, n-diamond）建立帶數字的標記點。auto-caption 參數可自動生成圖例。

{{OSM Location map
| coord = {{coord|...}}
| zoom = ...
| shape1 = n-circle  | mark-coord1 = {{coord|...}} | mark-title1 = Location 1 | ...
| shape2 = n-circle  | mark-coord2 = {{coord|...}} | mark-title2 = Location 2 | ...
| auto-caption = 1  <!-- 启用自动图例 -->
}}

• 標籤位置調整： 使用 ldx（水平偏移，-左/+右）和 ldy（垂直偏移，-上/+下）微調標籤位置，避免重疊。label-pos4 = top,with-line | ldx4=8 | ldy4=-37 可將標籤移遠並用線連接。
• 換行字元： 在標籤文本中使用 ^ 進行換行（顯示實際的 ^ 用 ^）。
• 自動圖例 (auto-caption)：
  • auto-caption=1: 生成基本圖例。
  • auto-caption=14: 指定最小列寬（14 em），自動分列。
  • auto-caption=collapsed columns=2: 初始摺疊的 2 列圖例。
• 編號匹配： 框架地圖上的編號應與全屏地圖一致。全屏編號總是從 1 開始順序排列。使用 numbered= 覆蓋自動編號可能導致不匹配。

檢視 {{Flushing Meadows-Corona Park map}} 模板獲取真實範例。

進階功能與技巧

添加圖形元素

地圖可包含各種圖形，如線條 (shape=rule)、箭頭 (shape=curveA/curveC)、框 (shape=box/panel)、自訂形狀（如 diamondD, cross, fivepointstar）等。

• 線條 (shape=rule)： 使用 shape-outline 控制顏色、寬度、不透明度和樣式（實線 solid、虛線 dashed、點線 dotted、雙線 double）。例：shape-outline6=hard grey,2,60,dashed。
• 自訂尺寸： mark-size 可設置寬度和高度（mark-size=44,62），對矩形框 (box) 還可設置圓角 (mark-size=44,62,4)。
• 透明與輪廓： 設置 shape-color=transparent 或低不透明度值（如 shape-color=hard blue, 30）建立透明形狀。shape-outline 定義輪廓。
• 面板 (shape=panel)： 建立資訊框區域。文本放置在內部，label-pos 控制對齊（左/右）和換行。

• 圖例框 (legendBox)： 更便捷地添加圖例。指定位置（相對於地圖左上角的像素）、大小和條目（引用現有標記點的形狀）。例：

  | legendBox=Legend,115px65px1px,175px205px <!-- 标题,宽高边框,位置X,Y -->
  | legendItem1=Major Roman Sites,7 <!-- 文本,标记点编号 -->
  | legendItem2=Medieval Sites,1,42 <!-- 文本,标记点编号,距顶距离(像素) -->

添加微縮地圖 (Minimap)

在角落添加定位地圖提供上下文。

{{OSM Location map
| ...
| minimap = file bottom left  <!-- 位置：file bottom left/right, file top left/right -->
| mini-file = Location_map_UK_Leicester.svg  <!-- Commons文件名，无File: -->
| mini-width = 120  <!-- 宽度(像素) -->
| mini-height = 100 <!-- 高度(像素) -->
| minipog-gx = 38   <!-- 定位点X坐标 (0-100网格，左上角为0,0) -->
| minipog-gy = 60   <!-- 定位点Y坐标 -->
}}

• 定位點： minipog-gx 和 minipog-gy 在覆蓋微縮圖的 100x100 網格上定位（0,0 在左上角）。例如 (38,60)。
• 定位框： 使用 minimap-boxwidth=xx（xx 是框占微縮圖寬度的百分比）替代點，框以 (minipog-gx, minipog-gy) 為中心。

• 簡寫格式 (mini-locator)：

  | mini-locator=Leicester UK ward map 2015 (blank).svg,top left,132px153px,38,60,16
  <!-- 文件名, 位置, 宽px高px, gx, gy, 框宽度% -->

弧線上的文本 (ArcText)

沿曲線放置文本，適合標記河流、海岸線等。

• 標準格式：

  | arc-coordA = {{coord|52.4109|-4.0875}}  <!-- 第一个字母的坐标 -->
  | arc-textA = Afon Rheidol <!-- 文本 -->
  | arc-angleA = -31 <!-- 起始角度(度) -->
  | arc-gapA = 4.5   <!-- 字母间距 -->
  | arc-radiusA = 0.24 <!-- 弧线半径 -->
  | arc-text-sizeA = 11 <!-- 字体大小 -->
  | arc-text-colorA = blue <!-- 颜色 -->
  | ellipse-factorA = 0.98 <!-- 椭圆因子(1=圆) -->

• 簡寫格式 (arcA)：

  | arcA = "Afon Rheidol", 52.4109, -4.0875, 11, blue, -31, 4.5, 0.24, 0.98
  <!-- 文本, 纬度, 经度, 大小, 颜色, 角度, 间距, 半径, 椭圆因子 -->

  更多範例和模式見 Template:OSM Location map/ArcText/doc。

使用地圖數據

• map-data： 添加來自 OpenStreetMap 的行政邊界、道路等（需維基數據 Q 值）。例：map-data=Q83065（萊斯特市邊界）。可添加多個 Q 值（逗號分隔）。
• map-data-heavy / map-data-light： 分別使用更粗/更細的線寬。
• map-data-inverse： 在指定邊界外添加淺灰色遮罩（帶 1px 灰邊）。
• map-data-text： （全屏地圖）點擊線條時顯示的文本（可含連結）。
• map-raw： 直接顯示維基上的 GeoJSON 檔案（如 Wikipedia:Map data/... 或 Commons 的 .map 檔案）。
• map-wdqs： 執行 SPARQL 查詢並在圖上顯示結果點/線/面。

樣式控制

文本顏色 (label-color)：

• • 建議方案：定居點（soft grey）、水域（soft blue）、綠地（soft green）、單個地點（dark grey）、圖例/面板（dark brown）。
  • 避免過度使用紅色（hard red），易與維基紅色連結混淆。
  • 可使用標準顏色名（見下方表格）或十六進制值（如 #AAAAAA）。
  • 設置不透明度：label-color=dark blue, 40（40% 不透明度）。
• 形狀顏色 (shape-color) 與輪廓 (shape-outline)： 類似文本顏色控制，可設置不透明度和線條樣式。
• 文本效果：
  • 換行： 在 label 文本中使用 ^。
  • 無標記的標籤： 設置 mark-size=0。
  • 傾斜標籤： 使用 label-angle=角度（定居點名稱通常不傾斜）。
  • 維基標記： 標籤文本支持 **粗体**、_斜体_ 和 维基链接。謹慎使用 HTML/CSS。

在資訊框中使用

• 如果資訊框支持 map_image 參數，優先使用。
• 或通過 |module={{OSM Location map|...}} 嵌入（例如 {{infobox school}}）。
• 可放在資訊框圖片下方的標題中（需同時存在圖片）。
• 使用 {{switcher}} 可在單個資訊框中切換顯示兩個地圖實例。
• 如果資訊框預設使用 maplink 地圖，檢查是否有機制替換為更豐富的 OSM Location map。

參數速查表

以下是所有可用參數的列表。markD 參數集提供預設值。

Code blank - OSM Location map/sandbox template, listing all the parameters

{{OSM Location map/sandbox | coord = {{coord| | }} | zoom= | float = | width = | height = | fullscreen-option = | caption = | title = | minimap = | mini-file = | mini-width = | mini-height = | minipog-gx = | minipog-gy = | minipog-boxwidth = | scalemark = <!-- optional default settings. These 'D' parameters only create override values for subsequent marks. They make no marks of their own --> | shapeD = | shape-colorD = | shape-outlineD = | shape-angleD = | markD = | mark-sizeD = | mark-dimD = | label-sizeD = | label-colorD = | label-angleD = | label-posD = | ldxD = <!-- short-forms of label-offset-x and -y are now available for all sets--> | ldyD = <!-- unumbered parameter set creates mark and/or label on the map --> | mark-coord = {{coord| | }} | mark = | shape = | shape-color = |shape-outline = | shape-angle = | mark-size = | mark-dim = | label = | label-size = | label-color = | label-angle = | label-pos = | ldx = | ldy = | mark-title = | mark-image = | mark-description= <!-- Arc text (A, B, C ... Z) no shape, mark or fullscreen effect, just text on an arc. Coords are for the first letter (max 26).--> | arc-coordA = {{coord| | }} | arc-textA = | arc-angleA = | arc-gapA = | arc-radiusA = | arc-text-sizeA = <!-- defaults to 12 --> |arc-text-colorA = |ellipse-factorA = <!-- defaults to 1.0 --> <!-- numbered markers. Values set in mark1 will be inherited by all other numbered markers, unless overridden by a 'D' value--> | mark-coord1 = {{coord| | }} | mark1 = | shape1 = <!--image/circle/square/triangle/diamond/rule/box/ellipse/etriangle/panel --> | shape-color1 = |shape-outline1 = <!--color,width,opacity,style--> | shape-angle1 = | mark-size1 = <!--width,height,corner--> | mark-dim1 = | label1 = <!--use ^ to add a newline, this makes labela1 and labelb1 redundant --> | label-size1 = <!--includes extra parameter options: ,outline,background for text effects--> | label-color1 = | label-angle1 = | label-pos1 = <!--position,[line option][,further options] --> | ldx1 = | ldy1 = | mark-title1 = | mark-image1 = | mark-description1= | mark-coord2 ={{coord| | }} | mark2 = | shape2 = | shape-color2 = <!-- ... and so on for all the parameters above --> }}

地圖顯示參數

參數	描述
coord	必需。 地圖中心點的緯度/經度。使用 coord={{Coord|纬度|经度}}。
zoom	必需。 縮放級別 (0=全球, 19=街道)。
float	地圖浮動位置：left, center (或 centre), right (預設)。
width height	地圖寬度和高度（像素，預設 350x250）。
caption	地圖下方的標題文本（可含維基標記、圖片、參考文獻）。
auto-caption	為編號點自動生成圖例：1（基礎）、15（最小寬度15em）、collapsed columns=2（初始摺疊的2列）。
toggletext	設置摺疊圖例的切換文本（如 '[Hide/show points list]'）。
title	地圖上方的標題文本（預設居中粗體）。
legendBox legendItem(n)	在地圖內添加圖例框。legendBox=标题,宽度px高度px边框px,位置Xpx,Ypx。legendItem(n)=文本,标记点编号[,距顶距离px]。
map-data map-data-text map-data-heavy map-data-light map-data-inverse	添加 OSM 數據元素（邊界、道路等，需 Q 值）。map-data-text 設置全屏點擊文本。heavy/light 控制線寬。inverse 添加外部遮罩。
map-raw	顯示原始 GeoJSON 檔案（逗號分隔多個檔案）。
map-wdqs map-wdqs-type	執行 SPARQL 查詢並顯示結果 (geopoint-點, geoline-線, geoshape-面)。
minimap	微縮地圖位置：file bottom left/right, file top left/right。
mini-file	Commons 微縮地圖檔案名稱（無 File:）。
mini-width mini-height	微縮地圖寬高（像素）。
minipog-gx minipog-gy	微縮地圖上定位點的網格坐標 (0-100, 左上角0,0)。
minimap-boxwidth	使用定位框（寬度百分比）替代點。
mini-locator	微縮地圖簡寫：文件名,位置,宽度px高度px,gx,gy,框宽度%。
scalemark	比例尺：1 顯示 (預設)，0 隱藏，數值 向左移動像素。
magnify	(2025+) 放大中心區域 (1.0-2.0)。
nolabels	1 隱藏 OSM 基礎地圖上的標籤（道路名可能仍顯示）。

標記點預設值 (D 參數集)

這些參數為後續標記點設置覆蓋預設值，本身不建立標記點。

參數	描述
shapeD	預設形狀 (image, circle, box, rule 等)。
shape-colorD	預設形狀填充色。
shape-outlineD	預設形狀輪廓 (颜色,宽度,不透明度,样式)。
shape-angleD	預設形狀旋轉角度。
markD	預設標記圖像檔案 (Commons)。
mark-sizeD	預設標記尺寸 (宽[,高[,圆角]])。
label-sizeD	預設標籤字體大小。
label-colorD	預設標籤文字顏色。
label-angleD	預設標籤旋轉角度。
label-posD	預設標籤位置 (left, right, top, bottom, center, 方位點)。
ldxD ldyD	預設標籤水平/垂直偏移（像素, -左/-上, +右/+下）。

標記點參數

參數	描述
mark-coord	必需。 標記點的緯度/經度 ({{Coord|...}})。
mark	標記圖像檔案 (Commons)。預設為 Red pog.svg。
shape	標記形狀 (image, circle, square, triangle, diamond, box, panel, rule, curveA/C, n-circle 等, 或 clip-path 形狀如 diamondD, cross)。
shape-color	形狀填充色（可加不透明度）。
shape-outline	形狀輪廓 (颜色,宽度px,不透明度%,样式)。
shape-angle	形狀旋轉角度（度）。
mark-size	尺寸 (宽px[,高px[,圆角px]])。設 0 僅顯示標籤。
label	標籤文本。用 ^ 換行。支持維基標記 (**粗体**, _斜体_, 链接, 謹慎使用 )。
label-size	標籤字體大小（可加 ,background, ,outline, ,paleground, ,beigeground 增強可讀性）。
label-color	標籤文字顏色（建議使用 OSM 柔和色調）。
label-angle	標籤旋轉角度（度）。
label-pos	標籤位置 (left/right/top/bottom/center/方位点)。可加選項：,with-line, ,n-line, ,mark-line,线宽,样式,间隙, ,photo-panel,图片尺寸,面板宽,面板高。
ldx ldy	標籤水平/垂直偏移（像素）。
mark-title	全屏地圖的工具提示/可點擊連結。設 none 排除在全屏外。含連結會使框架地圖標記點也可點擊。
mark-image	全屏地圖顯示的圖片（Commons檔案名稱，無 File:）。
mark-description	全屏地圖顯示的描述文本。
numbered	覆蓋編號形狀的自動編號（文本）。

弧線文本參數 (A, B, C ... Z)

參數	描述	簡寫參數
arc-coordA	弧線文本起點坐標 ({{Coord|...}})。
arc-textA	顯示的文本。	arcA = "文本", 纬度, 经度, 大小, 颜色, 角度, 间距, 半径, 椭圆因子
arc-angleA	文本起始角度（度）。
arc-gapA	字母間距因子。
arc-radiusA	弧線半徑因子。
arc-text-sizeA	字體大小（預設 12）。
arc-text-colorA	文字顏色。
ellipse-factorA	橢圓因子（1=圓，<1壓扁垂直，>1壓扁水平）。

與 Maplink 的比較

• OSM Location Map:
  • 優勢： 框架地圖能直接展示豐富的手工定製細節（多種標記、形狀、文本標籤、圖形、覆蓋層）。提供更精細的控制和表達力，適合需要特定上下文的地圖。
  • 特點： 靜態框架 + 全屏交互連結。文本標籤在地圖上直接可見。
• Maplink:
  • 優勢： 更側重自動化（通過維基數據 Q 值添加點/線/面）。通常在資訊框中使用，代碼可能更簡潔。
  • 特點： 框架地圖功能較基礎，主要依賴全屏交互。文本標籤通常在全屏顯示。
• 總結： OSM Location map</code> 更适合需要'''在框架地图中直接呈现复杂、定制化信息'''的场景。<code>{{Maplink}} 更擅長快速生成基於維基數據的自動化地圖。兩者功能有部分重疊，但核心目標不同。

更新歷程

• 當前版本 (2025+): 核心基於 Lua/Scribunto 模組。使用 MediaWiki 的 Kartographer 擴展 (<mapframe>) 渲染 OSM 基礎地圖。模組計算坐標轉換（緯度/經度 -> 地圖像素），並使用 內聯 CSS 在地圖上疊加圖形和文本元素。這使得地圖成為頁面的「實時」部分（支持維基標記、連結）。
• 優勢： 高性能（相比舊方案加載快 5 倍）、低資源消耗、支持無限標記點、功能擴展性強。
• 歷史： 曾依賴 {{Graph:Street map with marks}} 和 Vega 庫 (2016-2023)。2023 年 Vega 因安全風險被移除，臨時方案使用純維基模板 + Kartographer。2025 年遷移到 Lua 模組解決性能瓶頸。
• 全屏地圖： 通過 <maplink> 實現，提供平移、縮放、檢視附近文章、顯示標記點詳情等功能。

核心背景：服務中斷與恢復 (2024 年更新)

• 問題起源 (2023 年 4 月): 維基媒體基金會 (WMF) 發現安全漏洞，停用了關鍵的 'Graph' 模組。該模組負責三件事：顯示正確的 OSM 地圖區域、坐標轉換（墨卡托轉頁面坐標）、生成地圖上的符號/圖像/文本。
• 預期與延宕: 最初計劃短暫停用以升級到 Vega v5，但因安全顧慮、性能問題（加載時間長）和未來維護資源的不確定性，升級受阻，停用期延長。
• 技術突破與解決方案:
  • 利用停用期解決了墨卡托坐標轉換的數學問題，使得坐標轉換可通過維基文本實現。
  • 探索並利用了維基百科內置的 CSS 圖形功能和 {{maplink}} 的「覆蓋層」(overlay)能力。
  • 基於以上兩點，成功重建了 OSM 位置地圖的核心功能（顯示、坐標、符號），無需再依賴 'Graph' 模組或 Vega 引擎。
• 目標: 新版本旨在讓約 5,600 張現有地圖恢復接近原始設計的顯示效果（優於僅顯示標記點的臨時方案），並增加新功能。

新版本 (CSS 版) 的局限與差異 (截至 2024 年 3 月)

1. 文本定位 (已解決): 初期最大問題是文本放置。現已可靠解決，文本可精確放置在符號四周「合適的距離」處。
   • 注: 臨時的 jdx= 參數已廢棄，可從模板調用中移除。
2. 尺寸與位置差異: 因代碼和調用方式不同，新版的圖形和文本大小、位置可能與舊版略有差異。目標是大多數地圖視覺上相似。
3. 弧形文本 (ArcText):
   • 舊版需要大量調整（隨縮放和緯度變化）。
   • CSS 版更穩定可預測，但結果與舊版不同，可能需要手動編輯適配。
   • 改進: 文本渲染更優，彎曲更平滑。
4. 光暈功能 (Halo): 因簡化需求，該少用功能在重寫中被省略。可用 shape-outline 模擬類似效果（需社區討論是否恢復）。
5. 大型圖像/覆蓋層定位: 因尺寸模型根本性改變及統一形狀/圖像尺寸的決定，大型透明覆蓋層的位置可能與舊版不同，可能需要重新調整大小和位置。

現已可用的新功能 (2024 年 CSS 版)

• 全屏連結: 直接利用 { {maplink}} 在右上角提供的「全屏連結」框，替代了舊版圖注頂部的文本連結。
• 標記點可點擊連結:
  • 首次實現點擊地圖標記點可跳轉到對應維基條目。
  • 利用 mark-title 中的資訊（也用於自動圖注和全屏）。
  • 行為：維基連結第一個提供的連結（如有多個），鼠標懸停時顯示連結提示。無連結的標記點無動作。
  • 待討論: 是否需要視覺提示表明可點擊？（如演示地圖中的 5 個可點擊點）。
• 行政區劃邊界 (重大新增):
  • 之前僅限於全屏顯示的「願望清單」功能。
  • 現在可直接在頁面內的地圖框架中顯示邊界（及潛在的其他線狀要素）。
  • 限制：只能繪製實線（不能虛線等），但可設置高透明度融入背景。
  • 使用方法：通過 map-data 設置，利用維基數據頁面上的 'Qvalues'。
• 自動圖注分欄: auto-caption= 現在可指定欄寬（單位 em），將編號項列表分成多欄顯示。
• 繪製順序:
  • 舊版：先畫所有形狀，再覆蓋文本。
  • 新版：每個元素（形狀、標籤、編號文本）按順序繪製，後繪製的可能覆蓋先繪製的。
  • 建議: 將重要專案（mark1）視為頂層，編號更大的在下層。若遮擋重要資訊，可能需要重新編號。也可用下文的連接線功能將標籤移出擁擠區。
• 標籤偏移簡寫: 使用 ldx (水平偏移) 和 ldy (垂直偏移) 替代 label-offset-x/y。正值向右/下，負值向左/上 (例: ldx4=-25| ldy4=-15)。廢棄的 jdx= 已無效。
• 多值參數 (簡化模板調用): 多個參數現在接受逗號分隔值：
  • mark-size=: [寬度(px), 高度(px), 圓角半徑(px)] (僅寬度必需)。
  • shape-color=: [顏色, 不透明度(0-100)] (兼容性：1=全透明(舊習慣)，100=不透明，0/未定義=不透明)。取代 shape-opacity=。
  • shape-outline=: [顏色, 線寬(px), 不透明度(0-100), CSS線型(solid/dotted/dashed/double等)]。例: shape-outline=red,8,30,solid 可模擬光暈。
  • label-pos=: 新增了多種繪製連接線的方式（見下文「新圖形元素」）。
• 新圖形元素 (均可用於最多60個標記點):

• • 基礎形狀 (circle, square, diamond, triangle/triangle-up): 寬度=高度，只需一個 mark-size 值。可旋轉(shape-angle=)。可設置顏色和輪廓(shape-color/outline=)。注意： 三角形不能有輪廓（CSS限制）。可加 n- 或 l- 前綴在形狀上顯示數字/字母。
  • 可變形狀 (box, ellipse, triangle): 可設不同寬高 (例: mark-size=34,14)。box 可加第三個值設圓角 (例: mark-size=34,34,3)。
  • 線 (rule): 在坐標點處放置一條線。mark-size= 設置長度。若「高度」>1，則應用 shape-outline 屬性，繪製雙線 (間隙=高度值，例: mark-size=120,10)。
  • 帶箭頭的線/弧 (ruleA, curveA(逆时针), curveC(顺时针)): mark-size= 設長度，shape-angle= 旋轉，shape-outline= 設線及箭頭顏色/粗細/樣式。
  • 資訊面板 (panel): 不同於點狀標記。用於圖例/資訊框。
    • 坐標代表面板左上角（其他形狀是中心點）。
    • 文本預設嘗試放在面板內部 (text-pos=left 在左上角左對齊)。
    • 類似 box, mark-size=W,H,R 設置寬、高、圓角。
  • 圖像 (image): 預設形狀。mark= 指定共享資源檔案名稱。未指定則顯示紅色標記點(pog)。圖像現在可加輪廓(shape-outline=)。圖像比例固定（不被擠壓/拉伸）。非正方形圖像最好提供 mark-dim= 或 mark-size=宽,高 以優化標籤定位。
• 連接線 (作為 label-pos 的附加選項): 有四種方式向地圖添加連接線 (with-line, n-line, mark-line, photo-panel)：
  • with-line: 用 ldx/ldy 指定一個偏移點，從標記畫線到此點，標籤放在該點旁 (例: label-pos2=left,with-line|ldx2=-15|ldy2=-3)。用於將擁擠區域的標籤移到清晰位置。
  • n-line: 類似 with-line，專用於帶編號的形狀。用於將重疊點的編號「拉」出來放在線端。編號也可作為維基連結。
  • mark-line: 從當前形狀 (markX) 向前一個形狀 (markX-1) 畫連接線。不涉及 ldx/ldy 或標籤。label-posX=right, mark-line, 2 畫 2px 粗的線，顏色由 shape-outlineX 決定。可添加線型(solid/dashed/dotted)和間隙大小（>1 畫雙線，例: label-pos-top, mark-line,3, dotted,6)。
  • photo-panel: 建立帶照片（來自 mark-image=）和文本的面板，並帶連接線。需要尺寸參數 (例: label-pos=left,photo-panel,0.8,110)。面板位置由 ldx/ldy 設定。可設置高度 (例: label-pos=left,photo-panel,0,90,24 建立無照片文本面板)。
• 標籤 (label=) 增強:
  • 可顯示帶懸停效果的維基文本（使用 SVG 標記時預設啟用）。
  • 可使用 ^ 添加換行字元 (例: label=Chester~field ^Railway ^Station)。
  • label-size= 新增選項：添加米色背景 (background) 覆蓋複雜底圖；添加 1px 黑色圓角輪廓 (outline) 突出標籤 (例: label-size3=13,background,outline)。
  • 其他控制：label-pos=, label-size=, label-color= (含不透明度), label-angle=, ldx/ldy=。

重大升級：Lua 重寫 (2025 年)

• 核心優勢:
  • 點數無上限: 移除之前 60 個標記點的限制。
  • 性能飛躍: 顯著減少處理時間和資源佔用，頁面加載速度提升約 80%。
  • 完全兼容: 功能等同於 CSS 版，地圖顯示效果「近乎相同」。
  • 弧形文本擴展: 最多支持 26 條弧線 (使用 arc-textA 到 arc-textZ)，替代舊版的 A, B, C。(註： 過多弧線可能影響可讀性)。
• 新增與改進功能:
  • 標籤格式化:
    • label-spacing=：增加字母間距（像素值，預設 0）。
    • label-height=：設置多行標籤的行高（相對於 label-size 的百分比，預設 120）。
  • 標籤位置 (label-pos): 除了 top/bottom/left/right，新增 8 個羅盤點選項 (northeast, southeast, southwest, northwest, north, east, south, west)，減少對 ldx/ldy 調整的依賴。
  • 自動圖注 (auto-caption=):
    • 可指定欄數 (columns=N) 替代欄寬。
    • 可添加 collapsible 或 collapsed 使列表可摺疊/預設摺疊 (例: auto-caption=30 collapsed)。
    • 預設切換文本為 [Hide/show caption list]，可用 toggletext= 自訂 (例: auto-caption=collapsed columns=2| toggletext=[Show/Hide the list of battles])。
  • 高亮功能 (highlight=): 當同一地圖用於多個頁面時，可突出顯示與當前頁面主題相關的特定點。定義 shapeH, shape-outlineH, shape-colorH 等屬性，然後在調用模板時指定 highlight=点编号 (例: {{myOSMmap|highlight=4}})。模板內需傳遞 |highlight={{{highlight|}}}}。

• • 新形狀 (基於 CSS clip-path): 引入一系列帶單層(D)或雙層(DD)「外線」（非真正輪廓）的實心形狀：
    • squareD, squareDD, triangleD, triangleDD, circleD, circleDD, diamond, diamondD, diamondDD
    • thincross, cross, crossD, fivepointstar, fivepointstarD, sixpointstar, sixpointstarD, sevenpointstar, sevenpointstarD, eightpointstar, eightpointstarD, ring
    • (boxD/DD, ellipseD/DD 是 squareD/DD, circleD/DD 的同義詞)。
  • 圖例框 (legendBox=, legendItem(n)=): 在地圖固定位置（相對於左上角，單位px）添加解釋性圖例框。定義尺寸、位置、標題、背景/文本顏色。legendItem 指定解釋文本、關聯點編號及距框頂距離 (px)。自動化程度高，但 panel 形狀提供更精細控制。
  • 放大 (magnify=): 按比例放大所有地圖要素（底圖、標籤、形狀）。用於在縮放級別之間提供中間尺寸。
    • 作用: 當某縮放級別要素太小，而下一級又過大時，提供折中 (例: magnify=1.4 放大 1.4 倍)。
    • 特點: 比例尺數值會相應調整。底圖細節不增加（與真正提高 zoom 不同）。地名也會放大（若太大可 nolabels=1 關閉並自行添加標籤）。
    • 限制: 只能放大 (>1)，不能縮小 (<1)。推薦範圍 1.2-1.5。當前存在與 float=centre 的兼容性問題，建議使用 left/right。
  • 複雜地圖能力: 模板現在能處理高度複雜的 OSM 地圖，支持標籤/符號層、多個數據層（如維基數據中的輪廓、通過 map-raw= 傳遞的 GeoJSON）。允許通過點擊交互探索更多數據（如地質資訊、火山細節），同時初始視圖保持清晰抽象。

另請參閱

• Template:Location map - 基礎單點定位圖。
• Template:Location map+ - 多點定位圖。
• Template:Location map many - 另一種多點定位圖。
• Commons:Category:Map pointers - 大量標記點圖標。
• Template:Overlay - 在圖片上疊加編號標籤。
• Wikipedia:WikiProject Maps - 維基地圖專案資源。
• Module:OSM Location map - 本模板依賴的 Lua 模組。
• Template:OSM Location map/examples - 範例地圖。
• Template:OSM Location map/Return to service - 2025 年更新詳情和功能演示。
• Template:OSM Location map/ArcText/doc - 弧線文本詳細指南。
• Help:Extension:Kartographer - Kartographer 擴展文檔。