Benutzerdefinierte Überlagerungen

1. Einführung
2. Benutzerdefinierte Überlagerung hinzufügen
   1. Überlagerungsunterklassen erstellen
   2. Überlagerung initialisieren
   3. Überlagerung ziehen
3. Benutzerdefinierte Überlagerung entfernen
4. Benutzerdefinierte Überlagerung ein- und ausblenden

Einführung

Überlagerungen sind Objekte auf einer Karte, die an Breiten-/Längenkoordinaten gebunden sind, so dass sie beim Ziehen oder Vergrößern der Karte verschoben werden. Informationen zu vordefinierten Überlagerungstypen finden Sie im Eintrag Auf Karten zeichnen.

In Google Maps JavaScript API wird eine Klasse OverlayView bereitgestellt, mit der Sie Ihre eigenen Überlagerungen erstellen können. Die Klasse OverlayView ist eine Basisklasse, die mehrere Methoden bereitstellt, die Sie beim Erstellen Ihrer Überlagerungen implementieren müssen. Die Klasse umfasst auch einige Methoden, die eine Übersetzung zwischen Bildschirmkoordinaten und Standorten auf der Karte ermöglichen.

Benutzerdefinierte Überlagerung hinzufügen

Nachfolgend sind die Schritte zusammengefasst, die zum Erstellen einer benutzerdefinierten Überlagerung erforderlich sind:

• Definieren Sie den prototype Ihres benutzerdefinierten Überlagerungsobjekts als neue Instanz von google.maps.OverlayView(). Auf diese Weise werden Unterklassen für die Überlagerungsklasse erstellt.
• Erstellen Sie einen Konstruktor für Ihre benutzerdefinierte Überlagerung, und definieren Sie beliebige Initialisierungsparameter.
• Implementieren Sie in Ihrem Prototyp eine Methode onAdd(), und fügen Sie die Überlagerung zur Karte hinzu. OverlayView.onAdd() wird aufgerufen, sobald das Anfügen der Überlagerung an die Karte möglich ist.
• Implementieren Sie eine Methode draw() in Ihren Prototyp, und bearbeiten Sie die visuelle Anzeige Ihres Objekts. OverlayView.draw() wird beim ersten Anzeigen des Objekts aufgerufen.
• Außerdem sollten Sie eine Methode onRemove() implementieren, um jegliche Elemente zu bereinigen, die Sie in die Überlagerung eingefügt haben.

Nachfolgend werden die einzelnen Schritte im Einzelnen erläutert. Außerdem können Sie das vollständige, funktionierende Beispiel aufrufen: Beispiel anzeigen (overlay-simple.html).

Überlagerungsunterklassen erstellen

In diesem Beispiel wird OverlayView verwendet, um eine einfache Bildüberlagerung zu erstellen.

// This example creates a custom overlay called USGSOverlay, containing
// a U.S. Geological Survey (USGS) image of the relevant area on the map.

// Set the custom overlay object's prototype to a new instance
// of OverlayView. In effect, this will subclass the overlay class therefore
// it's simpler to load the API synchronously, using
// google.maps.event.addDomListener().
// Note that we set the prototype to an instance, rather than the
// parent class itself, because we do not wish to modify the parent class.

var overlay;
USGSOverlay.prototype = new google.maps.OverlayView();

// Initialize the map and the custom overlay.

function initMap() {
  var map = new google.maps.Map(document.getElementById('map'), {
    zoom: 11,
    center: {lat: 62.323907, lng: -150.109291},
    mapTypeId: 'satellite'
  });

  var 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.
  var srcImage = 'https://developers.google.com/maps/documentation/' +
      'javascript/examples/full/images/talkeetna.png';

  // The custom USGSOverlay object contains the USGS image,
  // the bounds of the image, and a reference to the map.
  overlay = new USGSOverlay(bounds, srcImage, map);
}

Jetzt erstellen wir einen Konstruktor für die Klasse USGSOverlay und initialisieren die übergebenen Parameter als Eigenschaften des neuen Objekts.

