地图、图层与相机（生成文件）

由 cargo run -p sqs-script --bin script_contract -- docs/lang/generated docs/API/script/reference 生成，契约版本 0.5-session。修改 registry 后重新生成，不要手改本文件。使用方法见脚本 API 指南。

map.sources

`map.sources.cluster`

从点源后台建立稳定的分层聚合，统计在筛选后执行。

权限：map.write
平台：桌面、移动、网页
签名：map.sources.cluster(arg0: string, arg1: SourceRef, arg2: ClusterOptions, arg3: SceneOwnerOptions): Operation<SourceRef>

`map.sources.createTransient`

创建场景持有的只读实时点源，原始文件不变。

权限：map.write
平台：桌面、移动、网页
签名：map.sources.createTransient(arg0: TransientSourceOptions, arg1: SceneOwnerOptions): Operation<SourceRef>

map.camera

`map.camera.easeTo`

准备二维相机运动，由场景开始后接管；用户定位可打断。

权限：map.write
平台：桌面、移动、网页
签名：map.camera.easeTo(arg0: CameraMotionOptions, arg1: SceneOwnerOptions): Operation<PlaybackRef>

`map.camera.flyTo`

准备二维相机运动，由场景开始后接管；用户定位可打断。

权限：map.write
平台：桌面、移动、网页
签名：map.camera.flyTo(arg0: CameraMotionOptions, arg1: SceneOwnerOptions): Operation<PlaybackRef>

map.contours

`map.contours.enable`

管理 Terrain-RGB 二维等高线及加载状态。

权限：map.write
平台：桌面、移动、网页
签名：map.contours.enable(arg0: ContourOptions): Operation<ContourStatus>

`map.contours.disable`

管理 Terrain-RGB 二维等高线及加载状态。

权限：map.write
平台：桌面、移动、网页
签名：map.contours.disable(): Operation<ContourStatus>

`map.contours.status`

管理 Terrain-RGB 二维等高线及加载状态。

权限：map.write
平台：桌面、移动、网页
签名：map.contours.status(): Operation<ContourStatus>

`map.contours.sampleElevation`

从当前 Terrain-RGB 图源查询 WGS84 点高程，透明像元返回缺测。

权限：project.read
平台：桌面、移动、网页
签名：map.contours.sampleElevation(arg0: [number,number]): Operation<OnlineElevationSample>

`map.contours.snapshot`

按指定范围读取地形等高线矢量快照，返回带米制 elevation_m 字段的冻结数据引用；不读取屏幕缓存，不改变显示。

权限：project.read
平台：桌面、移动、网页
签名：map.contours.snapshot(arg0?: ContourSnapshotOptions): Operation<ContourSnapshot>

map.basemap

`map.basemap.load`

加载样式底图，返回可等待和取消的加载任务。

权限：map.write
平台：桌面、移动、网页
签名：map.basemap.load(arg0: BasemapLoadOptions): Operation<BasemapLoadRef>

map.contours

`map.contours.profileLines`

按范围从地形图源读取平行剖面线，每个顶点保留米制高程；返回冻结三维线数据引用，不改变显示。

权限：project.read
平台：桌面、移动、网页
签名：map.contours.profileLines(arg0?: TerrainProfileOptions): Operation<TerrainProfileSnapshot>

map.basemap

`map.basemap.ready`

等待底图初始视野提交并读取状态。

权限：project.read
平台：桌面、移动、网页
签名：map.basemap.ready(arg0: BasemapLoadRef): Operation<BasemapStatus>

`map.basemap.cancel`

取消尚未提交的底图加载。

权限：map.write
平台：桌面、移动、网页
签名：map.basemap.cancel(arg0: BasemapLoadRef): Operation<void>

`map.basemap.status`

读取当前底图加载状态。

权限：project.read
平台：桌面、移动、网页
签名：map.basemap.status(): Operation<BasemapStatus>

map

`map.open`

读取矢量文件并作为面、线或圆点显示；同时需要 project.read 和 map.write。

