تجميع العلامات

اختيار النظام الأساسي: Android iOS JavaScript

نظرة عامة

يوضح لك هذا البرنامج التعليمي كيفية استخدام مجموعات العلامات لعرض عدد كبير من العلامات على الخريطة. يمكنك استخدام مكتبة @googlemaps/markerclusterer جنبًا إلى جنب مع واجهة برمجة تطبيقات JavaScript للخرائط لدمج علامات التقارب في المجموعات وتبسيط عرض العلامات على الخريطة.

للتعرف على كيفية عمل تجميع العلامات، اعرض الخريطة أدناه.

قد لا تتوفّر العيّنات في منطقتك.

يشير الرقم في المجموعة العنقودية إلى عدد العلامات التي تحتوي عليها. لاحظ أنه عند تكبير أي من مواقع المجموعات العنقودية، ينخفض العدد على المجموعة، وستبدأ في رؤية العلامات الفردية على الخريطة. يؤدي تصغير الخريطة إلى دمج العلامات في مجموعات عنقودية مرة أخرى.

يعرض النموذج أدناه الرمز الكامل الذي تحتاجه لإنشاء هذه الخريطة.

TypeScript

async function initMap() {
  // Request needed libraries.
  const { Map, InfoWindow } = await google.maps.importLibrary("maps") as google.maps.MapsLibrary;
  const { AdvancedMarkerElement, PinElement } = await google.maps.importLibrary("marker") as google.maps.MarkerLibrary;

  const map = new google.maps.Map(
    document.getElementById("map") as HTMLElement,
    {
      zoom: 3,
      center: { lat: -28.024, lng: 140.887 },
      mapId: 'DEMO_MAP_ID',
    }
  );

  const infoWindow = new google.maps.InfoWindow({
    content: "",
    disableAutoPan: true,
  });

  // Create an array of alphabetical characters used to label the markers.
  const labels = "ABCDEFGHIJKLMNOPQRSTUVWXYZ";

  // Add some markers to the map.
  const markers = locations.map((position, i) => {
    const label = labels[i % labels.length];
    const pinGlyph = new google.maps.marker.PinElement({
      glyph: label,
      glyphColor: "white",
    })
    const marker = new google.maps.marker.AdvancedMarkerElement({
      position,
      content: pinGlyph.element,
    });

    // markers can only be keyboard focusable when they have click listeners
    // open info window when marker is clicked
    marker.addListener("click", () => {
      infoWindow.setContent(position.lat + ", " + position.lng);
      infoWindow.open(map, marker);
    });
    return marker;
  });

  // Add a marker clusterer to manage the markers.
  new MarkerClusterer({ markers, map });
}

const locations = [
  { lat: -31.56391, lng: 147.154312 },
  { lat: -33.718234, lng: 150.363181 },
  { lat: -33.727111, lng: 150.371124 },
  { lat: -33.848588, lng: 151.209834 },
  { lat: -33.851702, lng: 151.216968 },
  { lat: -34.671264, lng: 150.863657 },
  { lat: -35.304724, lng: 148.662905 },
  { lat: -36.817685, lng: 175.699196 },
  { lat: -36.828611, lng: 175.790222 },
  { lat: -37.75, lng: 145.116667 },
  { lat: -37.759859, lng: 145.128708 },
  { lat: -37.765015, lng: 145.133858 },
  { lat: -37.770104, lng: 145.143299 },
  { lat: -37.7737, lng: 145.145187 },
  { lat: -37.774785, lng: 145.137978 },
  { lat: -37.819616, lng: 144.968119 },
  { lat: -38.330766, lng: 144.695692 },
  { lat: -39.927193, lng: 175.053218 },
  { lat: -41.330162, lng: 174.865694 },
  { lat: -42.734358, lng: 147.439506 },
  { lat: -42.734358, lng: 147.501315 },
  { lat: -42.735258, lng: 147.438 },
  { lat: -43.999792, lng: 170.463352 },
];

initMap();
index.ts

ملاحظة: اقرأ الدليل حول استخدام TypeScript و"خرائط Google".

JavaScript

async function initMap() {
  // Request needed libraries.
  const { Map, InfoWindow } = await google.maps.importLibrary("maps");
  const { AdvancedMarkerElement, PinElement } = await google.maps.importLibrary(
    "marker",
  );
  const map = new google.maps.Map(document.getElementById("map"), {
    zoom: 3,
    center: { lat: -28.024, lng: 140.887 },
    mapId: "DEMO_MAP_ID",
  });
  const infoWindow = new google.maps.InfoWindow({
    content: "",
    disableAutoPan: true,
  });
  // Create an array of alphabetical characters used to label the markers.
  const labels = "ABCDEFGHIJKLMNOPQRSTUVWXYZ";
  // Add some markers to the map.
  const markers = locations.map((position, i) => {
    const label = labels[i % labels.length];
    const pinGlyph = new google.maps.marker.PinElement({
      glyph: label,
      glyphColor: "white",
    });
    const marker = new google.maps.marker.AdvancedMarkerElement({
      position,
      content: pinGlyph.element,
    });

    // markers can only be keyboard focusable when they have click listeners
    // open info window when marker is clicked
    marker.addListener("click", () => {
      infoWindow.setContent(position.lat + ", " + position.lng);
      infoWindow.open(map, marker);
    });
    return marker;
  });

  // Add a marker clusterer to manage the markers.
  new MarkerClusterer({ markers, map });
}