/** @constructor */
function USGSOverlay(bounds, image, map) {

  // Initialize all properties.
  this.bounds_ = bounds;
  this.image_ = image;
  this.map_ = map;

  // Define a property to hold the image's div. We'll
  // actually create this div upon receipt of the onAdd()
  // method so we'll leave it null for now.
  this.div_ = null;

  // Explicitly call setMap on this overlay.
  this.setMap(map);
}

Wir können diese Überlagerung jedoch noch nicht zur Karte im Konstruktor der Überlagerung hinzufügen. Zuvor müssen wir sicherstellen, dass alle Kartenbereiche verfügbar sind, da diese die Reihenfolge vorgeben, in der die Objekte auf der Karte angezeigt werden. In der API wird dies durch eine Hilfsmethode angegeben. Diese Methode wird im nächsten Abschnitt behandelt.

Überlagerung initialisieren

Wenn die Überlagerung zum ersten Mal instanziiert wurde und angezeigt werden kann, müssen wie sie über das DOM des Browsers zur Karte hinzufügen. In der API wird angegeben, dass die Überlagerung zur Karte hinzugefügt wurde, indem die Methode onAdd() der Überlagerung aufgerufen wird. Um diese Methode zu bearbeiten, erstellen wir ein Element <div>, das unser Bild enthalten soll, fügen ein Element <img> hinzu, fügen es in das Element <div> ein und fügen dann die Überlagerungen in einen der Bereiche der Karte ein. Ein Bereich ist ein Knoten in der DOM-Baumstruktur.

Die Bereiche vom Typ MapPanes geben die Stapelreihenfolge für verschiedene Ebenen der Karte vor. Folgende Bereiche sind verfügbar; sie sind in der Reihenfolge ihrer Stapelung von unten nach oben sortiert:

• mapPane ist der unterste Bereich, der über den Kacheln liegt. In diesem Bereich können keine DOM-Ereignisse empfangen werden. (Bereich 0).
• overlayLayer enthält Polylinien, Polygone, Geländeüberlagerungen und Kachelüberlagerungen. In diesem Bereich können keine DOM-Ereignisse empfangen werden. (Bereich 1).
• overlayShadow enthält die Schattierungen der Marker. In diesem Bereich können keine DOM-Ereignisse empfangen werden. (Bereich 2).
• overlayImage enthält die Vordergrundbilder der Marker. (Bereich 3).
• floatShadow enthält die Schattierung der Info-Fenster. Diese Überlagerung liegt über overlayImage, sodass Marker in der Schattierung des Info-Fensters liegen können. (Bereich 4).
• overlayMouseTarget enthält Elemente, die DOM-Mausereignisse empfangen, z. B. transparente Ziele für Marker. Diese Überlagerung liegt über floatShadow, sodass Marker innerhalb der Schattierung des Info-Fensters klickbar sein können. (Bereich 5).
• floatPane enthält das Info-Fenster. Diese Überlagerung liegt über allen Kartenüberlagerungen. (Bereich 6).

Da es sich bei unserem Bild um eine „Geländeüberlagerung“ handelt, verwenden wir den Bereich overlayLayer. Wenn wir diesen Bereich haben, fügen wir unser Objekt als untergeordnetes Element ein.

/**
 * onAdd is called when the map's panes are ready and the overlay has been
 * added to the map.
 */
USGSOverlay.prototype.onAdd = function() {

  var div = document.createElement('div');
  div.style.borderStyle = 'none';
  div.style.borderWidth = '0px';
  div.style.position = 'absolute';

  // Create the img element and attach it to the div.
  var img = document.createElement('img');
  img.src = this.image_;
  img.style.width = '100%';
  img.style.height = '100%';
  img.style.position = 'absolute';
  div.appendChild(img);

  this.div_ = div;

  // Add the element to the "overlayLayer" pane.
  var panes = this.getPanes();
  panes.overlayLayer.appendChild(div);
};

Überlagerung ziehen