权限：map.write
平台：桌面、移动
签名：map.open(arg0: string, arg1?: MapOpenOptions): Operation<MapLayerRef>

`map.getStyle`

读取当前共同内联样式快照，包含图源数据与图层编辑；不改变地图。

权限：project.read
平台：桌面、网页
签名：map.getStyle(): Operation<import("sqsmap").StyleSpecification>

`map.setStyle`

原子提交HTTP或自定义协议样式地址及内联样式；省略diff或true尝试保留兼容源与图层，false完整替换，null清空；flush确认写入而非资源就绪。

权限：map.write
平台：桌面、网页
签名：map.setStyle(arg0: string | null | import("sqsmap").StyleSpecification, arg1?: import("sqsmap").StyleOptions): Operation<void>

`map.getAttributions`

读取当前逻辑图源署名的完整纯文本快照，包含来源与图层身份；不改变地图。

权限：project.read
平台：桌面、网页
签名：map.getAttributions(): Operation<import("sqsmap").AttributionSnapshot>

map.lifecycle

`map.lifecycle.read`

读取初始化、首次完整绘制、实际帧和当前工作；只读查询不采样动画或推进渲染。

权限：project.read
平台：桌面、网页
签名：map.lifecycle.read(arg0: string, arg1: unknown[]): Operation<unknown>

map

`map.getCapabilities`

读取已实现的共同地图能力；缺失或false表示不可使用。

权限：project.read
平台：桌面、网页
签名：map.getCapabilities(): Operation<Readonly<Record<string, unknown>>>

map.protocol

`map.protocol.write`

登记或移除当前桌面或网页脚本拥有的协议处理器；回调和二进制走有界私有通道，停止释放自身登记。

权限：map.write
平台：桌面、网页
签名：map.protocol.write(arg0: string, arg1: [string, number]): Operation<unknown>

map.resourcePolicy

`map.resourcePolicy.read`

共享资源配置快照与只读HTTP或自定义协议请求计划；资源交付由宿主负责。

权限：project.read
平台：桌面、网页
签名：map.resourcePolicy.read(arg0: string, arg1: unknown[]): Operation<unknown>

`map.resourcePolicy.write`

共享资源配置快照与只读HTTP或自定义协议请求计划；资源交付由宿主负责。

权限：map.write
平台：桌面、网页
签名：map.resourcePolicy.write(arg0: string, arg1: unknown[]): Operation<unknown>

map.scene

`map.scene.read`

共同场景生命周期、时钟、GeoJSON归属及地图持有的轨迹播放、二维线动画与颜色透明度宽度曲线。

权限：project.read
平台：桌面、网页
签名：map.scene.read(arg0: string, arg1: unknown[]): Operation<unknown>

`map.scene.write`

共同场景生命周期、时钟、GeoJSON归属及地图持有的轨迹播放、二维线动画与颜色透明度宽度曲线。

权限：map.write
平台：桌面、网页
签名：map.scene.write(arg0: string, arg1: unknown[]): Operation<unknown>

map.source

`map.source.read`

读取共同 GeoJSON、瓦片元数据或配准媒体图源身份、加载状态、媒体状态、实时协议或独立快照，查询使用 await；sqs.getMaterialFadeDuration无参数，返回整数缩放材质渐变毫秒数，默认300；sqs.getLabelFadeDuration无参数，返回独立标签放置渐变毫秒数，默认300。

权限：project.read
平台：桌面、网页
签名：map.source.read(arg0: string, arg1: unknown[]): Operation<unknown>

注册、移除或原子更新共同 GeoJSON 与配准媒体；GeoJSON 支持内存与 HTTP或自定义协议URL，媒体接受宿主解码帧、图像 HTTP或自定义协议URL/updateImage、MP4/H.264 视频HTTP或自定义协议urls、命名 Canvas RGBA 帧和播放控制；矢量与影像瓦片支持登记、HTTP或自定义协议TileJSON及setTiles/setUrl，影像瓦片支持共同raster图层，矢量MVT支持共同circle/line/fill、source-layer查询与独立要素状态；不自动创建显示图层；sqs.setMaterialFadeDuration接受一个有限非负且最多3600000的毫秒数，不改变手动图案或虚线时序，不重置源身份、缓存和时钟；sqs.setLabelFadeDuration接受一个有限非负且最多3600000的毫秒数，独立控制标签放置渐变，0即时，不重置源身份、缓存和时钟。

