ElaneMap 船讯网 JSAPI

概述

定位

本 Skill 是任务调度器，不是完整 API 手册。

收到需求后，先判断业务场景，选择一个最接近的 Recipe，再按 Recipe 链接读取必要的 Reference。不要一次性加载全部文档，也不要仅停留在模块 README。

只使用文档明确列出的公开入口。详细参数、方法和数据结构以对应 Reference 为准，完整业务调用顺序以 Recipe 为准。

标准工作流

1. 确认任务是新建、修改、排错、代码审查还是 API 查询。
2. 检查目标项目的前端框架、JSAPI 加载方式、运行页面和部署来源。
3. 阅读[公开 API 边界](references/public-api-boundaries.md)，排除内部实现。
4. 从“场景路由”选择最接近的 Recipe，提取业务流程。
5. 从“知识路由”读取 Recipe 指向的具体 Reference，核对签名、配置、单位和生命周期。
6. 在已有项目中优先沿用其加载方式、代码风格和服务实例，不重复初始化地图或服务。
7. 只生成业务所需的 JavaScript；除非用户要求完整页面，不复制 Demo 的 HTML、CSS、按钮、表单或 jQuery 事件。
8. 完成后检查鉴权、坐标、时间、数据单位、事件解绑和资源清理。
9. 对可运行页面使用真实部署地址进行浏览器验证。

强制规则

• 通过地图配置的 ak 传入授权 Key。
• Key 必须绑定当前页面实际部署的域名或 IP。
• 使用维护中的 HTTPS JSAPI 包和 HTTPS 服务地址。
• 接口返回 status: 14 时，优先排查来源域名或 IP 与 Key 的绑定关系。
• 示例、提交内容、日志和截图中不得保留真实 Key，应替换为占位符。
• 不得实例化名称含 Impl 的类，不得调用 Reference 未列入公开方法的内部函数。
• 保留官方字段拼写，包括历史兼容拼写；不要擅自“纠正”字段名。
• 坐标顺序必须按数据表示区分：ShipxyAPI.latLng(lat, lng) 及继承自 Leaflet 的坐标数组使用 [纬度, 经度]，GeoJSON coordinates 使用 [经度, 纬度]；船舶接口字段、时间戳和速度等单位以目标 Reference 为准。
• 不确定某成员是否公开时，视为不可用，并回到公开入口重新设计。

场景路由：优先读取 Recipe

每个任务通常先读一个 Recipe；组合需求再增加必要的 Recipe。

地图基本功能

• 创建首张地图、设置中心与缩放：[创建基础地图](recipes/create-basic-map.md)
• 配置缩放、比例尺、鼠标位置等控件：[配置地图控件](recipes/configure-map-controls.md)
• 测距、测面积及清除测量结果：[配置测量功能](recipes/configure-measurement.md)
• 海图、街道图、卫星图切换：[切换底图](recipes/switch-basemap.md)
• 绘制、编辑和结束航线：[绘制和编辑航线](recipes/draw-route.md)
• 添加、移动或删除标记：[添加和编辑标记](recipes/add-edit-marker.md)
• 添加、编辑或删除折线：[添加和编辑折线](recipes/add-edit-polyline.md)
• 添加、编辑或删除多边形：[添加和编辑多边形](recipes/add-edit-polygon.md)
• 添加、显示或移除自定义瓦片：[管理自定义瓦片图层](recipes/manage-custom-tile-layer.md)
• 加载授权的月更新海图：[添加月更新海图](recipes/add-monthly-chart.md)

地图业务功能