Beachten Sie, dass wir im obigen Code keine spezielle visuelle Darstellung definiert haben. In der API wird jedes Mal eine separate Methode draw() zur Überlagerung aufgerufen, wenn es erforderlich ist, die Überlagerung auf der Karte zu ziehen, auch beim ersten Hinzufügen.

Aus diesem Grund implementieren wir diese Methode draw(), rufen MapCanvasProjection der Überlagerung mithilfe von getProjection() auf und berechnen die exakten Koordinaten, an denen die oberen rechten und unteren linken Punkte des Objekts verankert werden sollen. Anschließend können wir die Größe von <div> verändern. Entsprechend verändern wir die Größe des Bildes, damit sie den Grenzen entspricht, die wir im Konstruktor der Überlagerung definiert haben.

USGSOverlay.prototype.draw = function() {

  // 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.
  var 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.
  var sw = overlayProjection.fromLatLngToDivPixel(this.bounds_.getSouthWest());
  var ne = overlayProjection.fromLatLngToDivPixel(this.bounds_.getNorthEast());

  // Resize the image's div to fit the indicated dimensions.
  var div = this.div_;
  div.style.left = sw.x + 'px';
  div.style.top = ne.y + 'px';
  div.style.width = (ne.x - sw.x) + 'px';
  div.style.height = (sw.y - ne.y) + 'px';
};

Benutzerdefinierte Überlagerung entfernen

Wir können auch eine Methode onRemove() hinzufügen, um die Überlagerung fehlerfrei aus der Karte entfernen können.

// The onRemove() method will be called automatically from the API if
// we ever set the overlay's map property to 'null'.
USGSOverlay.prototype.onRemove = function() {
  this.div_.parentNode.removeChild(this.div_);
  this.div_ = null;
};

Benutzerdefinierte Überlagerung ein- und ausblenden

Wenn Sie eine Überlagerung ein- oder ausblenden möchten, statt sie einfach zu erstellen oder zu entfernen, können Sie Ihre eigenen Methoden hide() und show() implementieren, um die Sichtbarkeit der Überlagerung anzupassen. Alternativ können Sie die Überlagerung vom DOM der Karte entfernen; diese Vorgehensweise ist jedoch etwas aufwändiger. Hinweis: Wenn Sie die Überlagerung anschließend wieder zum DOM der Karte hinzufügen, wird die Methode onAdd() der Überlagerung erneut aufgerufen..

Im nachfolgenden Beispiel werden die Methoden hide() und show() zum Prototyp der Überlagerung hinzugefügt, mit denen zwischen Ein- und Ausblenden des Containers <div> gewechselt wird. Zusätzlich fügen wir eine Methode toggleDOM() hinzu, mit der die Überlagerung zur Karte hinzugefügt bzw. daraus entfernt wird.

// Set the visibility to 'hidden' or 'visible'.
USGSOverlay.prototype.hide = function() {
  if (this.div_) {
    // The visibility property must be a string enclosed in quotes.
    this.div_.style.visibility = 'hidden';
  }
};

USGSOverlay.prototype.show = function() {
  if (this.div_) {
    this.div_.style.visibility = 'visible';
  }
};

USGSOverlay.prototype.toggle = function() {
  if (this.div_) {
    if (this.div_.style.visibility === 'hidden') {
      this.show();
    } else {
      this.hide();
    }
  }
};

// Detach the map from the DOM via toggleDOM().
// Note that if we later reattach the map, it will be visible again,
// because the containing <div> is recreated in the overlay's onAdd() method.
USGSOverlay.prototype.toggleDOM = function() {
  if (this.getMap()) {
    // Note: setMap(null) calls OverlayView.onRemove()
    this.setMap(null);
  } else {
    this.setMap(this.map_);
  }
};

Achten Sie auf die Benutzeroberfläche:

<!-- Add an input button to initiate the toggle method on the overlay. -->
    <div id="floating-panel">
      <input type="button" value="Toggle visibility" onclick="overlay.toggle();"></input>
      <input type="button" value="Toggle DOM attachment" onclick="overlay.toggleDOM();"></input>
    </div>

Beispiel anzeigen (overlay-hideshow.html).