权限：map.write
平台：桌面、网页
签名：map.source.write(arg0: string, arg1: unknown[]): Operation<unknown>

map.glyph

`map.glyph.read`

读取已解析样式的字形服务地址；查询使用await。

权限：project.read
平台：桌面、网页
签名：map.glyph.read(arg0: string, arg1: unknown[]): Operation<unknown>

`map.glyph.write`

切换或清除HTTP或自定义协议字形服务，保留已加载图源与图片并取消旧资源请求。

权限：map.write
平台：桌面、网页
签名：map.glyph.write(arg0: string, arg1: unknown[]): Operation<unknown>

map.image

`map.image.load`

加载HTTP或自定义协议PNG/JPEG/WebP图片并解码为独立RGBA8像素；不自动注册。

权限：project.read
平台：桌面、网页
签名：map.image.load(arg0: string): Operation<unknown>

`map.image.read`

读取样式和运行时图片；返回独立 RGBA 像素与可选伸缩、内容区域和文字适配元数据副本。

权限：project.read
平台：桌面、网页
签名：map.image.read(arg0: string, arg1: unknown[]): Operation<unknown>

`map.image.write`

添加、更新或移除共同静态与动态图片；有界回调、重绘和同尺寸更新复用图片候选及元数据。

权限：map.write
平台：桌面、网页
签名：map.image.write(arg0: string, arg1: unknown[]): Operation<unknown>

map.layer

`map.layer.read`

读取共同 GeoJSON 或媒体 raster 图层、属性、筛选和 UI 描述，查询使用 await。

权限：project.read
平台：桌面、网页
签名：map.layer.read(arg0: string, arg1: unknown[]): Operation<unknown>

`map.layer.write`

共同circle/line/fill/raster、默认/多算法及map/viewport光照hillshade与color-relief高程图层、平面/透视fill-extrusion建筑、平面heatmap、支持SDF染色、缺图事件、默认碰撞与可调文字排版的点图片/内置字体文字symbol和无源background图层增删、排序、属性与缩放范围；要素图层支持筛选，媒体/背景没有要素；保留相机和真实图源身份。

权限：map.write
平台：桌面、网页
签名：map.layer.write(arg0: string, arg1: unknown[]): Operation<unknown>

map.camera

`map.camera.read`

按共同地图写法读取权威平面或球面相机，查询使用 await。

权限：project.read
平台：桌面、网页
签名：map.camera.read(arg0: string, arg1: unknown[]): Operation<unknown>

`map.camera.write`

按共同地图写法提交完整校验的平面或球面相机设置，使用 flush 确认；球面支持动画、范围拟合、roll 和持久留白；留白保持地理姿态并调整投影主点。

权限：map.write
平台：桌面、网页
签名：map.camera.write(arg0: string, arg1: unknown[]): Operation<unknown>

map.light

`map.light.read`

按共同地图写法读取光照常量与历史配置，查询使用 await。

权限：project.read
平台：桌面、网页
签名：map.light.read(arg0: string, arg1: unknown[]): Operation<unknown>

`map.light.write`

原子设置共同光照颜色、方向和强度，使用 flush 确认。

权限：map.write
平台：桌面、网页
签名：map.light.write(arg0: string, arg1: unknown[]): Operation<unknown>

map.gesture

`map.gesture.read`

读取共同导航开关与实际活动状态，查询使用 await。

权限：project.read
平台：桌面、网页
签名：map.gesture.read(arg0: string, arg1: unknown[]): Operation<unknown>

`map.gesture.write`

设置共同默认导航开关，等待实际应用确认。

权限：map.write
平台：桌面、网页
签名：map.gesture.write(arg0: string, arg1: unknown[]): Operation<unknown>

