Android 地图视图

SqsMapView 可直接加入 Android 布局。它组合既有地图宿主和触摸识别，显示动态库输出的 RGBA 帧，并将视图尺寸、密度和触摸坐标传给共同地图核心。Java 最低 API24，须同时装入匹配 ABI 的 libsqs_map.so 和 libsqsmap_mobile.so。脚本仍使用 import {map} from 'sqsmap'，无需改写为另一种语言。

SqsMapView mapView = new SqsMapView(this);
mapView.setListener(new SqsMapView.Listener() {
  @Override public void onReady(SqsMapView view, NativeMapHost host) {
    host.runScript("import {map} from 'sqsmap';"
        + "map.jumpTo({center:[0,0],zoom:3});"
        + "map.addSource('demo',{type:'geojson',data:{type:'Feature',"
        + "properties:{},geometry:{type:'Polygon',coordinates:"
        + "[[[-4,-4],[4,-4],[4,4],[-4,4],[-4,-4]]]}}});"
        + "map.addLayer({id:'demo-fill',type:'fill',source:'demo',"
        + "paint:{'fill-color':'#ef4444'}});export default {};")
        .whenComplete((state, error) -> view.post(() -> {
          if (!view.isCurrent(host)) return;
          if (error != null) android.util.Log.e("SqsMap", "初始化失败", error);
        }));
  }
  @Override public void onError(SqsMapView view, Throwable error) {
    android.util.Log.e("SqsMap", "地图错误", error);
  }
});
setContentView(mapView);

构造、监听器配置、状态查询与生命周期调用均在主线程执行，监听器也在主线程执行。runScript(module) 是就绪后的快捷入口；未就绪时返回失败 Future。自定义传输通过 setTransportFactory() 在打开前设置，每个新地图须创建独立 Transport，并随其宿主关闭。加入窗口、完成布局且未暂停后开始创建地图，onReady 提供当次 NativeMapHost。getHost() 未就绪时返回 null；isReady() 只描述当前地图宿主已打开，脚本初始化完成继续看 onScriptState。不要在主线程或地图线程等待自身 Future。使用异步结果前以 isCurrent(host) 确认仍是当前地图。

将 Activity/Fragment 的生命周期接到 pause()、resume() 与最终的 destroy() / destroyAsync()。暂停或离开窗口会立即废弃当前代次、解除触摸、清除待呈现帧，并关闭整个地图宿主，取消 HTTP/WS 和脚本任务。恢复或重新加入窗口须等旧宿主释放后创建新地图，再次调用 onReady。相机、图层、图片和脚本不会自动保存，应用在每次 onReady 重新初始化；最终销毁后不能再次恢复。同一个 View 的重复挂载不会继续使用旧地图句柄。

整个 View 是共同绘制与触摸矩形。逻辑地图尺寸按视图物理尺寸除以显示密度后取整，帧使用核心实际输出尺寸并缩放到该矩形。触摸沿同一矩形映射，接通单指平移、双指缩放/旋转/倾斜与共同点击，受脚本手势策略控制。View 支持显示密度 0.25..8，物理帧每边最多 4096、共 16MiB RGBA，在打开/调整前校验；交付只保留一个待呈现最新帧，RGBA 按离屏读回的 sRGB 预乘格式转换为 Android 所需的非预乘 ARGB，复用颜色数组和 Bitmap，避免依赖字节序或无界 UI 帧队列。宿主对外待执行操作最多 32 项，超出返回 RESOURCE_LIMIT，关闭不占用该队列预算。事件/脚本状态的 UI 通知最多 32 项、单项 256KiB、总计 4MiB；溢出以 RESOURCE_LIMIT 明确报错并停止当前代次，不静默丢弃事件。帧副本、ARGB 数组和 Bitmap 各有内存开销，此外仍有原生、传输、解码和 GPU 开销。

上面的例子加载一块自含 GeoJSON 面，无需外部地图服务。图层面板、缩放/回正等工具、状态展示和图源署名由应用实现。可通过宿主的命令、事件、getStyle() 和 getAttributions() 建立自己的界面；View 不添加常驻调试标签或工具栏。

View 源码、帧交付辅助源码、完整 Activity 示例、版本与 SHA。示例包含生命周期接线；正式应用还需声明网络权限并按服务提供方要求显示来源。

本机最低 API24 的 Java/Activity 与 ARM64 JNI 编译、18 项 CPU 帧门控/转换、15 项真实 JVM/JNI/软件 GPU 检查通过。实际半透明红色帧为 (188,0,0,128)，转换为 Android ARGB 0x80ff0000；不透明蓝色、密度调整、32 项 owner 操作限制、资源取消与打开失败后的清理也有实际证明。窗口生命周期的框架替身检查单独记录，透明三维像素仍待验收；本机 JVM/JNI 帧证明不替代 Android Canvas、MotionEvent、窗口生命周期和设备驱动验收。移动 GIS 应用、iOS、手机设备与正式发行继续待完成。

Android 宿主 · 触摸导航 · 像素密度 · SDK 验收状态

Android 生命周期接线依据 Activity 生命周期，像素呈现使用平台 Bitmap API。