內容簡介
GPX Route Map 外掛可將 GPX 檔案轉換為互動式地圖，讓訪客在網站前端輕鬆查看路線和相關資訊，提升使用者體驗。
【主要功能】
• 支援 GPX 路徑和路線的顯示
• 提供互動式地圖，使用 MapLibre GL
• 顯示起點和終點標記
• 顯示統計數據：距離、高度等
• 可選擇不同的地圖樣式
• 支援自訂的路徑標記和描述
外掛標籤
開發者團隊
原文外掛簡介
GPX Route Map turns a GPX file into an interactive map on the front end of your site. Drop the block into any post or page, pick a .gpx file, and visitors get:
An interactive map powered by MapLibre GL, on OpenStreetMap, OpenTopoMap or Thunderforest tiles.
The track drawn as a route line with start and end markers.
Support for both GPX tracks (
Waypoint markers with popups for any
Optional Waypoint posts (experimental), to give a waypoint its own description, a photo shown as its marker, or an icon in your own colors.
A stats bar: distance, elevation gain, elevation loss, max and min elevation, in metric or imperial units.
A hand-drawn elevation profile you can scrub with mouse or touch, the position syncs onto the map.
The map loads lazily (only when it scrolls into view) so it never slows down your page, and multiple maps can live on the same page.
You can author tracks in any GPX tool, for example the free gpx.studio editor, then upload the resulting file to your Media Library.
Source code
The front-end JavaScript in build/ is minified (the block editor script is not, so that its strings stay translatable). The human-readable source lives in the plugin’s src/ directory, which is included in this plugin, and is also available with full build instructions at the public repository: https://github.com/SirLouen/gpx-route-map. The plugin is built with Vite (pnpm install && pnpm run build).
External services
This plugin renders maps using map images (tiles) served by a third party. Tiles are loaded directly by each visitor’s browser when a page containing a map is viewed, so the tile provider receives that visitor’s IP address, browser User-Agent, and the coordinates of the map area being viewed. The block editor’s map preview loads tiles the same way, from the browser of whoever is editing the post. No data is sent when a page has no map on it, and the plugin never sends your GPX files anywhere.
OpenStreetMap (default)
Out of the box the plugin uses OpenStreetMap’s public tile server at tile.openstreetmap.org. No account or key is needed, and nothing has to be configured.
Service: OpenStreetMap. Terms: Tile Usage Policy. Privacy: OSMF Privacy Policy.
The public OSM tile server is rate-limited and is not intended for high-traffic sites.
Thunderforest (optional)
If you choose a Thunderforest style under Settings > GPX Route Map, or for a single map in its block or with the shortcode’s provider attribute, and enter an API key under Settings, tiles are loaded from api.thunderforest.com instead, and your API key is included in each tile request. This only happens once a Thunderforest style is chosen and a key supplied; the plugin never contacts them otherwise.
Because visitors’ browsers load the tiles, the key is visible in your pages’ source. Thunderforest does not offer a way to restrict a key to your domain, so treat the key as public and keep an eye on your usage.
Service: Thunderforest. Terms: Thunderforest Terms and Conditions. Privacy: Thunderforest Privacy Policy.
OpenTopoMap (optional)
If you choose OpenTopoMap under Settings > GPX Route Map, or for a single map in its block or with the shortcode’s provider attribute, tiles are loaded from tile.opentopomap.org instead. No account or key is needed. This only happens once OpenTopoMap is chosen; the plugin never contacts it otherwise.
OpenTopoMap is run by volunteers, with no guarantee that it stays available, and its maps have less detail close in than OpenStreetMap’s.
Service: OpenTopoMap. Terms: Usage terms (in German). Privacy: OpenTopoMap publishes no privacy policy; its operator is named in the imprint.
Any other provider
If a developer points the plugin at another tile server with the gpxrm_tile_url filter, the same applies to whichever server that is.
Usage
Block: search for “GPX Route Map” in the block inserter, then choose a GPX file.
Shortcode: [gpx_route_map]
Examples:
[gpx_route_map id="123"] - render the GPX attachment with ID 123.
[gpx_route_map gpx="https://example.com/route.gpx" height="520" elevation="false"]
Shortcode attributes:
id – Attachment ID of a .gpx file uploaded to the Media Library.
gpx – Attachment ID, or an absolute URL to a .gpx file (alternative to id).
height – Map height in pixels, from 200 to 1200. Default: the site setting.
height_tablet – Map height at 782px and below. Default: the site’s Tablet height, or height when the site sets none.
height_mobile – Map height at 480px and below. Default: the site’s Mobile height, or height_tablet when the site sets none.
stats – Show the stats bar (distance, elevation, waypoints). true or false. Default: the site setting.
elevation – Show the interactive elevation profile. true or false. Default: the site setting.
download – Show the GPX download button on the map. true or false. Default: the site setting (off).
maxzoom – How close the map opens when it frames a short route, from 1 to 22, though never closer than its tile provider has tiles. Visitors can zoom in as far as those tiles go. Default: the site setting.
provider – The map tiles: osm (OpenStreetMap), opentopomap, or a Thunderforest style once its API key is saved: thunderforest-outdoors, thunderforest-cycle, thunderforest-landscape or thunderforest-atlas. A Thunderforest style without a saved key shows the site’s provider. Default: the site setting.
units – metric (km / m) or imperial (mi / ft). Default: the site setting.
fields – Which stats to list, from distance, gain, loss, max, min and waypoints, e.g. distance,gain. Default: the site setting. Use stats="false" to remove the bar.
waypoints – Link the file’s waypoints to Waypoint posts, as number:post ID pairs that number the waypoints from 1 in the order of the file, e.g. 1:12, 3:40. Needs Waypoint posts turned on. Default: only the links the GPX file holds, when it is in the Media Library.
Provide either id or gpx. The block exposes the same options in its sidebar (Source, Display, Stats bar items and Map tiles panels, and Waypoints once Waypoint posts are on).
Filters (for developers):
gpxrm_tile_url – change the raster tile URL template a map loads. It runs for every map, whether its provider comes from the block, the shortcode or the site setting. The second argument is the provider that map uses, such as osm, opentopomap or thunderforest-outdoors: its own choice, else the site’s, else osm while a Thunderforest style has no key. A callback that ignores the second argument replaces the tiles of every map, whatever was chosen for it.
gpxrm_tile_max_zoom – change the last zoom level a tile server has tiles for (integer, 0 for not known), such as for a tile server of your own; the second argument is the tile URL template.
gpxrm_tile_attribution – change the attribution HTML.
gpxrm_height – change the site-wide map height in pixels (integer).
gpxrm_max_zoom – change how close maps open when they frame a short route, site-wide (integer).
gpxrm_heights – change the site-wide height for every viewport band (array of base, tablet, mobile; 0 means “follow the next larger band”).
gpxrm_units – change the site-wide unit system (metric or imperial).
gpxrm_show_stats – change whether the stats bar shows by default (boolean).
gpxrm_show_elevation – change whether the elevation profile shows by default (boolean).
gpxrm_show_download – change whether the download button shows by default (boolean).
gpxrm_stat_fields – change which stats the bar lists by default (array of distance, gain, loss, max, min, waypoints).