map

`map.flush`

确认调用前已提交的地图操作，可选等待真实渲染；不代表图源就绪。

权限：project.read
平台：桌面、移动、网页
签名：map.flush(arg0?: import("sqsmap").FlushOptions): Operation<import("sqsmap").MapCommitResult>

`map.state`

读取当前地图的加载、图层和任务摘要。

权限：project.read
平台：桌面、移动、网页
签名：map.state(): Operation<MapStateSnapshot>

`map.setLocale`

设置地图控件与右键菜单语言；auto 跟随网页语言偏好，返回实际使用的语言。

权限：map.write
平台：网页
签名：map.setLocale(arg0: 'auto' | 'zh' | 'en'): Operation<'zh' | 'en'>

`map.getLocale`

读取地图控件与右键菜单实际使用的语言。

权限：project.read
平台：网页
签名：map.getLocale(): Operation<'zh' | 'en'>

`map.clear`

预演清空当前地图中的图层与脚本数据源；提交需宿主确认。

权限：map.write
平台：桌面、移动、网页
签名：map.clear(): ChangePlan<void>

`map.addGeoJSON`

读取 GeoJSON 并作为面或线显示；同时需要 project.read 和 map.write。

权限：map.write
平台：桌面、移动、网页
签名：map.addGeoJSON(arg0: string, arg1: GeoJSON): Operation<MapLayerRef>

map.sources

`map.sources.add`

将数据集注册为地图数据源，不自动绘制。

权限：map.write
平台：桌面、移动、网页
签名：map.sources.add(arg0: string, arg1: DatasetSourceSpec | GeoJSONSourceSpec | VectorFileSourceSpec | RasterFileSourceSpec | XyzSourceSpec | RasterDemSourceSpec | OnlineRasterDemSourceSpec | PointCloudSourceSpec | ModelSourceSpec | Tiles3dSourceSpec | GaussianSplatSourceSpec, arg2?: SceneOwnerOptions): Operation<SourceRef>

`map.sources.get`

按精确标识查找地图数据源。

权限：project.read
平台：桌面、移动、网页
签名：map.sources.get(arg0: string): Operation<SourceRef | null>

`map.sources.remove`

预演移除未被显示图层使用的数据源。

权限：map.write
平台：桌面、移动、网页
签名：map.sources.remove(arg0: SourceRef): ChangePlan<void>

`map.sources.list`

列出当前地图数据源。

权限：project.read
平台：桌面、移动、网页
签名：map.sources.list(arg0?: PageOptions): Operation<Page<SourceInfo>>

map.layers

`map.layers.add`

用已有数据源创建面、线、圆点、影像、高程晕渲/分层设色、点云、模型、3D Tiles 或高斯泼溅显示。

权限：map.write
平台：桌面、移动、网页
签名：map.layers.add(arg0: FillLineLayerSpec | RasterLayerSpec | SymbolLayerSpec | HeatmapLayerSpec | HillshadeLayerSpec | ColorReliefLayerSpec | PointCloudLayerSpec | ModelLayerSpec | Tiles3dLayerSpec | GaussianSplatLayerSpec, arg1?: SceneOwnerOptions): Operation<MapLayerRef>

`map.layers.get`

按精确标识或名称查找显示图层。

权限：project.read
平台：桌面、移动、网页
签名：map.layers.get(arg0: string): Operation<MapLayerRef | null>

`map.layers.removeMany`

统一预演并确认移除多个显示图层；源文件不变。

权限：map.write
平台：桌面、移动、网页
签名：map.layers.removeMany(arg0: MapLayerRef[]): ChangePlan<void>

`map.layers.remove`

预演移除显示图层。

权限：map.write
平台：桌面、移动、网页
签名：map.layers.remove(arg0: MapLayerRef): ChangePlan<void>

`map.layers.rename`

更改显示图层名称。

权限：map.write
平台：桌面、移动、网页
签名：map.layers.rename(arg0: MapLayerRef, arg1: string): Operation<void>

