Sukha地图 JavaScript SDK 开发文档

版本基线：0.1.0-alpha.37 · 2026-10-08 · 浏览器 JavaScript / TypeScript。

本文按入门、开发指南、插件与工具、接口参考、常见问题组织。示例使用 load 返回的 SDK 命名空间，与普通网页和 npm 工程共用。接口名称和参数以Sukha实际实现为准，不默认兼容全部高德 JS API。

1. 概述

1.1 功能介绍

数据范围由授权数据集决定。骑行、完整省市区门牌、行政边界不在本次范围。当前 JS 不提供独立 Arc 类。JS Loader 支持 language / voiceLanguage，分别配置界面和录音语言，值为 zh-CN、en-US、my-MM，语音未指定时跟随界面；默认中文。不同 SDK 实例互不影响。

1.2 下载与运行环境

SDK 安装包由平台提供；使用与本文匹配的 browser 或 ESM/TypeScript 包。文档下载仅包含教程与 API 参考，不包含 SDK 二进制。不要假设公共 npm 已发布相同版本。

推荐现代 Chrome、Edge、Android WebView 等支持 SDK 所需 WebGL、Worker、Promise 的环境，通过 HTTPS 或 localhost 运行。已做 Chrome 检查，未承诺 Chrome 49、所有 iOS Safari 或所有厂商 WebView 可用。浏览器定位和音频能力需要实际设备验证。

2. 入门指南

2.1 获取 Key

申请Sukha WEB Key，登记页面完整 Origin（协议、域名、端口）、数据集及地图/搜索/路线/导航权限。localhost:8080 与其他端口、HTTP 与 HTTPS 是不同 Origin。页面只放 WEB Key，不放服务器管理凭据。

2.2 方式一：普通网页加载

将交付包整个 browser 目录复制到网站 /vendor/sukha/alpha37/，保留 assets、Worker、语音和许可证目录。不必额外引入 MapLibre。

<!doctype html>
<html lang="zh-CN">
<head>
  <meta charset="UTF-8">
  <meta name="viewport" content="width=device-width,initial-scale=1">
  <title>Sukha地图</title>
  <link rel="stylesheet" href="/vendor/sukha/alpha37/sukha.css">
  <style>html,body,#map{height:100%;margin:0}</style>
</head>
<body>
  <div id="map"></div>
  <script src="/vendor/sukha/alpha37/sukha.js"></script>
  <script type="module">
    try {
      const sdk = await SukhaSDK.load({
        key: 'YOUR_WEB_KEY',
        serviceBaseUrl: 'https://map.sukha.cn',
        datasetId: 'YOUR_DATASET_ID',
        version: '0.1.0-alpha.37'
      });
      const map = new sdk.Map('map', {center: [100.02228,21.67623], zoom: 16});
      await map.ready;
      window.addEventListener('pagehide', () => map.destroy(), {once:true});
    } catch (error) {
      console.error(error.code, error.message);
      document.getElementById('map').textContent = '地图加载失败，请检查授权和网络';
    }
  </script>
</body>
</html>

SDK 的 script 不加 async 或 type=module；它必须先于业务代码执行。业务 module 用于顶层 await。SukhaSDK 全局提供 load、version 等，地图和服务类从 load 返回的 sdk 获取。单页应用在组件卸载时销毁；使用浏览器往返缓存的页面，恢复时需重建已经销毁的实例。

2.3 方式二：npm / TypeScript 工程

把固定包解压到项目 vendor/sukha-sdk，保留 package.json 和 dist，然后安装该本地包：

npm install ./vendor/sukha-sdk

import {load} from '@sukha/maps';
import '@sukha/maps/style.css';

const sdk = await load({
  key: 'YOUR_WEB_KEY', serviceBaseUrl: 'https://map.sukha.cn',
  datasetId: 'YOUR_DATASET_ID', version: '0.1.0-alpha.37'
});
const map = new sdk.Map('map', {center:[100.02228,21.67623], zoom:16});
await map.ready;

两种加载方式二选一，不重复加载两套 SDK。npm 工程使用 import 导出，非 CommonJS require。框架生产构建需保留 CSS、Worker 和语音资源路径；跨构建工具不能只验证开发模式。优先使用 browser 目录可以减少资源打包配置。

2.4 Loader 参数说明

