مقدمة
التراكبات هي عناصر على الخريطة مرتبطة بإحداثيات خطوط الطول/دائرة العرض، لذا تتحرك عند سحب الخريطة أو تكبيرها أو تصغيرها. للحصول على معلومات عن أنواع التراكب المحدّدة مسبقًا، اطّلِع على الرسم على الخريطة.
توفّر Maps JavaScript API فئة OverlayView
لإنشاء التراكبات المخصصة. OverlayView
هي فئة أساسية توفر عدة طرق يجب تنفيذها عند إنشاء التراكبات. توفر الفصل أيضًا بعض الطرق التي تتيح الترجمة بين إحداثيات الشاشة والمواقع على الخريطة.
إضافة تراكب مخصّص
في ما يلي ملخّص للخطوات المطلوبة لإنشاء تراكب مخصّص:
- اضبط
prototype
لعنصر التراكب المخصّص على مثيل جديد منgoogle.maps.OverlayView()
. في الواقع، سيؤدي ذلك إلى إنشاء فئة فرعية للفئة تراكب. - أنشئ أداة إنشاء للتراكب المخصّص، واضبط أي مَعلمات إعداد.
- نفِّذ طريقة
onAdd()
داخل النموذج الأوّلي، وأرفِق التراكب بالخريطة. سيتم استدعاءOverlayView.onAdd()
عندما تكون الخريطة جاهزة لإرفاق التراكب. - نفِّذ طريقة
draw()
في النموذج الأوّلي، وتعامل مع المحتوى المرئي لجسمك. سيتم استدعاءOverlayView.draw()
عند عرض الكائن لأول مرة. - يجب أيضًا تنفيذ طريقة
onRemove()
لإزالة أي عناصر أضفتها داخل الصورة المتراكبة.
في ما يلي مزيد من التفاصيل حول كل خطوة. يمكنك الاطّلاع على المثال الكامل والعملي للرمز البرمجي: عرض مثال الرمز البرمجي.
فئة فرعية للتراكب
يستخدم المثال أدناه الرمز OverlayView
لإنشاء صورة مركّبة بسيطة.
الآن ننشئ دالة انشائية لفئة USGSOverlay
، ونُعدّ المَعلمات المُرسَلة كثِمار للكائن الجديد.
TypeScript
/** * The custom USGSOverlay object contains the USGS image, * the bounds of the image, and a reference to the map. */ class USGSOverlay extends google.maps.OverlayView { private bounds: google.maps.LatLngBounds; private image: string; private div?: HTMLElement; constructor(bounds: google.maps.LatLngBounds, image: string) { super(); this.bounds = bounds; this.image = image; }
JavaScript
/** * The custom USGSOverlay object contains the USGS image, * the bounds of the image, and a reference to the map. */ class USGSOverlay extends google.maps.OverlayView { bounds; image; div; constructor(bounds, image) { super(); this.bounds = bounds; this.image = image; }
لا يمكننا بعد إرفاق هذا التراكب بالخريطة في الدالة الإنشائية للتراكب. أولاً، نحتاج إلى التأكد من توفر جميع أجزاء الخريطة، لأنها تحدد الترتيب الذي يتم به عرض الكائنات على الخريطة. وتوفر واجهة برمجة التطبيقات طريقة مساعدة تشير إلى حدوث ذلك. سنتناول هذه الطريقة في القسم التالي.
بدء عرض الصورة المتراكبة
عند إنشاء العنصر المتراكب لأول مرة ويصبح جاهزًا للعرض، علينا إرفاقه
بالخريطة من خلال نموذج DOM للمتصفّح. تشير واجهة برمجة التطبيقات إلى أنّه تمت
إضافة العنصر المتراكب إلى الخريطة من خلال استدعاء طريقة onAdd()
للعنصر المتراكب. لتنفيذ هذه المعالجة، ننشئ عنصرًا من النوع <div>
لعرض الصورة، ونضيف عنصرًا من النوع <img>
، ونُرفقه
بالعنصر <div>
، ثم نُرفِق العنصر المتراكب بإحدى اللوحات في الخريطة. الجزء هو عُقدة داخل شجرة نموذج العناصر في المستند (DOM).
تحدّد الأجزاء، من النوع
MapPanes
،
ترتيب التكديس للطبقات المختلفة على الخريطة. تتوفّر اللوحة التالية، ويتم سردها بالترتيب الذي يتم تجميعها به من أسفل
إلى أعلى:
mapPane
هي اللوحة السفلية وتظهر فوق المربّعات. قد لا يتلقّى أحداث DOM . (الجزء 0).- يحتوي
overlayLayer
على خطوط متعددة الأضلاع وأشكال متعددة الأضلاع وتراكبات الأرض وتراكبات طبقة المربّعات. قد لا يتلقّى أحداث DOM. (اللوحة 1). - يحتوي
markerLayer
على علامات. قد لا يتلقّى أحداث DOM. (اللوحة 2). - يحتوي
overlayMouseTarget
على عناصر تتلقى أحداث DOM. (الجزء 3). - يحتوي
floatPane
على نافذة المعلومات. وهو فوق كل تراكبات الخرائط. (الجزء 4).
ونظرًا لأن صورتنا هي "تراكب أرضي"، فسنستخدم الجزء overlayLayer
. عندما
يصبح لدينا هذا الشريط، سنُرفِق العنصر به كعنصر فرعي.
TypeScript
/** * onAdd is called when the map's panes are ready and the overlay has been * added to the map. */ onAdd() { this.div = document.createElement("div"); this.div.style.borderStyle = "none"; this.div.style.borderWidth = "0px"; this.div.style.position = "absolute"; // Create the img element and attach it to the div. const img = document.createElement("img"); img.src = this.image; img.style.width = "100%"; img.style.height = "100%"; img.style.position = "absolute"; this.div.appendChild(img); // Add the element to the "overlayLayer" pane. const panes = this.getPanes()!; panes.overlayLayer.appendChild(this.div); }
JavaScript
/** * onAdd is called when the map's panes are ready and the overlay has been * added to the map. */ onAdd() { this.div = document.createElement("div"); this.div.style.borderStyle = "none"; this.div.style.borderWidth = "0px"; this.div.style.position = "absolute"; // Create the img element and attach it to the div. const img = document.createElement("img"); img.src = this.image; img.style.width = "100%"; img.style.height = "100%"; img.style.position = "absolute"; this.div.appendChild(img); // Add the element to the "overlayLayer" pane. const panes = this.getPanes(); panes.overlayLayer.appendChild(this.div); }
رسم التراكب
تجدر الإشارة إلى أننا لم نستدعي أي عرض مرئي خاص في الرمز أعلاه. تستدعي
واجهة برمجة التطبيقات طريقة draw()
منفصلة على التراكب كلما احتاجت إلى رسم
التراكب على الخريطة، بما في ذلك عند إضافته لأول مرة.
وبالتالي، سنطبّق طريقة draw()
هذه ونسترجع
MapCanvasProjection
الخاص بالتراكب باستخدام getProjection()
ونحسب الإحداثيات الدقيقة التي يتم عندها ارتساء نقطتين العنصر العلوي الأيمن والأيسر في العنصر.
بعد ذلك، يمكننا تغيير حجم <div>
. سيؤدي ذلك بدوره إلى تغيير حجم الصورة لتتطابق مع
الحدود التي حدّدناها في أداة إنشاء الصورة المتراكبة.
TypeScript
draw() { // We use the south-west and north-east // coordinates of the overlay to peg it to the correct position and size. // To do this, we need to retrieve the projection from the overlay. const overlayProjection = this.getProjection(); // Retrieve the south-west and north-east coordinates of this overlay // in LatLngs and convert them to pixel coordinates. // We'll use these coordinates to resize the div. const sw = overlayProjection.fromLatLngToDivPixel( this.bounds.getSouthWest() )!; const ne = overlayProjection.fromLatLngToDivPixel( this.bounds.getNorthEast() )!; // Resize the image's div to fit the indicated dimensions. if (this.div) { this.div.style.left = sw.x + "px"; this.div.style.top = ne.y + "px"; this.div.style.width = ne.x - sw.x + "px"; this.div.style.height = sw.y - ne.y + "px"; } }
JavaScript
draw() { // We use the south-west and north-east // coordinates of the overlay to peg it to the correct position and size. // To do this, we need to retrieve the projection from the overlay. const overlayProjection = this.getProjection(); // Retrieve the south-west and north-east coordinates of this overlay // in LatLngs and convert them to pixel coordinates. // We'll use these coordinates to resize the div. const sw = overlayProjection.fromLatLngToDivPixel( this.bounds.getSouthWest(), ); const ne = overlayProjection.fromLatLngToDivPixel( this.bounds.getNorthEast(), ); // Resize the image's div to fit the indicated dimensions. if (this.div) { this.div.style.left = sw.x + "px"; this.div.style.top = ne.y + "px"; this.div.style.width = ne.x - sw.x + "px"; this.div.style.height = sw.y - ne.y + "px"; } }
إزالة تراكب مخصّص
نضيف أيضًا طريقة onRemove()
لإزالة التراكب تمامًا من الخريطة.
TypeScript
/** * The onRemove() method will be called automatically from the API if * we ever set the overlay's map property to 'null'. */ onRemove() { if (this.div) { (this.div.parentNode as HTMLElement).removeChild(this.div); delete this.div; } }
JavaScript
/** * The onRemove() method will be called automatically from the API if * we ever set the overlay's map property to 'null'. */ onRemove() { if (this.div) { this.div.parentNode.removeChild(this.div); delete this.div; } }
إخفاء تراكب مخصّص وعرضه
إذا كنت تريد إخفاء محتوى مركّب أو إظهاره بدلاً من إنشائه أو إزالته،
يمكنك استخدام طريقتَي hide()
وshow()
الخاصتَين لتعديل مستوى ظهور التراكب. بدلاً من ذلك، يمكنك فصل التراكب عن نموذج العناصر في المستند (DOM) للخريطة، على الرغم من أن هذه العملية أكثر تكلفة قليلاً. يُرجى العلم أنّه في حال إعادة إرفاق العنصر المتراكب
بعنصر DOM للخريطة، ستتم إعادة استدعاء طريقة onAdd()
للعنصر المتراكب.
يضيف المثال التالي الطريقتَين hide()
وshow()
إلى ملف نموذج التراكب
الذي يغيّر مستوى رؤية الحاوية <div>
. بالإضافة إلى ذلك، تتم
إضافة طريقة toggleDOM()
التي تُرفق التراكب بالخريطة أو تُزيله منها.
TypeScript
/** * Set the visibility to 'hidden' or 'visible'. */ hide() { if (this.div) { this.div.style.visibility = "hidden"; } } show() { if (this.div) { this.div.style.visibility = "visible"; } } toggle() { if (this.div) { if (this.div.style.visibility === "hidden") { this.show(); } else { this.hide(); } } } toggleDOM(map: google.maps.Map) { if (this.getMap()) { this.setMap(null); } else { this.setMap(map); } }
JavaScript
/** * Set the visibility to 'hidden' or 'visible'. */ hide() { if (this.div) { this.div.style.visibility = "hidden"; } } show() { if (this.div) { this.div.style.visibility = "visible"; } } toggle() { if (this.div) { if (this.div.style.visibility === "hidden") { this.show(); } else { this.hide(); } } } toggleDOM(map) { if (this.getMap()) { this.setMap(null); } else { this.setMap(map); } }
إضافة عناصر تحكّم للأزرار
لتفعيل الطريقتَين toggle
وtoggleDom
، تتم إضافة عناصر التحكّم بالأزرار إلى الخريطة.
TypeScript
const toggleButton = document.createElement("button"); toggleButton.textContent = "Toggle"; toggleButton.classList.add("custom-map-control-button"); const toggleDOMButton = document.createElement("button"); toggleDOMButton.textContent = "Toggle DOM Attachment"; toggleDOMButton.classList.add("custom-map-control-button"); toggleButton.addEventListener("click", () => { overlay.toggle(); }); toggleDOMButton.addEventListener("click", () => { overlay.toggleDOM(map); }); map.controls[google.maps.ControlPosition.TOP_RIGHT].push(toggleDOMButton); map.controls[google.maps.ControlPosition.TOP_RIGHT].push(toggleButton);
JavaScript
const toggleButton = document.createElement("button"); toggleButton.textContent = "Toggle"; toggleButton.classList.add("custom-map-control-button"); const toggleDOMButton = document.createElement("button"); toggleDOMButton.textContent = "Toggle DOM Attachment"; toggleDOMButton.classList.add("custom-map-control-button"); toggleButton.addEventListener("click", () => { overlay.toggle(); }); toggleDOMButton.addEventListener("click", () => { overlay.toggleDOM(map); }); map.controls[google.maps.ControlPosition.TOP_RIGHT].push(toggleDOMButton); map.controls[google.maps.ControlPosition.TOP_RIGHT].push(toggleButton);
إكمال نموذج الرمز
في ما يلي الرمز البرمجي النموذجي الكامل:
TypeScript
// This example adds hide() and show() methods to a custom overlay's prototype. // These methods toggle the visibility of the container <div>. // overlay to or from the map. function initMap(): void { const map = new google.maps.Map( document.getElementById("map") as HTMLElement, { zoom: 11, center: { lat: 62.323907, lng: -150.109291 }, mapTypeId: "satellite", } ); const bounds = new google.maps.LatLngBounds( new google.maps.LatLng(62.281819, -150.287132), new google.maps.LatLng(62.400471, -150.005608) ); // The photograph is courtesy of the U.S. Geological Survey. let image = "https://developers.google.com/maps/documentation/javascript/"; image += "examples/full/images/talkeetna.png"; /** * The custom USGSOverlay object contains the USGS image, * the bounds of the image, and a reference to the map. */ class USGSOverlay extends google.maps.OverlayView { private bounds: google.maps.LatLngBounds; private image: string; private div?: HTMLElement; constructor(bounds: google.maps.LatLngBounds, image: string) { super(); this.bounds = bounds; this.image = image; } /** * onAdd is called when the map's panes are ready and the overlay has been * added to the map. */ onAdd() { this.div = document.createElement("div"); this.div.style.borderStyle = "none"; this.div.style.borderWidth = "0px"; this.div.style.position = "absolute"; // Create the img element and attach it to the div. const img = document.createElement("img"); img.src = this.image; img.style.width = "100%"; img.style.height = "100%"; img.style.position = "absolute"; this.div.appendChild(img); // Add the element to the "overlayLayer" pane. const panes = this.getPanes()!; panes.overlayLayer.appendChild(this.div); } draw() { // We use the south-west and north-east // coordinates of the overlay to peg it to the correct position and size. // To do this, we need to retrieve the projection from the overlay. const overlayProjection = this.getProjection(); // Retrieve the south-west and north-east coordinates of this overlay // in LatLngs and convert them to pixel coordinates. // We'll use these coordinates to resize the div. const sw = overlayProjection.fromLatLngToDivPixel( this.bounds.getSouthWest() )!; const ne = overlayProjection.fromLatLngToDivPixel( this.bounds.getNorthEast() )!; // Resize the image's div to fit the indicated dimensions. if (this.div) { this.div.style.left = sw.x + "px"; this.div.style.top = ne.y + "px"; this.div.style.width = ne.x - sw.x + "px"; this.div.style.height = sw.y - ne.y + "px"; } } /** * The onRemove() method will be called automatically from the API if * we ever set the overlay's map property to 'null'. */ onRemove() { if (this.div) { (this.div.parentNode as HTMLElement).removeChild(this.div); delete this.div; } } /** * Set the visibility to 'hidden' or 'visible'. */ hide() { if (this.div) { this.div.style.visibility = "hidden"; } } show() { if (this.div) { this.div.style.visibility = "visible"; } } toggle() { if (this.div) { if (this.div.style.visibility === "hidden") { this.show(); } else { this.hide(); } } } toggleDOM(map: google.maps.Map) { if (this.getMap()) { this.setMap(null); } else { this.setMap(map); } } } const overlay: USGSOverlay = new USGSOverlay(bounds, image); overlay.setMap(map); const toggleButton = document.createElement("button"); toggleButton.textContent = "Toggle"; toggleButton.classList.add("custom-map-control-button"); const toggleDOMButton = document.createElement("button"); toggleDOMButton.textContent = "Toggle DOM Attachment"; toggleDOMButton.classList.add("custom-map-control-button"); toggleButton.addEventListener("click", () => { overlay.toggle(); }); toggleDOMButton.addEventListener("click", () => { overlay.toggleDOM(map); }); map.controls[google.maps.ControlPosition.TOP_RIGHT].push(toggleDOMButton); map.controls[google.maps.ControlPosition.TOP_RIGHT].push(toggleButton); } declare global { interface Window { initMap: () => void; } } window.initMap = initMap;
JavaScript
// This example adds hide() and show() methods to a custom overlay's prototype. // These methods toggle the visibility of the container <div>. // overlay to or from the map. function initMap() { const map = new google.maps.Map(document.getElementById("map"), { zoom: 11, center: { lat: 62.323907, lng: -150.109291 }, mapTypeId: "satellite", }); const bounds = new google.maps.LatLngBounds( new google.maps.LatLng(62.281819, -150.287132), new google.maps.LatLng(62.400471, -150.005608), ); // The photograph is courtesy of the U.S. Geological Survey. let image = "https://developers.google.com/maps/documentation/javascript/"; image += "examples/full/images/talkeetna.png"; /** * The custom USGSOverlay object contains the USGS image, * the bounds of the image, and a reference to the map. */ class USGSOverlay extends google.maps.OverlayView { bounds; image; div; constructor(bounds, image) { super(); this.bounds = bounds; this.image = image; } /** * onAdd is called when the map's panes are ready and the overlay has been * added to the map. */ onAdd() { this.div = document.createElement("div"); this.div.style.borderStyle = "none"; this.div.style.borderWidth = "0px"; this.div.style.position = "absolute"; // Create the img element and attach it to the div. const img = document.createElement("img"); img.src = this.image; img.style.width = "100%"; img.style.height = "100%"; img.style.position = "absolute"; this.div.appendChild(img); // Add the element to the "overlayLayer" pane. const panes = this.getPanes(); panes.overlayLayer.appendChild(this.div); } draw() { // We use the south-west and north-east // coordinates of the overlay to peg it to the correct position and size. // To do this, we need to retrieve the projection from the overlay. const overlayProjection = this.getProjection(); // Retrieve the south-west and north-east coordinates of this overlay // in LatLngs and convert them to pixel coordinates. // We'll use these coordinates to resize the div. const sw = overlayProjection.fromLatLngToDivPixel( this.bounds.getSouthWest(), ); const ne = overlayProjection.fromLatLngToDivPixel( this.bounds.getNorthEast(), ); // Resize the image's div to fit the indicated dimensions. if (this.div) { this.div.style.left = sw.x + "px"; this.div.style.top = ne.y + "px"; this.div.style.width = ne.x - sw.x + "px"; this.div.style.height = sw.y - ne.y + "px"; } } /** * The onRemove() method will be called automatically from the API if * we ever set the overlay's map property to 'null'. */ onRemove() { if (this.div) { this.div.parentNode.removeChild(this.div); delete this.div; } } /** * Set the visibility to 'hidden' or 'visible'. */ hide() { if (this.div) { this.div.style.visibility = "hidden"; } } show() { if (this.div) { this.div.style.visibility = "visible"; } } toggle() { if (this.div) { if (this.div.style.visibility === "hidden") { this.show(); } else { this.hide(); } } } toggleDOM(map) { if (this.getMap()) { this.setMap(null); } else { this.setMap(map); } } } const overlay = new USGSOverlay(bounds, image); overlay.setMap(map); const toggleButton = document.createElement("button"); toggleButton.textContent = "Toggle"; toggleButton.classList.add("custom-map-control-button"); const toggleDOMButton = document.createElement("button"); toggleDOMButton.textContent = "Toggle DOM Attachment"; toggleDOMButton.classList.add("custom-map-control-button"); toggleButton.addEventListener("click", () => { overlay.toggle(); }); toggleDOMButton.addEventListener("click", () => { overlay.toggleDOM(map); }); map.controls[google.maps.ControlPosition.TOP_RIGHT].push(toggleDOMButton); map.controls[google.maps.ControlPosition.TOP_RIGHT].push(toggleButton); } window.initMap = initMap;
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; } .custom-map-control-button { background-color: #fff; border: 0; border-radius: 2px; box-shadow: 0 1px 4px -1px rgba(0, 0, 0, 0.3); margin: 10px; padding: 0 0.5em; font: 400 18px Roboto, Arial, sans-serif; overflow: hidden; height: 40px; cursor: pointer; } .custom-map-control-button:hover { background: rgb(235, 235, 235); }
HTML
<html> <head> <title>Showing/Hiding Overlays</title> <link rel="stylesheet" type="text/css" href="./style.css" /> <script type="module" src="./index.js"></script> </head> <body> <div id="map"></div> <!-- The `defer` attribute causes the script to execute after the full HTML document has been parsed. For non-blocking uses, avoiding race conditions, and consistent behavior across browsers, consider loading using Promises. See https://developers.google.com/maps/documentation/javascript/load-maps-js-api for more information. --> <script src="https://maps.googleapis.com/maps/api/js?key=AIzaSyB41DRUbKWJHPxaFjMAwdrzWzbVKartNGg&callback=initMap&v=weekly" defer ></script> </body> </html>