`map.layers.move`

更改显示图层的叠加顺序。

权限：map.write
平台：桌面、移动、网页
签名：map.layers.move(arg0: MapLayerRef, arg1: MapLayerMoveOptions): Operation<void>

`map.layers.duplicate`

复制显示配置并复用原数据源。

权限：map.write
平台：桌面、移动、网页
签名：map.layers.duplicate(arg0: MapLayerRef, arg1?: MapLayerDuplicateOptions): Operation<MapLayerRef>

`map.layers.list`

分页列出脚本及工作台既有矢量、影像图层摘要。

权限：project.read
平台：桌面、移动、网页
签名：map.layers.list(arg0?: PageOptions): Operation<Page<MapLayerInfo>>

`map.layers.setVisible`

设置显示图层的可见性。

权限：map.write
平台：桌面、移动、网页
签名：map.layers.setVisible(arg0: MapLayerRef, arg1: boolean): Operation<void>

`map.layers.setOpacity`

设置整层透明度乘数。

权限：map.write
平台：桌面、移动、网页
签名：map.layers.setOpacity(arg0: MapLayerRef, arg1: number): Operation<void>

`map.layers.setPaint`

原子更新常量、属性和连续缩放样式。

权限：map.write
平台：桌面、移动、网页
签名：map.layers.setPaint(arg0: MapLayerRef, arg1: FillLinePaintPatch | SymbolPaintPatch | HeatmapPaint | ElevationPaintPatch | PointCloudPaint | Tiles3dPaint): Operation<void>

`map.layers.setHeight`

按数字字段设置静态线图层的三维显示高度，不修改源数据；高度米=(字段值-base)*exaggeration+offset，平面基准且不贴地形。仅支持 EPSG:3857 地图中的静态实线图层及其普通颜色、线宽、透明度样式；全层字段须为有限数字，先完整校验再应用。null 清除并恢复默认高度。

权限：map.write
平台：桌面、移动、网页
签名：map.layers.setHeight(arg0: MapLayerRef, arg1: LayerHeightOptions | null): Operation<LayerHeightSummary>

`map.layers.classify`

按完整源数据生成确定分类颜色与图例。

权限：map.write
平台：桌面、移动、网页
签名：map.layers.classify(arg0: MapLayerRef, arg1: ClassificationOptions): Operation<ClassificationSummary>

`map.layers.setVertexHeight`

按三维线各顶点的米制高程设置显示高度，沿线起伏且不修改源几何；支持 Web 墨卡托静态实线，先完整校验后应用，显示期间源线只读，null 清除高度。

权限：map.write
平台：桌面、移动、网页
签名：map.layers.setVertexHeight(arg0: MapLayerRef, arg1?: VertexHeightOptions | null): Operation<VertexHeightSummary>

`map.layers.clearClassification`

清除分类并恢复之前的颜色样式。

权限：map.write
平台：桌面、移动、网页
签名：map.layers.clearClassification(arg0: MapLayerRef): Operation<void>

`map.layers.legend`

分页读取完整源数据分类图例与业务代码说明。

权限：project.read
平台：桌面、移动、网页
签名：map.layers.legend(arg0: MapLayerRef, arg1?: PageOptions): Operation<Page<LegendEntry>>

`map.layers.ready`

等待图层在当前视野加载到位后返回图层状态；不代表整个数据集已加载，超时返回当前状态。

权限：project.read
平台：桌面、移动、网页
签名：map.layers.ready(arg0: MapLayerRef, arg1?: LayerReadyOptions): Operation<MapLayerInfo>

`map.layers.setFilter`

按类型化条件筛选显示，不修改源数据。

权限：map.write
平台：桌面、移动、网页
签名：map.layers.setFilter(arg0: MapLayerRef, arg1: Expression|boolean|null): Operation<void>

map.camera

`map.camera.fitLayer`

定位到显示图层范围。

权限：map.write
平台：桌面、移动、网页
签名：map.camera.fitLayer(arg0: MapLayerRef, arg1?: CameraFitOptions): Operation<void>