load(config, callback?) → Promise<Namespace>。推荐 await 和 try/catch；可选回调采用 complete/error 状态。

getCapabilities() 返回授权数据集及 capabilities；它不是所有后端接口的逐项验收结果。不支持的 Loader 参数会报错。语言示例：load({key: '你的 Web Key', language: 'my-MM', voiceLanguage: 'en-US'})。已有实例变更语言时销毁后重新初始化。地图地名使用服务端翻译，未翻译的名称保留原名；宿主业务文案自行翻译。

3. 基础概念与坐标

默认 WGS84；缅甸业务建议保留默认。业务本身使用 GCJ02 时，在 load 传 coordinateSystem:'GCJ02'，地图、搜索、路线公开输入输出自动转换。不要再手工二次转换。算法转换区间是经度 73.66–135.05、纬度 3.86–53.55，区间外报错，不根据坐标猜测系统。

浏览器 Geolocation 原始测量由 SDK 转成公开模式；手动传给 Navi/WalkingNavi 的 Fix 要用公开模式。配送 DeliveryPoint/快照明确保持 WGS84。setThemeLocation 使用原始 WGS84 位置。手工图层及覆盖物数据应符合地图公开模式，第三方栅格不自动重投影。

4. 创建地图

4.1 Map 构造参数

new sdk.Map(container, options?)；container 为元素 ID 或 HTMLElement，必须已有非零尺寸。

创建后 await map.ready；初始化/底图错误由 Promise 或 error 事件处理。销毁后不可复用同一 Map 对象。

4.2 昼夜主题

map.setTheme('auto');
map.on('themechange', ({theme,mode}) => console.log(theme,mode));
// map.setTheme('day'); map.setTheme('night');

getTheme() 返回配置模式，getResolvedTheme() 返回实际主题。自动模式结合时间、太阳位置与地理位置判断。setThemeLocation(rawWgs84Point) 使用宿主已有原始定位，传 null 恢复地图中心；它不主动启动定位。

5. 与地图交互

5.1 相机与范围

map.setZoomAndCenter(17,[100.02228,21.67623]);
map.setRotation(0);
map.setPitch(0);
const pixel = map.lngLatToContainer([100.02228,21.67623]);
const position = map.containerToLngLat(pixel);
console.log(map.getBounds(), position);

5.2 控件

const scale = new sdk.Scale({position:'LB'});
const toolbar = new sdk.ToolBar({position:'RT',offset:[12,12]});
map.addControl(scale);
map.addControl(toolbar);

position 支持 LT/RT/LB/RB；offset 为 Pixel 或 [x,y]。控件 show/hide 控制显隐，map.removeControl 解除绑定，destroy() 最终释放。

5.3 事件

function onClick(event) { console.log(event.lnglat); }
map.on('click',onClick);
map.once('complete',() => console.log('地图完成一次加载'));
// map.off('click',onClick);

通用事件对象提供 on、once、off；解绑时保留原函数引用。地图当前转发 click、movestart、mapmove、moveend、zoomstart、zoomend、dragstart、dragend，另有 complete、error、themechange。不要假定所有高德事件名均可触发。服务 complete/error 与地图 complete 含义不同。

6. 覆盖物

6.1 Marker

const shop = new sdk.Marker({map,position:[100.02228,21.67623],title:'门店',anchor:'bottom'});
shop.on('click',() => console.log(shop.getPosition()));
shop.setPosition([100.023,21.677]);
shop.setAngle(90);

6.2 Polyline、Polygon、Circle

/** @type {[number,number][]} */
const path = [[100.022,21.676],[100.024,21.678],[100.026,21.676]];
const line = new sdk.Polyline({map,path,strokeColor:'#1268e5',strokeWeight:5,strokeOpacity:0.9});
const polygon = new sdk.Polygon({map,path,fillColor:'#1268e5',fillOpacity:0.15});
const circle = new sdk.Circle({map,center:path[0],radius:100,fillOpacity:0.15});
map.setFitView([line],true,[32,32,120,32],18);

path 为点数组；strokeWeight 为线宽，透明度 0–1；radius 为米。Polyline 提供 getLength、getBounds、setPath、setOptions；Polygon 提供 getArea、contains；Circle 提供 setCenter/setRadius。面积单位平方米。

6.3 InfoWindow

