Template: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 扩展文档。