npm.io
0.0.4 • Published yesterday

hamuga-imap-sdk

Licence
—
Version
0.0.4
Deps
1
Size
98 kB
Vulns
0
Weekly
0
SummaryDependencyVersions

Hamuga iMap JS SDK

MapLibre GL-д суурилсан газрын зураг, хайлт (autocomplete), чиглэл тооцоолол (routing), сонирхолтой цэг (POI)-ийн SDK.

Peer dependency: maplibre-gl ^5.15.0. npm-ээр суулгах үед заавал шаардлагатай; <script> tag-аар ашиглах бол HTML дотор MapLibre-г SDK-аас өмнө ачаална.

Суулгах

1. npm (ES Module)

npm install --save hamuga-imap-sdk maplibre-gl
import HamugaImap from "hamuga-imap-sdk";
import "hamuga-imap-sdk/dist/hamuga-imap.min.css";
import "maplibre-gl/dist/maplibre-gl.css";

// === Initialize ===
HamugaImap.initialize({
  debug: true,               // console log-ийг асаах/унтраах
  apiKey: "HAMUGA_IMAP_API_KEY",
  theme: "dark",             // "dark" | "light"
});

// === Газрын зураг ===
const map = HamugaImap.ui.map({
  container: "map",          // element id эсвэл HTMLElement
  center: [106.9, 47.9],
  zoom: 12,
  attributionControl: false,
});

// === Controls ===
const ml = HamugaImap.ui.maplibregl;

map.addControl(new ml.ScaleControl({ maxWidth: 120, unit: "metric" }));

map.addControl(
  new ml.AttributionControl({
    compact: true,
    customAttribution: "© ICT Hamuga iMap",
  }),
  "bottom-right"
);

map.addControl(
  new ml.NavigationControl({
    showZoom: true,
    showCompass: true,
    visualizePitch: true,
  }),
  "bottom-right"             // "top-left" | "top-right" | "bottom-left" | "bottom-right"
);

map.addControl(
  new ml.GeolocateControl({
    positionOptions: { enableHighAccuracy: true },
    trackUserLocation: true,
    showUserLocation: true,
    showAccuracyCircle: true,
    fitBoundsOptions: { maxZoom: 16 },
  }),
  "bottom-right"
);

React-д ашиглах бол map-ыг useRef-д хадгална (const mapRef = useRef(null); mapRef.current = HamugaImap.ui.map({...})), ml-ийг мөн адил. Доорх жишээ энгийн JS хувилбар.

2. <script> tag (HTML)

MapLibre-г SDK-аас өмнө ачаалах ёстой.

