查询身份、选择与数据更新
选择面板和悬停UI由使用方维护，地图提供源/渲染查询、要素状态及事件。selected、hover等是使用方定义的状态键，查询不会自动选择、修改原始属性或业务数据。
| 身份/修订 | 用途与变化规则 |
|---|---|
| sourceInstanceId | 源实例；移除重建产生新值，旧句柄不能操作新源 |
| sourceLayer和id | MVT目标必须指定sourceLayer；数字ID与字符串ID区分。跨样式层显示同一源要素共享状态 |
| dataRevision | 数据更新变化；直接用旧查询Feature作状态目标会拒绝，避免旧快照误写 |
| cacheRevision/layerInstanceId | 显示快照/层身份；不能用数组位置代替长期身份 |
| stateRevision | 状态修改独立变化，不改dataRevision或原始属性 |
显式或promoteId的有效ID状态在同一源数据更新后保留；可以预设暂不存在的ID状态。generateId的整体替换清空状态，避免索引重排选错。源移除重建不继承状态。MVT渲染查询已按层内稳定类型ID去重；源查询保留瓦片片段，几何拼接/合并仍未实现。
下面的选择处理器刻意保留源实例及规范ID，允许同源稳定ID跨数据修订继续选中；若需要只操作精确查询快照，直接把原Feature作为目标，保留sqs.dataRevision校验。
import {map} from 'sqsmap';
let selected;
const current = async target => {
const source = await map.getSource(target.source);
return source?.sourceInstanceId === target.sqs.sourceInstanceId;
};
const targetOf = feature => {
const id = feature.id;
if (!(typeof id === 'string' || (typeof id === 'number'
&& Number.isFinite(id) && Math.abs(id) <= Number.MAX_SAFE_INTEGER))
|| !feature.sqs?.sourceInstanceId)
throw Error('A stable feature identity is required');
return {source:feature.source,id:feature.id,
...(feature.sourceLayer ? {sourceLayer:feature.sourceLayer} : {}),
sqs:{sourceInstanceId:feature.sqs.sourceInstanceId}};
};
export async function selectFeature(feature) {
const next = feature ? targetOf(feature) : undefined;
if (next && !await current(next)) throw Error('Source was replaced');
if (selected && await current(selected))
map.setFeatureState(selected, {selected:false});
if (next) map.setFeatureState(next, {selected:true});
await map.sqs.flush({render:true});
selected = next;
}
// Caller-owned UI awaits selectFeature(hit) or selectFeature(undefined).
// Caller serializes updates and displays errors; no DOM object is passed.
调用方必须串行调用处理器，等待结果后更新UI；失败时报告错误，重新读取getFeatureState并核对当前源身份。多个写入及flush不是通用事务，清旧状态成功、新状态失败时不能显示为全部成功。同一要素重复选择不会影响业务属性。源变更后重读状态和查询；generateId更新及源实例变化时清掉UI缓存。
用paint中的feature-state为selected/hover定义颜色或尺寸，缺失值显式设回退；filter/layout不接受feature-state。鼠标/按层事件和sqs.sourceschange触发外部UI刷新；停止时取消订阅、拒绝迟到异步读取，地图销毁释放源状态。停止普通脚本不自动销毁宿主地图。
要素状态 · 查询 · 悬停事件 · MVT去重范围。接口与原生/桌面/浏览器既有验收均已实现，本项补齐身份/选择文档；移动GIS应用、设备及正式发行另行验收。