• 展示指定区域内的船舶：[展示区域船舶](recipes/display-area-ships.md)
• 展示船队或多艘指定船舶：[展示船队船舶](recipes/display-fleet-ships.md)
• 按船名、MMSI 等条件搜索：[搜索船舶](recipes/search-ship.md)
• 按 MMSI 定位并选中船舶：[定位单艘船舶](recipes/locate-ship.md)
• 按船舶和时间范围查询历史轨迹：[查询船舶轨迹](recipes/query-track.md)
• 播放、暂停、调速和跳转历史轨迹：[轨迹回放](recipes/playback-track.md)
• 回放指定区域内多艘船舶：[区域船舶回放](recipes/replay-area-ships.md)
• 显示或隐藏港口、航道等海事图层：[切换海事图层](recipes/toggle-maritime-layers.md)
• 显示风、浪、气压、台风等气象数据：[显示海洋气象](recipes/show-marine-weather.md)

知识路由：按主题读取 Reference

接入、鉴权与生命周期

• 脚本地址、加载顺序、Key 和加载失败：[安装与引入](references/getting-started/installation.md)
• 地图容器、构造参数和首屏视图：[创建地图](references/getting-started/create-map.md)
• 通用初始化配置：[初始化配置](references/getting-started/configuration.md)
• 服务创建、事件清理和地图销毁：[地图生命周期](references/getting-started/lifecycle.md)
• 来源绑定、HTTPS、安全检查和上线清单：[安全与检查清单](references/security-and-checklist.md)
• 受控授权页面的准备和端到端验证：[授权测试页契约](references/testing/authorized-page.md)

地图核心

• 地图实例、视图方法和公开服务挂载点：[地图对象](references/core/map.md)
• 跨模块通用配置项：[通用配置](references/core/common-options.md)
• 经纬度顺序、坐标表示与转换边界：[坐标规则](references/core/coordinates.md)
• 地图及图层事件的注册和解绑：[事件模型](references/core/events.md)

控件

• 海图、街道图和卫星图切换：[底图控件](references/controls/basemaps.md)
• 距离和面积测量：[测量控件](references/controls/measurement.md)
• 消息提示框：[消息框](references/controls/message-box.md)
• 鹰眼小地图：[缩略图控件](references/controls/minimap.md)
• 鼠标位置及经纬度格式化：[鼠标位置](references/controls/mouse-position.md)
• 比例尺：[比例尺控件](references/controls/scale.md)
• 船舶搜索框和搜索结果：[船舶搜索](references/controls/search-ship.md)
• 放大、缩小和缩放级别：[缩放控件](references/controls/zoom.md)

图层与覆盖物

• 图层添加、显隐、移除和层级关系：[图层管理](references/layers/layer-management.md)
• 区域数据图层：[区域图层](references/layers/area-layers.md)
• 业务自定义瓦片服务：[自定义瓦片图层](references/layers/custom-tile-layer.md)
• 网格及大数据量图层：[网格图层](references/layers/grid-layers.md)
• 标准瓦片图层：[瓦片图层](references/layers/tile-layers.md)
• 标记、折线、多边形及矢量样式：[矢量图层](references/layers/vector-layers.md)

船舶

• 区域船、船队、查询、定位、选择和清理：[船舶服务](references/ship/ship-service.md)
• 船舶字段、接口数据转换和单位：[船舶数据结构](references/ship/ship-data.md)
• 船舶点击、选中等事件：[船舶事件](references/ship/ship-events.md)
• 船型、颜色、标签等显示配置：[船舶样式](references/ship/ship-style.md)
• 船舶导航标记和导航状态：[船舶导航](references/ship/navigation.md)

轨迹与航线

• 历史轨迹查询、添加、显隐、更新和删除：[轨迹管理](references/track/track-service.md)
• 轨迹点和轨迹对象字段：[轨迹数据](references/track/track-data.md)
• 播放、暂停、速度、进度和播放对象显示：[轨迹回放](references/track/track-playback.md)
• 航线节点、绘制、编辑和销毁：[轨迹与航线绘制](references/track/track-drawing.md)
• 轨迹点点击和播放事件：[轨迹事件](references/track/track-events.md)
• 轨迹线、节点、标签和抽稀配置：[轨迹样式](references/track/track-style.md)
• 停留、慢速、断点等轨迹分析：[轨迹分析](references/track/track-analysis.md)

