7.5 图层与气象服务

适用版本：ElaneMap H5 API 3.5
前置阅读：建议先阅读《7.1-快速入门：从注册到接入》与《7.2-地图引擎基础：地图控制与业务绘制》，掌握 API 引入、密钥（ak）配置、地图实例化（new ShipxyAPI.Map(...)）之后再阅读本篇。
本篇涉及服务的 API 引用方式：

1. 概述

ElaneMap H5 在海图底图之上提供两类叠加能力：

叠加图层体系（本篇第 2~8 节）：

图层	服务入口	说明
全球港口	`ShipxyAPI.portDataSymbol`	全球港口瓦片图层，支持墨卡托/纠偏两种 URL
浮标/航标	`ShipxyAPI.NavigationService`	航标显示、添加、定位、选中
特殊区域	`ShipxyAPI.areaViewSymbol`	排放控制区、专属经济区、时区等六类区域面
长江航道	`ShipxyAPI.cjhdLayerServer`	长江航道专用瓦片图层
经纬度网格	`ShipxyAPI.latlngGraticuleServer`	经纬网线与度数标签
自定义瓦片	`ShipxyAPI.customeTileLayerService`	叠加任意第三方/自有瓦片源
月更新海图	`L.TileLayer.multi` + `options.addTileLayer`	月更新海图/海陆一张图（扩展图源方式接入）

气象服务体系（本篇第 9 节）：

ShipxyAPI.WeatherService 提供气温、气压、风（海风符号/风场）、海浪、海流/海水、降雨、海区预报、台风、潮汐等专业气象图层的显示与隐藏，以及单点经纬度气象数据查询（getLatLngWeather）。气压等值线（weatherChoroplethServer）见本篇第 5 节。

所有图层服务统一遵循同一使用模式：

先创建地图：var _map = new ShipxyAPI.Map("map", {ak: "您的密钥"});

调用 ShipxyAPI.XXXService(_map, options) 初始化服务；初始化后服务对象同时挂载在地图实例上（如 _map.weatherService、_map.areaViewSymbol），两种方式均可调用。

通过 show()/hide() 或 showArea()/hideArea() 控制图层显隐。

2. 港口展示服务 portDataSymbol

全球港口展示服务，以瓦片图层方式在海图上叠加全球港口图标。

2.1 创建

参数说明：

参数	类型	说明
map	L.gMap	地图对象
options	Object	设置信息，非必填。`{WEB_MERCATOR_URL: "WEB墨卡托URL", WEB_MERCATOR_GCJ02_URL: "WEB墨卡托纠偏URL"}`

返回值：L.PortDataSymbol 港口图层对象。初始化后也可通过 map.portDataSymbol 访问。

options 参数表：

参数	说明
WEB_MERCATOR_URL	港口瓦片 WEB 墨卡托 URL，默认 `//portsrv.shipxy.com/tiles/wm/{0}-{1}-{2}.png`
WEB_MERCATOR_GCJ02_URL	港口瓦片 WEB 墨卡托纠偏 URL（GCJ02 坐标系下使用），默认 `//portsrv.shipxy.com/tiles/wmgcj/{0}-{1}-{2}.png`

如果没有特殊需要，可以不设置 options，直接 ShipxyAPI.portDataSymbol(map)。

2.2 方法

方法	说明
show()	显示港口图层
hide()	隐藏港口图层

2.3 完整示例

3. 浮标/航标展示服务 NavigationService

浮标展示服务提供浮标（航标）显示、添加浮标、定位浮标等功能。其底层实现类为 NavigationMarkService（航标展示服务实现类），二者 options 完全一致。

3.1 创建

3.2 options 参数表

参数	默认值	说明
onClick	undefined	单击事件回调
onHover	undefined	悬浮事件回调
flyToZoom	10	定位默认 zoom
bigIconZoom	6	大图标显示级别
iconScale	0.6	图标显示比例
smallIconScale	1	小图标显示比例
isShow	true	是否显示航标
isShowTooltip	true	是否显示 tooltip
isSelectedShowReal	true	选中时是否显示真实航标

3.3 方法速查表（NavigationMarkService）

方法	说明
addMarker(data)	添加航标，按 MMSI 自动覆盖
addMarkers(arr)	添加多个航标，按 MMSI 自动覆盖
cancelSelected()	取消选中
clearMarker()	擦除所有航标（内存对象未删除）
getNavigationByMMSI(mmsi, isRequest)	获取航标信息；`mmsi` 为航标标识 MMSI，`isRequest` 表示是否请求服务器数据；返回航标数据（null 或 CanvasNavigation）
getNavigationType(typeCode)	根据航标类型代码获取航标类型，返回 string
locationNavigation(navigation)	定位航标对象
locationNavigationByMMSI(mmsi)	通过 MMSI 定位航标
recoveryMarker()	重绘所有航标（根据内存对象）
redraw()	航标图层重绘
removeAllMarker()	移除所有航标
removeMarkerByMMSI(mmsi, redraw)	移除指定 MMSI 航标；`redraw`（Boolean）表示是否刷新视图
setSelectedNavigation(mmsi)	设置选中指定 MMSI 的航标
show(isShow)	航标图层显示、关闭

