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

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

نظرة عامة

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

لمعرفة طريقة عمل تجميع العلامات، اطّلِع على الخريطة أدناه.

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

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

TypeScript

import { MarkerClusterer } from '@googlemaps/markerclusterer';

async function init() {
    // Request needed libraries.
    const [{ InfoWindow }, { AdvancedMarkerElement, PinElement }] =
        await Promise.all([
            google.maps.importLibrary('maps'),
            google.maps.importLibrary('marker'),
        ]);

    const mapElement =
        document.querySelector<google.maps.MapElement>('gmp-map')!;
    const innerMap = mapElement.innerMap;

    const infoWindow = new 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 PinElement({
            glyphText: label,
            glyphColor: 'white',
        });

        const marker = new AdvancedMarkerElement({
            position,
            content: pinGlyph,
            gmpClickable: true,
        });

        // markers can only be keyboard focusable when they have click listeners
        // open info window when marker is clicked
        marker.addEventListener('gmp-click', () => {
            const content = document.createElement('div');
            content.textContent = `${String(position.lat)}, ${String(position.lng)}`;
            infoWindow.setContent(content);

            infoWindow.open({
                anchor: marker,
                map: innerMap,
            });
        });
        return marker;
    });

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

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 },
];

void init();
index.ts

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

JavaScript

import { MarkerClusterer } from '@googlemaps/markerclusterer';

async function init() {
    // Request needed libraries.
    const [{ InfoWindow }, { AdvancedMarkerElement, PinElement }] =
        await Promise.all([
            google.maps.importLibrary('maps'),
            google.maps.importLibrary('marker'),
        ]);

    const mapElement = document.querySelector('gmp-map');
    const innerMap = mapElement.innerMap;

    const infoWindow = new 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 PinElement({
            glyphText: label,
            glyphColor: 'white',
        });

        const marker = new AdvancedMarkerElement({
            position,
            content: pinGlyph,
            gmpClickable: true,
        });

        // markers can only be keyboard focusable when they have click listeners
        // open info window when marker is clicked
        marker.addEventListener('gmp-click', () => {
            const content = document.createElement('div');
            content.textContent = `${String(position.lat)}, ${String(position.lng)}`;
            infoWindow.setContent(content);

            infoWindow.open({
                anchor: marker,
                map: innerMap,
            });
        });
        return marker;
    });

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

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 },
];

void init();
index.js

CSS

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>
        <script>
            // prettier-ignore
            (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: "GOOGLE_MAPS_API_KEY",
            });
        </script>
    </head>
    <body>
        <gmp-map
            center="-28.024,140.887"
            zoom="3"
            map-id="DEMO_MAP_ID"></gmp-map>
    </body>
</html>
index.html

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

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

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

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

   NPM

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

   npm install @googlemaps/markerclusterer

   CDN

   يُحمّل النص البرمجي أدناه أحدث إصدار من المكتبة (2.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

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

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

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

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

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

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