跳到主要内容
SqsMap地图与空间数据工具

地图来源与署名

完整来源查询、图源身份与自定义署名界面

共同脚本使用 await map.sqs.getAttributions()，独立网页 SDK 使用 await view.getAttributions()，动态库使用 sqsm_map_attributions_json。这些查询返回当前逻辑来源的完整纯文本和来源记录，不移动相机、不轮询网络、不改变命令或事件序号。使用方负责署名界面；变化事件按宿主轮询或实际帧采样。

图源的 attribution 字段参考 MapLibre 图源规范，实现由 SqsMap 自有核心提供。getAttributions 是 SqsMap 扩展，放在共同脚本的 sqs 名下。

脚本示例

import {map} from 'sqsmap';
map.addSource('trees', {
  type:'geojson', attribution:'© 数据提供方',
  data:{type:'FeatureCollection',features:[]}
});
map.addLayer({id:'trees',type:'circle',source:'trees'});
const credits = await map.sqs.getAttributions();
export default credits;

text 为按首次出现顺序精确去重后的完整文字；items 保留每个独立来源，同样的文字不合并来源身份。每条记录包含 scope、kind、sourceId、sourceInstanceId、layerIds、text。旧快照不会随之后的修改改变，脚本和 SDK 的对象、数组均只读。

  • common：共同 GeoJSON 图源及其引用图层，保留真实不复用的图源实例身份。同名重建不会改变旧快照。
  • style：样式级来源及启用样式图层引用的 vector/GeoJSON 来源。样式级来源是 SqsMap 扩展，始终保留；样式源暂未提供实例身份，sourceInstanceId 为 null。
  • host：通过宿主瓦片 API 登记的来源。网页 raster/terrain-rgb 使用 raster:图层编号及真实资源代次；桌面区分 configured-raster 与 script-raster，暂未提供实例身份，不能冒充共同图源句柄。

显示范围与合并

共同图层和样式图层采用逻辑显隐以及 minzoom 包含、maxzoom 不包含的规则。未被启用图层引用的图源不贡献署名。仍有其他启用图层引用同一来源时保留。透明度、要素筛选、瓦片就绪和像素遮挡不会删除来源，因此保守保留可能适用的署名。

后到的 TileJSON 只更新所属图源，不覆盖样式级和其他图源来源；缺失或空署名保留旧来源。网页宿主瓦片按启用状态和投影兼容性贡献署名；级别限额可继续过度缩放显示，不因此隐藏来源。当前网页地球视图不绘制这些平面宿主瓦片，其来源也不进入快照。桌面按实际样式底图抑制影像、叠加标记和三维配置规则合并宿主来源；离线样式保留原样式来源。外部宿主自行添加而未登记来源的覆盖物不能凭空生成版权信息。

影像与地形

SDK 和网页 xyz/raster-dem 脚本宿主都接收 attribution。请提供服务要求的完整文字和来源链接。

const rasterId = view.addRasterTiles(tileTemplate, {
  scheme:'mercator', attribution:providerCredit
});
await view.flush();
const credits = await view.getAttributions();
creditElement.textContent = credits.text;

这是 SDK 接入片段，view、tileTemplate、providerCredit、creditElement 由使用方提供。下方提供完整变化事件、初始化查询和取消订阅界面示例。

完整性与界面

原始 attribution 必须是字符串，UTF-8 上限 4 KiB。移除 HTML 标签并只解码一次实体，不再截到 180 字。完整快照 JSON 上限 64 KiB；超限返回 RESOURCE_LIMIT，保留地图和已返回的旧快照。清理相应图层后可重新查询，绝不以截断文字或假空数据冒充成功。

自定义界面使用 textContent 等文本写入方式；不要把来源文本当作 HTML 执行。原始 HTML 的链接不作为可执行界面返回，使用方需按图源服务要求补相应来源链接；纯文本不能代替这些链接或完整许可要求。

动态库能力位为 SQSM_MAP_ATTRIBUTION_QUERIES（8192），ABI 版本仍为 1。查询输出独立拥有，失败清零，用 sqsm_map_bytes_free 释放；销毁地图后已取得的缓冲仍有效。完整 C 示例和同一份跨端查询脚本可直接下载。外机及移动应用脚本宿主仍待验收/接入；当前软件验证不代表硬件复验。

Rust 入口为 MapSession::attributions / BasemapSession::attributions，以及 attribution::style_snapshot、common_items、AttributionSnapshot::combine。显式 zoom 必须为有限数。来源查询与变化事件为分开的能力，两者均已接通并分别查询能力。

更多范围见 GeoJSON 图源 API 与 自定义地图工具。

Rust 完整 CompiledStyle 字面量还需 root_attribution；CompiledSource::GeoJson 含 attribution，匹配其余字段可使用 ..。

署名变化事件与完整自定义界面

共同脚本使用 map.on('sqs.attributionschange', event => ...)，event.attributions 与查询返回相同的深冻结完整快照。SDK 支持相同事件名，以及 view.onAttributionsChange(...)；能力查询 attributionEvents 为 true 才表示已接通。独立动态库的持续脚本支持此事件，一次性脚本仍明确拒绝监听；移动应用宿主待接入。

事件在宿主轮询或实际帧采样时产生，同一间隔内的写入可以合并；已发出的历史快照不修改。文字相同但来源身份或引用图层改变仍会通知。没有初始重放：先监听，再查询；用本地版本计数防止慢查询覆盖新事件。

64KiB完整快照超限会发出 error，context === 'attributions'，保留明确错误码；重复相同错误只报告一次，恢复后重新通知。地图、旧快照和只读查询均不被错误通知替换。32订阅、128待处理通知和256KiB待处理内容预算仍适用；溢出明确结束脚本会话。停止释放宿主订阅；地图销毁后未交付通知取消，SDK待处理once承诺以CANCELLED结束。

// @gis-api 0.5-session
// @permissions ["project.read"]
import { map } from 'sqsmap';
export const sessionMode = 'persistent';
let revision = 0;
let current;
map.on('sqs.attributionschange', event => {
  revision++;
  current = event.attributions;
});
const initialRevision = revision;
const initial = await map.sqs.getAttributions();
if (initialRevision === revision) current = initial;
export default { initial: current };

下载完整HTML/CSS/脚本示例并放在匹配SDK的dist/、wasm/目录旁即可运行；含初始查询、事件更新、显隐、重建来源、销毁和清理的全部代码。使用textContent，不执行图源HTML；示例自有几何的来源文字及链接由应用定义。使用OpenFreeMap、ArcGIS等外部服务时，保留该服务要求的明确版权及提供方链接；纯文本查询不会自动代替这些链接。

同一份共同事件脚本用于真实网页主线程/严格Worker与原生持续QuickJS验收。C能力位16384（SQSM_MAP_ATTRIBUTION_EVENTS）；既有sqsm_map_poll_events_json返回attributionEvent.attributions或attributionEvent.context/error。公共队列满时先排空，未入队署名采样在后续轮询重试。ABI保持1，输出所有权不变。