海事业务

• 港口图层：[港口](references/maritime/ports.md)
• 航道和水道图层：[航道](references/maritime/waterways.md)
• 海区及区域显隐：[海区](references/maritime/sea-areas.md)
• 经纬网：[经纬网](references/maritime/graticule.md)
• 当前航次和历史航次：[航次](references/maritime/voyage.md)

海洋气象

• 气温、气压、风、浪、降水、潮汐和统一清理：[气象服务](references/weather/weather-service.md)
• 气象矢量图层与样式：[气象图层](references/weather/weather-layers.md)
• 台风列表、路径和单个台风显隐：[台风](references/weather/typhoon.md)
• 风场显示与隐藏：[风场](references/weather/wind-field.md)
• 雷达数据绘制与清理：[雷达](references/weather/radar.md)

插件与工具

• 可公开使用的插件范围和选型：[插件概览](references/plugins/plugin-overview.md)
• Canvas 船舶网格能力：[Canvas 船舶网格](references/plugins/grid-canvas-ship.md)
• 矢量网格显示与交互：[矢量网格](references/plugins/vector-grid.md)
• 热点雷达数据绘制：[热点雷达](references/plugins/hot-radar.md)
• 接口数据格式转换：[数据转换](references/utilities/data-conversion.md)
• 距离、边界等几何计算：[几何工具](references/utilities/geometry.md)
• 区域数据处理：[区域工具](references/utilities/region.md)

实现策略

新建功能

从最接近的 Recipe 保留最小业务代码，再根据目标框架封装。先完成地图和服务初始化，再添加业务能力，最后补清理逻辑。

修改现有功能

先定位已有地图、服务和事件实例。避免创建第二个同类服务；只修改与需求相关的配置、数据处理和生命周期代码。

故障排查

按以下顺序检查：

1. JSAPI 文件是否成功加载，ShipxyAPI 是否存在。
2. 地图容器是否存在且宽高不为零。
3. Key、来源域名或 IP、HTTPS 是否匹配。
4. 地图和业务服务是否按正确顺序初始化。
5. 经度纬度顺序、Unix 秒/毫秒、航向和速度单位是否正确。
6. 控制台和网络请求是否出现 status: 14、混合内容或接口错误。
7. 页面卸载前是否解除事件并销毁服务和地图。

代码审查

重点指出以下问题：内部 API、真实 Key 泄露、重复初始化、错误单位、错误字段拼写、未解绑事件、未清理图层，以及把 Demo 页面交互逻辑混入业务代码。

输出要求

• 默认使用中文解释，代码中的公开 API 名称和字段名保持原样。
• 优先给出可嵌入现有项目的关键 JavaScript，不生成无关页面结构。
• 明确列出调用前提、数据单位、返回结果和必要的清理操作。
• 若文档未证明某能力公开可用，明确说明边界，不根据内部源码猜测调用方式。
• 引用具体 Recipe 和 Reference，使后续维护可以追溯。

完成检查

• 使用的类、方法和配置均在公开 Reference 中。
• 代码只包含实际业务逻辑，没有 Demo 展示层事件。
• Key 已脱敏，来源绑定和 HTTPS 条件已说明。
• 地图容器、初始化顺序和异步就绪时机正确。
• 坐标、时间、速度、航向和尺寸单位正确。
• 事件、轨迹、图层、服务和地图有对应清理路径。
• 相关 Recipe 与 Reference 链接有效。
• 可运行任务已在目标部署地址检查控制台和网络请求。

维护校验

• 独立校验运行 node scripts/validate-all.mjs，不依赖仓库外文件。
• 重新提炼 Reference 运行 node scripts/generate-all.mjs；该命令仅用于完整源码工作区，并要求相邻目录 ../jsapi 存在。
• 浏览器端到端验证按[授权测试页契约](references/testing/authorized-page.md)准备脱敏测试页，再运行 scripts/smoke-test-browser.mjs。