图标图片表达式与缺失回退

具备 commonLineSymbols 的匹配开发SDK还支持共同二维沿线图文：真实逐字弯线路径、目标归属、图文组合及共同预算。下文早期点符号范围与尚待沿线事项，应按此有限子集理解；复杂整形、倾斜/球面/地形与完整道路拼接仍待完成。

共同二维点 symbol 的 icon-image 支持图片值表达式，能力为 commonIconImageExpressions。['image', name] 同步查当前登记或已加载的图片，存在时返回内部图片值，缺失时返回真正的 null。coalesce 因而可以选择下一张可用图片；不需要下载新图源或把图片名转换为文字。

import { map } from 'sqsmap';
const rgba = (width, height, color) => ({
  width, height,
  data: Array.from({ length: width * height }, () => color).flat()
});
map.addImage('fallback', rgba(12, 12, [0, 0, 255, 255]));
map.addSource('points', { type: 'geojson', data: {
  type: 'Feature', id: 7, properties: { icon: 'primary' },
  geometry: { type: 'Point', coordinates: [116.4, 39.9] }
} });
map.addLayer({ id: 'icons', type: 'symbol', source: 'points',
  layout: { 'icon-image': ['let', 'name', ['get', 'icon'],
    ['let', 'pic', ['image', ['var', 'name']],
      ['coalesce', ['var', 'pic'], ['image', 'fallback']]]] }
});
await map.sqs.flush();
// primary此前缺失，显示蓝色fallback；添加后同一图层自动选择primary。
map.addImage('primary', rgba(16, 8, [255, 0, 0, 255]), { pixelRatio: 2 });
await map.sqs.flush();

普通字符串保持原行为：直接指定图片名称，不测试可用性。['coalesce', 'missing', ['image', 'fallback']] 会选非null字符串 missing，没有图片可画；若要按资源存在与否回退，应使用 image。空字符串同样非null，但表示不画图标；显式 ['image', ''] 是非法名称。所有候选都缺失时没有图标，也没有对应渲染查询命中。

图片值可在 case、match、coalesce、let/var 之间传递，保留实际图片身份。每个let绑定捕获父作用域，按需求值；同一let中的兄弟绑定不能互相引用，请像示例一样嵌套。未使用绑定和未选中分支不会求值。图片变量不能送入普通字符串、数字或布尔运算；format 值不能作为 icon-image。图片名称表达式、控制流与变量展开共享既有8192步/64层预算，表达式最多32层/1024节点。

图标继续使用原RGBA/SDF路径及全部现有参数：RGBA保持bitmap本色，仅乘 icon-opacity；SDF使用 icon-color 与 icon-opacity。尺寸仍按图片像素宽高除以pixelRatio再乘icon-size；锚点、icon-offset、旋转、整体碰撞、排序与图层查询均使用选中图片的真实区域。SDF图标可用，format图片段仍明确拒绝SDF，两者边界独立。

仅可见要素实际尝试过的缺失名称进入 styleimagemissing。主图片已存在时，不求值也不通知未使用的回退图片；添加、更新、删除图片或修改图源属性会重新选择资源并刷新查询。事件去重、代次与持续脚本要求见缺失样式图片。原生与WASM图片写入均在提交前执行共同符号候选校验；非法图层、图源或图片更新以及输出准备失败保留旧资源、表达式、图层身份和画面。

名称最多256字节；既有图片登记、图集、点数量、碰撞和显示预算继续生效。本能力仅共同平面点图标，不扩展pattern、下载、URL底图表达式域、沿线或三维组合，也不表示移动应用及正式发行已经验收。语义参考MapLibre image规范，由本项目自行实现。

可复制共同脚本，或使用完整浏览器页面。

完整脚本见portable-icon-image.js，独立网页见icon-image-check.html。相同脚本验证16项，覆盖真实图片可用性回退、变量/数据刷新、实际missing需求、RGBA/SDF保持、非法候选原子性与身份；最终蓝色12×12图片做像素核验。