const info = new sdk.InfoWindow({content:'门店说明',closeWhenClickMap:true});
info.open(map,[100.02228,21.67623]);
// info.setContent(element); info.close(); info.destroy();

content 字符串按纯文本展示，不解析 HTML。富文本请构造可信 HTMLElement，并用 textContent 写入外部文字。参数还包括 position、offset、size；getIsOpen 读取状态。

6.4 平滑移动

shop.moveTo([100.024,21.678],{duration:1500});
// shop.pauseMove(); shop.resumeMove(); shop.stopMove();

moveAlong 支持路径动画，参数以 MoveOptions/MovePath 声明为准。动画展示不替代真实定位、上传或导航计算；对象移除时应停止动画。

7. 数据可视化与图形工具

7.1 热力图

const heat = new sdk.HeatMap(map,{radius:25,opacity:[0,0.8]});
heat.setDataSet({data:[{lng:100.02228,lat:21.67623,count:10}],max:20});

radius 为像素核大小；opacity 为透明度区间；gradient 为数值分段到 CSS 颜色的映射；zooms 限定显示级别。数据字段为 lng、lat、count，max 为归一化上限。支持 addDataPoint、setOptions、show/hide/destroy。

7.2 点聚合

const cluster = new sdk.MarkerCluster(map,[
  {lnglat:[100.02228,21.67623],shopId:'a'},
  {lnglat:[100.02230,21.67625],shopId:'b'}
],{gridSize:60,maxZoom:20,minClusterSize:2,zoomOnClick:true});

更新 setData 或 addData，读取 getCount/getClustersCount，结束 destroy。算法为网格聚合，不承诺与高德生成相同分组。

7.3 瓦片与海量点

// 仅演示地址模板：替换成业务有权使用的 XYZ 瓦片服务。
const tiles = new sdk.TileLayer({map,
  tileUrl:'https://YOUR_TILE_SERVER/{z}/{x}/{y}.png',
  tileSize:256,opacity:0.7,zooms:[10,20]
});
const mass = new sdk.MassMarks([
  {lnglat:[100.02228,21.67623],id:'shop-1'}
],{map,opacity:0.9});
mass.on('click',event => console.log(event.data));
// mass.setData(nextData); mass.destroy(); tiles.destroy();

tileSize 支持 256/512，opacity 为 0–1；MassMarks 可通过 style 配置图标 URL、尺寸和锚点。第三方瓦片的授权、坐标和数据质量由提供方决定。海量点不是 POI 搜索服务；数量性能应在目标浏览器验证。

7.4 绘制、编辑

const mouse = new sdk.MouseTool(map);
mouse.on('draw',event => console.log(event.obj));
mouse.polyline({strokeColor:'#1268e5',strokeWeight:5});
// 单击加点、双击结束。mouse.close(false) 退出并保留完成图形。
const editor = new sdk.PolylineEditor(map,line);
editor.open();
// editor.close(); editor.destroy(); mouse.destroy();

MouseTool 支持 marker、polyline、polygon、circle、rectangle；本版 JS 的 finish 是内部方法，业务不能像 Android 一样调用 finish。编辑器支持顶点拖动、中点插入、右键删除以及 addNode/removeNode；PolygonEditor 对面使用同样调用方式。

8. 定位

8.1 单次定位与定位控件

const location = new sdk.Geolocation({
  enableHighAccuracy:true,timeout:15000,maximumAge:0,
  showButton:true,showMarker:true,showCircle:true,
  panToLocation:true,buttonPosition:'RB',needAddress:false
});
map.addControl(location);
try {
  const fix = await location.getCurrentPosition();
  console.log(fix.position,fix.accuracy,fix.heading,fix.speed,fix.timestamp);
} catch(error) { console.error(error.code,error.message); }

Geolocation 使用真实浏览器定位权限，不用 IP 或示例坐标伪造定位。SDK 坐标变化不能提升原始传感器精度。

8.2 持续定位与地址

const watchId = location.watchPosition((status,result) => {
  if(status === 'complete') console.log(result.position);
  else console.warn(result);
});
// 停止：location.clearWatch(watchId);
// 页面释放：location.destroy();

needAddress:true 时监听 address 事件补充地址，不阻塞坐标结果。回调接口与 Promise 错误形态不同；定位公共控件的错误回调为字符串错误码，await 抛 SDKError。浏览器后台、锁屏、省电状态不保证持续回调。