<!doctype html>
<html lang="mn">
  <head>
    <meta charset="UTF-8" />
    <meta name="viewport" content="width=device-width, initial-scale=1.0" />

    <!-- 1) MapLibre GL (SDK-аас ӨМНӨ) -->
    <script src="https://unpkg.com/maplibre-gl@5.15.0/dist/maplibre-gl.js"></script>
    <link href="https://unpkg.com/maplibre-gl@5.15.0/dist/maplibre-gl.css" rel="stylesheet" />

    <!-- 2) Hamuga iMap SDK -->
    <script src="https://unpkg.com/hamuga-imap-sdk@0.0.3/dist/iife.global.js"></script>
    <link href="https://unpkg.com/hamuga-imap-sdk@0.0.3/dist/hamuga-imap.min.css" rel="stylesheet" />

    <style>
      html, body, main, #map { margin: 0; padding: 0; width: 100%; height: 100%; }
      main { display: grid; grid-template-columns: 1fr 3fr; }
      aside { padding: 20px; }
      .hamuga-imap-theme-dark aside { background-color: #111; }
    </style>
  </head>

  <body>
    <main>
      <aside><div id="autocomplete"></div></aside>
      <section><div id="map"></div></section>
    </main>

    <script>
      HamugaImap.initialize({
        debug: true,
        apiKey: "HAMUGA_IMAP_API_KEY",
        theme: "dark",
      });

      const map = HamugaImap.ui.map({
        container: "map",
        center: [106.9, 47.9],
        zoom: 12,
        attributionControl: false,
      });

      const ml = HamugaImap.ui.maplibregl;
      map.addControl(new ml.ScaleControl({ maxWidth: 120, unit: "metric" }));
      map.addControl(
        new ml.AttributionControl({ compact: true, customAttribution: "© ICT Hamuga iMap" }),
        "bottom-right"
      );
      map.addControl(
        new ml.NavigationControl({ showZoom: true, showCompass: true, visualizePitch: true }),
        "bottom-right"
      );
      map.addControl(
        new ml.GeolocateControl({
          positionOptions: { enableHighAccuracy: true },
          trackUserLocation: true,
          showUserLocation: true,
          showAccuracyCircle: true,
          fitBoundsOptions: { maxZoom: 16 },
        }),
        "bottom-right"
      );
    </script>
  </body>
</html>

Autocomplete (хайлт)

// UI
HamugaImap.ui.autocomplete({
  container: "autocomplete",
  width: "600px",
  onSelection: (result) => {
    const { latitude: lat, longitude: lng } = result?.location || {};
    if (lat == null || lng == null) return;
    map.flyTo({ center: [lng, lat], zoom: 15 });
    HamugaImap.ui.marker().setLngLat([lng, lat]).addTo(map);
  },
});

// API
HamugaImap.autocomplete({ value: "regency", page: 1, perPage: 3 })
  .then((result) => console.log(result))
  .catch((err) => console.error(err));

Routing (чиглэл)

// Машин / явган
HamugaImap.routing({
  locations: [
    { lat: 47.918, lon: 106.9176 },
    { lat: 47.92,  lon: 106.92 },
  ],
})
  .then((result) => console.log(result))
  .catch((err) => console.error(err));

// Нийтийн тээвэр
HamugaImap.routingBus({
  start: "47.927572261628114,106.93353687526832",
  end: "47.907956772246735,106.91491161586976",
  mode: ["WALK", "BUS"],
})
  .then((result) => console.log(result))
  .catch((err) => console.error(err));

POI (сонирхолтой цэг)

// Талбайгаар
HamugaImap.poi({
  area: false,
  categoryIds: [543],
  llx: 106.90699148188776, lly: 47.90622961174208,   // зүүн-доод булан
  urx: 106.93673742840637, ury: 47.91933711330858,   // баруун-дээд булан
  workHour: "",    // "open" — зөвхөн нээлттэйг
  name: "",        // нэрээр шүүх
  filter: "",
  page: 1,
  size: 10,
})
  .then((result) => console.log(result))
  .catch((err) => console.error(err));

// Координатаар
HamugaImap.poiCoordinate({ lat: 47.91194077591632, lon: 106.92879515654936, zoom: 10 })
  .then((result) => console.log(result))
  .catch((err) => console.error(err));

Хийсэн засварууд (өмнөх зааврын алдаанууд)

Хуучин заавар Асуудал Засвар
https://js.hamuga.mn/v0.0.1/hamuga-imap.min.js Домейн байхгүй (NXDOMAIN) — script tag ачаалагдахгүй https://unpkg.com/hamuga-imap-sdk@0.0.3/dist/iife.global.js
CDN хувилбар v0.0.1 npm пакет 0.0.2 — зөрүүтэй Хамгийн сүүлийн хувилбар (0.0.3) — npm/unpkg-ээс
GeolocateControl({ …, zoom }) zoom хувьсагч тодорхойлогдоогүй → ReferenceError Устгав
onSelection дотор map npm жишээ нь mapRef.current хэрэглэдэг мөртлөө map-д ханддаг Нэг нэрээр (map) тогтвортой болгов
MapLibre CSS дурдаагүй Газрын зургийн control зөв харагдахгүй maplibre-gl/dist/maplibre-gl.css нэмэв

Шаардлага (газрын зураг зурагдахад)

SDK-ийн газрын зураг vector tile-ыг backend-ээс fetch-ээр татдаг тул tile endpoint нь:

  1. Хүрэх боломжтой (амьд домейн), ба
  2. CORS зөвшөөрсөн байх ёстой (Access-Control-Allow-Origin).

Ажиллаж буй tile endpoint: https://gateway.hamuga.mn/tile/tiles/{z}/{x}/{y}.pbf (header x-api-key: <KEY>, CORS *). Хэрэв өөрийн backend-ээр дамжуулж, API key-г нууцлах шаардлагатай бол developer.hamuga.mn-ийн proxy зааврыг үзнэ үү.