3.4 完整示例

4. 特殊区域展示服务 areaViewSymbol

特殊区域展示服务用于在海图上叠加六类区域面数据：

区域	标识
全球海区	GSEA
排放控制区	TYP
排放控制区(中国)	CTYP
专属经济区	EEZ
全球时区	TIME
临海基线	BLINE

4.1 创建

返回值：L.AreaViewSymbol 区域展示/隐藏对象。初始化后可通过 map.areaViewSymbol 访问。

4.2 options 参数表

参数	说明
gsea_url	全球海区数据 URL，默认 `//api.shipxy.com/h5/demo/data/globalSeaAreaSymbol_area.json`
typ_url	排放控制区数据 URL，默认 `//api.shipxy.com/h5/demo/data/typhoon_area.json`
ctyp_url	排放控制区(中国)数据 URL，默认 `//api.shipxy.com/h5/demo/data/chinaDischargeAreaSymbol_area.json`
eez_url	专属经济区数据 URL，默认 `//api.shipxy.com/h5/demo/data/exclusiveEconomicZoneSymbol_area.json`
isShowName	是否显示名称，默认：true。注意：showName 属性目前仅"专属经济区"起作用

options 非必填，不传则使用默认数据地址。

4.3 方法

方法	说明
showArea(type)	显示指定区域，type 取值为 GSEA / TYP / CTYP / EEZ / TIME / BLINE
hideArea(type)	隐藏指定区域；不传参数 `hideArea()` 表示隐藏所有区域

4.4 完整示例

说明：演示页面 b1_8.htm（图层展示）中，领海基线按钮实际同时切换了 BLINE、BLINE12、BLINE24 三个标识（分别对应基线、12 海里、24 海里线），可按需参考该用法。

5. 长江航道图层服务 cjhdLayerServer 与气压等值线 weatherChoroplethServer

5.1 长江航道图层服务 cjhdLayerServer

在地图上叠加长江航道专用瓦片图层。创建方式：

options 参数表（均非必填）：

参数	说明
url	瓦片地址
error_url	瓦片异常地址
dataCJ9	9级瓦片网格范围
m_types	瓦片类型映射，如 `{"MT_SEA": "m", "MT_GOOGLE": "d", "MT_SATELLITE": "w"}`
minZoom	最小缩放级别
maxZoom	最大缩放级别

初始化后通过 map.cjhdLayerServer.show() / map.cjhdLayerServer.hide() 控制显隐。

提示：也可以在地图初始化时通过 new ShipxyAPI.Map("map", {cjhdTileLayer: {isShow: true}}) 直接显示长江航道图层。

5.2 气压等值线 weatherChoroplethServer

在地图上叠加气压等值线图层。创建方式：

参数	类型	说明
map	Map	地图对象
options	Object	配置信息，非必填

使用方式与长江航道图层一致（显隐控制模式相同）：

6. 经纬度网格服务 latlngGraticuleServer

在地图上显示经纬度网格线及度数标签。

6.1 创建

6.2 options 参数表

参数	说明
showLabel	是否显示经纬度标签，如 `true`
weight	网格线宽，如 `0.8`
color1	非卫星地图线颜色，如 `"#666"`
color2	卫星地图线颜色，如 `"#bbb"`
fontColor1	非卫星地图字颜色，如 `"#333"`
fontColor2	卫星地图字颜色，如 `"#fff"`
dashArray	线型虚线设置，如 `[0, 0]` 表示实线
latFormatTickLabel	纬度标签格式化方法，默认 `CanvasShipUtils.latFormatter`
lngFormatTickLabel	经度标签格式化方法，默认 `CanvasShipUtils.lngFormatter`
zoomInterval	各级别网格间隔数组，`{start, end, interval}`，interval 单位为度

zoomInterval 默认配置（级别 2~18 对应间隔 60 度到约 0.001 度逐级加密）：

6.3 方法

方法	说明
show()	显示经纬度网格
hide()	隐藏经纬度网格

6.4 完整示例

7. 自定义瓦片图层服务 customeTileLayerService

用于在海图上叠加任意自定义瓦片源（如自有光栅图、第三方瓦片服务）。

7.1 创建与参数

addLayer 的 options 参数：