9. 搜索与地理编码

9.1 POI 搜索

const search = new sdk.PlaceSearch({map,pageIndex:1,pageSize:20});
const result = await search.search('酒店');
console.log(result.poiList.count,result.poiList.pois);
const nearby = await search.searchNearBy('酒店',[100.02228,21.67623],1000);
if(nearby.poiList.pois.length) {
  const detail = await search.getDetails(nearby.poiList.pois[0].id);
  console.log(detail.name,detail.location);
}

pageIndex 为 1–5，pageSize 为 1–50；type 为Sukha分类字符串；map 可选，传入时服务可显示结果标记。周边 radius 为 0–5000 米。返回 POI 包含 id、name、type、location，kind 可区分地点/建筑；ID 不兼容高德 ID。city 等未声明筛选参数不受支持。

setPageIndex/setPageSize 改分页，clear() 清理搜索标记，cancel() 取消请求，destroy() 释放服务。同一个服务新请求取消旧请求，需要并行时使用独立实例。

9.2 输入联想与搜索框

// 页面先提供 <input id="keyword">
const autocomplete = new sdk.AutoComplete({input:'keyword'});
const suggestions = await autocomplete.search('酒店');
console.log(suggestions.tips);

input 可为 ID 或 HTMLInputElement；也可不绑定输入控件，仅调用 search。SearchBox 是组合 UI，按 SearchOptions 创建。触碰输入框及下拉区域之外会收起建议；程序切换菜单时可以调用 searchBox.hideSuggestions()，最终退出 destroy。

9.3 正地理编码与逆地理编码

const geocoder = new sdk.Geocoder({radius:1000,extensions:'all'});
const address = await geocoder.getAddress([100.02228,21.67623]);
console.log(address.regeocode.formattedAddress,address.regeocode.matched);
const places = await geocoder.getLocation('门店名称');
console.log(places.geocodes);

正查询匹配已发布地点/建筑名称。名称结果或 formattedAddress 不等于完整街道门牌解析。geocodes 空数组代表无匹配，使用回调时可以收到 no_data。

10. 路线规划

10.1 驾车路线

const driving = new sdk.Driving({map,policy:sdk.DrivingPolicy.LEAST_TIME});
const routeResult = await driving.search(
  [100.02228,21.67623],[100.03,21.68],
  {waypoints:[]}
);
for(const route of routeResult.routes) console.log(route.distance,route.time,route.path,route.steps);

DrivingPolicy.LEAST_TIME 对应 TIME，LEAST_DISTANCE 对应 DISTANCE。只提供这两类策略，不接受任意高德数字策略。途经点通过 search 第三参数 waypoints；setAvoidPolygons、setAvoidRoad 配置避让，对应 get/clear 方法读取与清除。

路线约束需匹配后台能力。途经点最多 16 个；JS 避让区域最多 3 个、每个 3–16 点；避让道路名称最多 200 字符。非空 setAvoidRoad 会清空区域，非空 setAvoidPolygons 会清空道路，两类约束互斥。步行不支持途经点及这些驾车约束。服务不支持时处理失败，不将忽略约束视为成功。

10.2 步行路线

const walking = new sdk.Walking({map});
const walkResult = await walking.search([100.02228,21.67623],[100.03,21.68]);
console.log(walkResult.routes);

Walking 使用独立步行路线服务，不通过降低驾车速度模拟。服务器必须开放对应规划接口；本版不提供骑行。

10.3 路线结果

clear() 清除服务绘制的路线；destroy() 释放服务。业务不应依赖渲染器内部图层 ID。

11. 前台网页导航

11.1 驾车导航

const navi = new sdk.Navi();
const gps = new sdk.Geolocation({enableHighAccuracy:true,timeout:15000,maximumAge:0});
// 此函数由页面开始按钮的点击事件调用。
async function startNavigation() {
  navi.unlockVoice(); // 保持在点击同步阶段，放在任何 await 前
  try {
    const fix = await gps.getCurrentPosition();
    await navi.calculateDriveRoute(fix.position,[100.03,21.68]);
    await navi.startNavi({
      position:fix.position.toArray(),accuracy:fix.accuracy,
      timestamp:fix.timestamp,speed:fix.speed,heading:fix.heading
    });
  } catch(error) { console.error(error.code,error.message); }
}
// 结束：navi.stopNavi(); 页面释放：navi.destroy(); gps.destroy();