`map.camera.fitLayers`

定位到多个指定显示图层的合并范围。

权限：map.write
平台：桌面、移动、网页
签名：map.camera.fitLayers(arg0: MapLayerRef[], arg1?: CameraFitOptions): Operation<void>

`map.camera.fitFeature`

定位到本次任务的单个真实要素。

权限：map.write
平台：桌面、移动、网页
签名：map.camera.fitFeature(arg0: FeatureRef, arg1?: CameraFitOptions): Operation<void>

`map.camera.state`

读取明确的坐标系和每逻辑像素分辨率。

权限：project.read
平台：桌面、移动、网页
签名：map.camera.state(): Operation<CameraState>

`map.camera.setView`

设置中心、分辨率或 EPSG:3857 标准 zoom，以及三维俯仰 pitch 与方位 bearing；pitch>0 自动进入三维视图。

权限：map.write
平台：桌面、移动、网页
签名：map.camera.setView(arg0: CameraViewOptions): Operation<void>

`map.camera.fitBounds`

将 WGS84/Web Mercator 范围转换到当前视图后定位；可直接传 minX,minY,maxX,maxY（按 WGS84）。

权限：map.write
平台：桌面、移动、网页
签名：map.camera.fitBounds(arg0: ViewBounds | [number,number,number,number], arg1?: CameraFitOptions): Operation<void>

`map.camera.fitAll`

定位到全部可见图层。

权限：map.write
平台：桌面、移动、网页
签名：map.camera.fitAll(arg0?: CameraFitOptions): Operation<void>

map.lighting

`map.lighting.state`

读取地球仪与三维建筑视图的光照设置。

权限：project.read
平台：桌面、网页
签名：map.lighting.state(): Operation<SceneLightingState>

`map.lighting.set`

调整地球仪或三维建筑视图的光照方向、强度、背光亮度与太阳时间。

权限：map.write
平台：桌面、网页
签名：map.lighting.set(arg0: SceneLightingOptions): Operation<SceneLightingState>

map.camera

`map.camera.focusWgs84`

定位经纬度，可在 Web Mercator 视图指定标准 zoom。

权限：map.write
平台：桌面、移动、网页
签名：map.camera.focusWgs84(arg0: [number,number], arg1?: {zoom?:number}): Operation<void>

map.features

`map.features.selection`

读取当前主选要素的版本快照。

权限：project.read
平台：桌面、移动、网页
签名：map.features.selection(): Operation<FeatureRef | ClusterRef | null>

`map.features.selectionSet`

读取当前单一数据集的多选快照。

权限：project.read
平台：桌面、移动、网页
签名：map.features.selectionSet(): Operation<FeatureSetRef | null>

`map.features.clearSelection`

清除当前要素选择。

权限：map.write
平台：桌面、移动、网页
签名：map.features.clearSelection(): Operation<void>

`map.features.select`

以指定版本要素替换当前选择。

权限：map.write
平台：桌面、移动、网页
签名：map.features.select(arg0: FeatureRef): Operation<void>

`map.features.selectSet`

以指定版本集合替换当前选择。

权限：map.write
平台：桌面、移动、网页
签名：map.features.selectSet(arg0: FeatureSetRef): Operation<void>

`map.features.get`

读取有界的类型化要素详情。

权限：project.read
平台：桌面、移动、网页
签名：map.features.get(arg0: FeatureRef, arg1?: FeatureReadOptions): Operation<FeatureResult>

`map.features.query`

按地图内容区逻辑像素查询可见要素。

权限：project.read
平台：桌面、移动、网页
签名：map.features.query(arg0: MapFeatureQueryOptions): Operation<Page<MapHit>>

map.camera

`map.camera.centerOn`

定位到地名、经纬度、范围或图层/数据：地名按行政级别自动缩放（省7/市11/县12/乡镇15）。

权限：map.write
平台：桌面、移动、网页
签名：map.camera.centerOn(arg0: CenterOnTarget, arg1?: CenterOnOptions): Operation<void>