参数	说明
url	瓦片URL，必填（使用 tileFunction 时可在该函数内拼 URL）
opacity	瓦片透明度，默认：0.7
tileFunction	自定义瓦片URL编辑方法，入参 view 包含 `view.tile.column`（x）、`view.tile.row`（y）、`view.zoom`（z），返回完整瓦片URL
cid	图层标识（演示示例中使用，配合 showLayerById/removeLayerById 控制显隐）
attribution / crs / maxZoom / label / errorTileUrl 等	透传 Leaflet tileLayer 常规参数

服务方法（演示示例中实际使用）：

方法	说明
addLayer(options)	添加自定义瓦片图层
showLayerById(cid)	按 cid 显示图层
removeLayerById(cid)	按 cid 移除图层

7.2 完整示例（整理自 a1_8.htm）

8. 月更新海图 / 海陆一张图

月更新海图不是独立服务接口，而是通过"扩展图源"方式接入：用 L.TileLayer.multi 创建月更新海图瓦片图层，放入地图 options 的 addTileLayer 数组，再通过 _map.basemapsControl.changeMap("MT_SEASEASON") 切换。

注意事项：

引入月更新海图，需要您的 key 拥有月更新海图的权限。

瓦片地址为 /apicall/GetMTile?k=您的密钥&x={x}&y={y}&z={z}（月更新瓦片）。

海陆一张图（MT_SEALAND 图源）下，可叠加 OS-MAP 网片图层（/apicall/GetWTile），瓦片范围为中国区域 L.latLngBounds(L.latLng(2, 70), L.latLng(54, 136))。

演示页面额外引用了 ../source/elane.osLayer.js（扩展脚本），并通过扩展 L.Class 实现 L.OSMAPTitleLayer：监听 baselayerchange 事件，仅在 MT_SEALAND 图源下添加网片瓦片图层。

完整示例（整理自 a1_9.htm）：

9. 气象服务 WeatherService

气象服务提供气温、气压、风、海浪、海流、降雨、海区预报、台风、潮汐等专业气象图层，以及单点经纬度气象数据查询。

9.1 创建与全局配置

配置项	说明
ShipxyOptions.weather.icon_base_url	气象图标存放 URL，默认 `//api.shipxy.com/h5/elanemap/images/`。图标资源部署在自有服务器时可覆盖此项

9.2 方法一览

以下方法均通过 map.weatherService.XXX() 调用。带时间参数的方法，时间格式统一为字符串 "yyyy-MM-dd HH:mm:ss"，例如 "2018-05-15 20:00:00"；不传时使用默认（当前）时间。每个显示方法都有对应的隐藏方法。

功能	显示方法	隐藏方法	时间参数
气温面	showTempTile(time)	hideTempTile()	可选
气压面	showPressureTile(time)	hidePressureTile()	可选
海风符号	showSeaBreezes(time)	hideSeaBreezes()	可选
风场	showWindFiel(time)	hideWindFiel()	可选
海浪符号	showSeaWaves(time)	hideSeaWaves()	可选
海流/海水符号	showSeaWater(time)	hideSeaWater()	可选（主文档标注"显示海流符号未实现"，实际效果以演示页面为准）
流场(洋流)	showOceanCurrentFiel(time)	hideOceanCurrentFiel()	可选（演示页面 b1_9 使用）
降水符号	showRainFall(time)	hideRainFall()	可选
海区预报	showSeaAreaForecasts()	hideSeaAreaForecasts()	无
台风列表控件	showTyphoonInfoList(closeCallback, ...)	hideTyphoonInfoList()	无
潮汐预报	showTides()	hideTides()	无
隐藏所有	hideAll()	—	—

方法签名与说明：

showTyphoonInfoList 在演示页面 b1_9 中的实际调用带扩展参数：

getLatLngWeather(type, latlng, time)：获取指定经纬度对应的气象数据；latlng 为经纬度对象（如地图点击事件返回的 e.latlng），time 格式同上。

9.3 单点气象数据接口（演示页面用法）

演示页面 b1_9 中，点击地图任意位置后，通过 AJAX 调用单点气象接口并在该点弹出气象信息（压、风、流、浪、温）：

返回字段说明（无效值均为 "-32767" 或空）：

字段	含义	单位
pressure	气压	hPa
winddir / windspeed	风向 / 风速	度 / 米每秒
oceandir / oceanspeed	流向 / 流速	度 / 米每秒
waveheight	浪高	米
temperature	温度	℃

9.4 完整可运行示例（整理自 b1_9.htm）

演示页面 b1_9 的按钮图标使用 base64 内嵌图片（.qiwen/.qiya 等 class），上方示例改为文字按钮以便直接运行，交互逻辑与源示例一致。

10. 效果示意、注意事项与 FAQ

10.1 效果示意

光栅图层：海图上展示全球船舶实时点位分布。
光栅示意.png

特殊区域：对应区域以半透明彩色面叠加在海图上，边界线清晰；专属经济区可显示区域名称文字。