Navi 规划返回 mode=navigation 的路线，不接收 Driving 预览结果直接替代。startNavi(fix) 使用真实新鲜定位，之后内部订阅浏览器定位。setVoiceEnabled 控制录音，repeat() 重播当前提示。导航事件的真实名称与载荷见配套 API 索引；自定义 UI 不解析音频来推断导航状态。

11.2 步行导航

WalkingNavi 的顺序为用户点击同步 unlockVoice → await calculateWalkRoute(origin,destination) → startNavi()。它与驾车 startNavi(fix) 签名不同。可通过 updateLocation(fix) 注入符合公开坐标模式的真实数据；不要同时注入互相矛盾的定位源。停止用 stopNavi，销毁用 destroy。

11.3 语音与限制

当前语音使用中文录音。browser 版默认从随包 assets/voice 加载；npm/ESM 默认从服务 /sdk-assets/voice/20260914/ 加载，可用 voiceBaseUrl 指定。需保留目录结构及正确 MIME；不要删除 Opus 资源。语音由用户点击解锁，浏览器锁屏、切后台、自动播放限制及解码支持需设备测试。JS 前台导航不承诺原生后台导航能力。

本版 Loader 没有语言参数，也不自动匹配系统语言。宿主自己的按钮/提示可以自行国际化；不能据此把 JS 描述为已完成与 Android 相同的中缅英接口。

12. 工具与组合组件

const a = new sdk.LngLat(100.02228,21.67623);
const meters = a.distance([100.03,21.68]);
console.log(meters);

GeometryUtil 提供距离、面积和几何关系工具，CoordinateConverter 提供显式坐标转换。距离是球面近似，不代替道路里程。DeliveryTrackingMap 和 DeliveryPlacePicker 为可选业务组件；不使用配送业务不需要创建它们。其数据协议仍为明确的 WGS84，订单权限、上传和状态由客户平台管理。

13. 异步回调、错误与释放

13.1 Promise 与回调

推荐 await 服务方法，并捕获 SDKError。回调方式如下：

search.search('酒店',(status,result) => {
  if(status === 'complete') console.log(result.poiList.pois);
  else if(status === 'no_data') console.log('暂无结果');
  else console.error(result); // 字符串错误码，不是完整 SDKError
}).catch(error => console.error(error.code,error.requestId));

服务同时返回 Promise，即便使用回调也应处理拒绝。cancel/destroy 的旧请求不应继续更新已销毁页面；不要依赖取消操作必然回调一次 error。异步结果写入 UI 前检查当前业务会话。

13.2 错误与日志

sdk.setErrorLogger(record => console.warn(record));
// 不再需要日志代理时：sdk.setErrorLogger(null);

不要把表格当成完整的服务端错误枚举；定位与网络服务的错误来源不同。不要记录 Key 或用户完整敏感请求。有限重试时优先遵守 Retry-After，不无限自动循环。

13.3 页面释放顺序

先停止业务订阅、watchPosition、导航，再销毁搜索/路线/编辑器/信息窗，最后 map.destroy。每个独立实例由创建者持有并释放。clearMap() 清理覆盖物，不能代替独立定位和服务对象的 destroy。框架重复挂载先释放旧实例，避免重复地图和监听。

14. API 分类索引

完整类型、方法签名与可选参数见 JavaScript API 声明索引，它与本次 dist 类型声明对应。普通接入通过 load 返回的命名空间创建服务；不要把底层带 Client 的构造签名当作最短业务调用方式。未列插件不自动从第三方 CDN 下载。

15. 常见问题与迁移

迁移时需要更换 Key、数据集、POI ID、坐标约定与策略值。Loader 的 plugin 用于名称校验，功能已在当前包中；它不是高德按需插件下载机制。信息窗字符串是纯文本。可选 @sukha/maps/amap-compat 仅适配部分调用形态，不等于完整高德接口兼容；新项目建议直接使用本文入口。

16. 版本与参考来源

本次基于 0.1.0-alpha.37 源码，通过 TypeScript 编译器重新生成声明并检查示例。详见版本与交付。

栏目结构参考高德 JS API 指南，本文接口和边界按本项目实现编写。