地图脚本设计与兼容迁移
MapLibre 风格地图接口、三端共用脚本与必要差异的设计约定。
本页说明 2026-10-10 冻结的设计约定。新模块与接口仍在实施中，不能把本页当作已发布 API 参考。 当前可执行用法见 脚本 API，平台范围见 开发者 API。
同一份地图脚本
新脚本计划从内建模块 sqsmap 导入 map、gis 和 expr。网页、桌面和移动端将提供同一套地图调用；地图初始化、窗口和页面由使用方宿主接入。
地图方法优先采用 MapLibre 风格，例如 addSource/addLayer、setPaintProperty/setLayoutProperty、flyTo/fitBounds、on/off/once。原有 gis 模块、引用和任务返回方式保持兼容；迁移通过适配完成。
返回值与事件
| 调用 | 设计约定 |
|---|---|
| 地图修改方法 | 参考返回地图的方法保持链式调用；返回表示已提交，应用结果单独等待 |
| ready / flush / sync 扩展 | 分别等待初始化、指定命令水位应用、读取最新已应用状态 |
| on | 返回可取消的订阅对象 |
| off | 返回地图 |
| once 带回调 | 返回地图 |
| once 不带回调 | 返回等待事件的 Promise |
| 渲染/源要素和高程查询 | 三端统一 await，明确标为与参考同步查询的差异 |
| GeoJSON 数据更新与聚合查询 | 按冻结 MapLibre 6.13.0 的 Promise 约定 |
事件不能只在脚本初始化时有效。显式交互会话将保持监听，停止或地图销毁后清理；一次性脚本仍能正常结束。命令完成、资源就绪、完成渲染和动画终点分别定义。
自定义工具与真实支持
图层面板、比例尺、缩放、回正和 2D/3D 工具由使用方绘制。地图提供状态、操作和事件；回正与俯视恢复、视图模式与球面投影分别定义。
每项能力将提供支持程度、参数限制、后端条件和验证状态。网页宿主尚未接入或移动链路缺失属于待实现，不能用平台标签代替验收。DOM、全屏、系统定位和原生纹理的差异由宿主说明。
参考版本固定为 MapLibre GL JS 6.13.0。对照目录、类型和可运行示例会随接口实施同步更新，规划内容与可用接口明确区分。
06.3 实施修订：相机和双向坐标查询统一返回 Promise，使用 await 获取实际已应用状态；链式设置和显式 flush 保持共同写法。完整设计中的其他方法仍以实际能力为准。