长江航道：长江干线水域叠加航道专用瓦片，9 级以上开始显示，可清晰看到航道边界与水深信息。

经纬度网格：海图上叠加灰色经纬网线，边缘标注度数；放大时网格间隔自动加密；切换到卫星图时线色/字色自动切换为浅色。

气温/气压：整幅海图覆盖半透明色斑图（气温暖色、气压冷色渐变），色斑随级别平滑过渡。

海风/海浪/海流：海面出现规则排列的风矢杆、浪高箭头、流向箭头符号，指示方向与大小。

风场/洋流：全屏粒子流线动画，流向清晰可见，具有动态流动效果。

海区预报：海图上叠加各海区名称标注，点击可查看该区域文字预报。

台风：地图边缘出现台风列表面板，选择台风后海图上绘制台风路径、风圈与警戒线。

潮汐：近岸港口位置出现潮汐站点图标，点击查看潮汐曲线预报。

10.2 注意事项

所有服务均需在 new ShipxyAPI.Map(...) 创建地图之后初始化；密钥占位符 您的密钥 需替换为实际申请的 ak。

气象图层时间参数格式统一为 "yyyy-MM-dd HH:mm:ss"，如 "2018-05-15 20:00:00"；预报数据按时次发布，演示中使用当天 20:00:00 时次。

气温与气压图层面互斥，演示示例中开启一个时会关闭另一个的按钮状态。

海流/洋流数据量大，演示示例中当地图级别大于 7 时先 setZoom(5) 再显示，避免低级别下加载过慢。

weatherChoroplethServer（气压等值线）主文档示例中的初始化和显隐写法沿用了 cjhdLayerServer 的占位写法，实际应以 map.weatherChoroplethServer 挂载名为准，集成时请以实际联调结果为准。

b1_8.htm（图层展示）源页面基于 3.0 版本插件（额外引入 L.AreaLayerService.js、L.FishAreaLayerService.js，渔区边界/渔业协定水域为插件能力），本篇示例已按 3.5 版本 API 整理。

月更新海图需要 key 具备相应权限，否则瓦片请求失败显示异常图（errorTileUrl 占位图）。

图层服务初始化一次即可，重复调用 ShipxyAPI.XXX(map) 不会叠加多个图层；显隐通过 show/hide 系列方法控制。

10.3 FAQ

Q：初始化了港口/区域服务但地图上没有显示？
A：初始化只是注册服务，大多数图层需显式调用 show() 或 showArea("GSEA") 才会显示；同时检查密钥权限与浏览器控制台是否有瓦片 403/404 错误。

Q：气象图层显示后如何一次全部关闭？
A：调用 map.weatherService.hideAll() 隐藏所有气象显示。

Q：自定义瓦片 URL 是动态拼接的怎么办？
A：使用 tileFunction(view) 回调，在函数内用 view.tile.column、view.tile.row、view.zoom 替换 URL 占位符并返回最终地址。

Q：经纬度网格在卫星图上几乎看不见？
A：通过 options 的 color2/fontColor2（卫星地图专用颜色）设置浅色系即可。

Q：单点气象返回字段出现 -32767？
A：-32767 为无效值占位，展示前需判空（参考 9.3 节演示代码的处理方式）。

Q：航标图标太大/太小？
A：调整 iconScale（图标显示比例，默认 0.6）与 smallIconScale（小图标显示比例，默认 1），以及 bigIconZoom（大图标显示级别，默认 6）。

7.5 图层与气象服务

1. 概述#

2. 港口展示服务 portDataSymbol#

2.1 创建#

2.2 方法#

2.3 完整示例#

3. 浮标/航标展示服务 NavigationService#

3.1 创建#

3.2 options 参数表#

3.3 方法速查表（NavigationMarkService）#

3.4 完整示例#

4. 特殊区域展示服务 areaViewSymbol#

4.1 创建#

4.2 options 参数表#

4.3 方法#

4.4 完整示例#

5. 长江航道图层服务 cjhdLayerServer 与气压等值线 weatherChoroplethServer#

5.1 长江航道图层服务 cjhdLayerServer#

5.2 气压等值线 weatherChoroplethServer#

6. 经纬度网格服务 latlngGraticuleServer#

6.1 创建#

6.2 options 参数表#

6.3 方法#

6.4 完整示例#

7. 自定义瓦片图层服务 customeTileLayerService#

7.1 创建与参数#

7.2 完整示例（整理自 a1_8.htm）#

8. 月更新海图 / 海陆一张图#

9. 气象服务 WeatherService#

9.1 创建与全局配置#

9.2 方法一览#

9.3 单点气象数据接口（演示页面用法）#

9.4 完整可运行示例（整理自 b1_9.htm）#

10. 效果示意、注意事项与 FAQ#

10.1 效果示意#

10.2 注意事项#

10.3 FAQ#