入门指南

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'})。已有实例变更语言时销毁后重新初始化。地图地名使用服务端翻译，未翻译的名称保留原名；宿主业务文案自行翻译。