const locations = [
  { lat: -31.56391, lng: 147.154312 },
  { lat: -33.718234, lng: 150.363181 },
  { lat: -33.727111, lng: 150.371124 },
  { lat: -33.848588, lng: 151.209834 },
  { lat: -33.851702, lng: 151.216968 },
  { lat: -34.671264, lng: 150.863657 },
  { lat: -35.304724, lng: 148.662905 },
  { lat: -36.817685, lng: 175.699196 },
  { lat: -36.828611, lng: 175.790222 },
  { lat: -37.75, lng: 145.116667 },
  { lat: -37.759859, lng: 145.128708 },
  { lat: -37.765015, lng: 145.133858 },
  { lat: -37.770104, lng: 145.143299 },
  { lat: -37.7737, lng: 145.145187 },
  { lat: -37.774785, lng: 145.137978 },
  { lat: -37.819616, lng: 144.968119 },
  { lat: -38.330766, lng: 144.695692 },
  { lat: -39.927193, lng: 175.053218 },
  { lat: -41.330162, lng: 174.865694 },
  { lat: -42.734358, lng: 147.439506 },
  { lat: -42.734358, lng: 147.501315 },
  { lat: -42.735258, lng: 147.438 },
  { lat: -43.999792, lng: 170.463352 },
];

initMap();
index.js

ملاحظة: يتم جمع JavaScript من مقتطف TypeScript.

CSS

/* 
 * Always set the map height explicitly to define the size of the div element
 * that contains the map. 
 */
#map {
  height: 100%;
}

/* 
 * Optional: Makes the sample page fill the window. 
 */
html,
body {
  height: 100%;
  margin: 0;
  padding: 0;
}
style.css

HTML

<html>
  <head>
    <title>Marker Clustering</title>

    <link rel="stylesheet" type="text/css" href="./style.css" />
    <script type="module" src="./index.js"></script>
  </head>
  <body>
    <div id="map"></div>

    <!-- prettier-ignore -->
    <script>(g=>{var h,a,k,p="The Google Maps JavaScript API",c="google",l="importLibrary",q="__ib__",m=document,b=window;b=b[c]||(b[c]={});var d=b.maps||(b.maps={}),r=new Set,e=new URLSearchParams,u=()=>h||(h=new Promise(async(f,n)=>{await (a=m.createElement("script"));e.set("libraries",[...r]+"");for(k in g)e.set(k.replace(/[A-Z]/g,t=>"_"+t[0].toLowerCase()),g[k]);e.set("callback",c+".maps."+q);a.src=`https://maps.${c}apis.com/maps/api/js?`+e;d[q]=f;a.onerror=()=>h=n(Error(p+" could not load."));a.nonce=m.querySelector("script[nonce]")?.nonce||"";m.head.append(a)}));d[l]?console.warn(p+" only loads once. Ignoring:",g):d[l]=(f,...n)=>r.add(f)&&u().then(()=>d[l](f,...n))})
        ({key: "AIzaSyB41DRUbKWJHPxaFjMAwdrzWzbVKartNGg", v: "weekly"});</script>
  </body>
</html>
index.html

تجربة "عيّنة"

JSFiddle.net Google Cloud Shell

كتوضيح بسيط، يضيف هذا الدليل التوجيهي مجموعة من العلامات إلى الخريطة باستخدام مصفوفة locations. يمكنك استخدام مصادر أخرى للحصول على علامات لخريطتك. للمزيد من المعلومات، اقرأ الدليل حول إنشاء العلامات.

إضافة أداة تجميع محدّدات

اتّبِع الخطوات التالية لإضافة أداة تجميع محدّدات المواقع:

1. أضف مكتبة تجميع العلامات إلى صفحتك أو تطبيقك. تتوفّر المكتبة على NPM على الرابط @googlemaps/markerclusterer وفي المستودع على GitHub.

   إدارة شبكة الشركاء (NPM)

   ثبِّت أحدث إصدار من مكتبة @googlemaps/markerclusterer باستخدام NPM.

   npm install @googlemaps/markerclusterer

   شبكة عرض المحتوى (CDN)

   يحمّل النص البرمجي أدناه أحدث إصدار 1.x.x للمكتبة من unpkg.com CDN.

   <script src="https://unpkg.com/@googlemaps/markerclusterer/dist/index.min.js"></script>

2. يمكنك إضافة أداة تجميع محدّدات للمواقع في تطبيقك.
   

   يضيف الكود أدناه أداة تجميع محدِّدات إلى الخريطة.

   إدارة شبكة الشركاء (NPM)

   import { MarkerClusterer } from "@googlemaps/markerclusterer";
   
   const markerCluster = new MarkerClusterer({ markers, map });

   شبكة عرض المحتوى (CDN)

   وعند الوصول إلى المكتبة باستخدام شبكة توصيل المحتوى (CDN)، تتوفّر المكتبة ضمن النطاق markerClusterer العام.

   const markerCluster = new markerClusterer.MarkerClusterer({ markers, map });

   يمرّر هذا النموذج المصفوفة markers إلى MarkerClusterer.

3. تخصيص أداة تجميع العلامات.
   • تخصيص رمز المجموعة من خلال واجهة العارض
   • عدِّل الخوارزمية لإنشاء المجموعات.

مزيد من المعلومات

يمكنك الاطّلاع على أمثلة أكثر تعقيدًا لتجميع العلامات في المستودع على GitHub وقراءة المستندات المرجعية الخاصة بالمكتبة.