ساخت کارت مکان با جستجو و پیش‌نمایش نقشه

در این راهنما یک مکان را روی سرور جستجو می‌کنید و عنوان، آدرس و نشانگر آن را در یک کارت React نمایش می‌دهید.

پیش‌نیازها

• یک برنامهٔ سرور Express و یک کلید خصوصی با دسترسی جستجو در متغیر محیطی BALAD_API_KEY.
• یک برنامهٔ React با بستهٔ maplibre-gl و یک کلید عمومی با دسترسی نقشه و مبدأ مجاز وب‌سایت.

کد سرور زیر یک مسیر به برنامهٔ Express شما اضافه می‌کند؛ اجرای خود سرور و رابط جستجو باید در برنامهٔ شما فراهم باشد.

مراحل

1. مرورگر عبارت کاربر را به مسیر داخلی /api/poi-card می‌فرستد؛ کلید خصوصی جستجو هرگز در کد مرورگر قرار نمی‌گیرد.
2. سرور نخستین نتیجه را به داده‌های title، address، lat و lng تبدیل می‌کند.
3. نتیجهٔ جستجو را به ورودی poi کارت بدهید و برای ورودی publicKey، یک کلید عمومی با دسترسی نقشه و مبدأ مجاز وب‌سایت قرار دهید.
4. کارت، عنوان و آدرس مکان را همراه نقشه و نشانگر نمایش می‌دهد.

جستجوی مکان روی سرور با Express

import express from "express";

const app = express();
const BALAD_API_KEY = process.env.BALAD_API_KEY;

app.get("/api/poi-card", async (req, res) => {
  const query = typeof req.query.q === "string" ? req.query.q.trim() : "";
  if (!query) return res.sendStatus(400);

  try {
    const url = new URL("https://search.services.balad.ir/v5/service/");
    url.searchParams.set("text", query);
    url.searchParams.set("limit", "1");

    const response = await fetch(url, {
      headers: { Authorization: "Bearer " + BALAD_API_KEY }
    });
    if (!response.ok) return res.sendStatus(response.status);

    const { results = [] } = await response.json();
    const poi = results[0];
    if (!poi) return res.sendStatus(404);

    res.json({
      title: poi.maintext,
      address: poi.subtitle,
      lat: poi.center_point.lat,
      lng: poi.center_point.lng
    });
  } catch {
    res.sendStatus(502);
  }
});

دریافت نتیجهٔ جستجو در مرورگر

const response = await fetch("/api/poi-card?q=" + encodeURIComponent(query));
if (response.status === 404) throw new Error("مکانی پیدا نشد.");
if (!response.ok) throw new Error("دریافت نتیجهٔ جستجو ناموفق بود.");
const poi = await response.json();

کارت مکان با React و MapLibre

import { useEffect, useRef } from "react";
import maplibregl from "maplibre-gl";
import "maplibre-gl/dist/maplibre-gl.css";

if (maplibregl.getRTLTextPluginStatus() === "unavailable") {
  maplibregl.setRTLTextPlugin(
    "https://tile-vector.services.balad.ir/rtl/mapbox-gl-rtl-text.js", true,
  );
}

export function PoiCard({ poi, publicKey }) {
  const container = useRef(null);

  useEffect(() => {
    const map = new maplibregl.Map({
      container: container.current,
      style: "https://tile-vector.services.balad.ir/styles/vector.json?api_key="
        + publicKey,
      center: [poi.lng, poi.lat],
      zoom: 15,
      minZoom: 3,
      attributionControl: { compact: false },
    });
    const marker = new maplibregl.Marker()
      .setLngLat([poi.lng, poi.lat])
      .addTo(map);

    return () => {
      marker.remove();
      map.remove();
    };
  }, [poi.lng, poi.lat, publicKey]);

  return <article className="poi-card">
    <div ref={container} style={{ height: 300 }}
         aria-label={"نقشه موقعیت " + poi.title} />
    <div>
      <h2>{poi.title}</h2>
      <p>{poi.address}</p>
    </div>
  </article>;
}

نتیجهٔ مورد انتظار

پس از دریافت یک نتیجه، کارت عنوان و آدرس مکان را همراه نقشه و یک نشانگر نشان می‌دهد. اگر نتیجه‌ای نباشد، مسیر نمونه وضعیت 404 برمی‌گرداند.

در این تصویر نقشه از بلد دریافت شده و نام و آدرس کارت برای آموزش به‌صورت فرضی قرار داده شده‌اند.

نکات

• مسیر /api/poi-card نمونه‌ای از سرور برنامهٔ شماست و بخشی از API بلد نیست.
• تنها فیلدهای مستند پاسخ را استفاده کنید و حالت نتیجهٔ خالی، خطای سرویس و بارگذاری ناموفق نقشه را در رابط کاربری پوشش دهید.
• کلید خصوصی جستجو فقط روی سرور می‌ماند؛ برای نمایش نقشه از کلید عمومی با مبدأ مجاز وب‌سایت استفاده کنید. نمونهٔ React برای MapLibre GL JS نسخهٔ ۵ است.

مرجع جستجوی مکان · همهٔ آموزش‌های کاربردی