Собственные наложения

1. Введение
2. Добавление собственного наложения
   1. Создание подкласса наложения
   2. Инициализация наложения
   3. Рисование наложения
3. Удаление собственного наложения
4. Скрытие и отображение собственного наложения

Введение

Наложения представляют собой объекты на карте, привязанные к координатам широты и долготы, поэтому они перемещаются при перетаскивании карты или изменении масштаба. Информацию о готовых типах наложений см. в документе Рисование на карте.

Google Maps JavaScript API предоставляет класс OverlayView для создания собственных наложений. Базовый класс OverlayView предоставляет несколько методов, которые необходимо реализовать при создании наложений. Также этот класс предоставляет несколько методов, позволяющих преобразовывать координаты на экране в места на карте, и наоборот.

Добавление собственного наложения

Ниже приведено краткое описание необходимых шагов для создания собственного наложения.

• Установите в качестве прототипа собственного наложения новый экземпляр класса google.maps.OverlayView(). Фактически эта операция создает подкласс класса наложения.
• Создайте конструктор собственного наложения и установите для него любые параметры инициализации.
• Реализуйте в прототипе метод onAdd() и прикрепите наложение к карте. OverlayView.onAdd() вызывается, когда карта готова к прикреплению наложения.
• Реализуйте методdraw() в прототипе для визуального отображения вашего объекта. OverlayView.draw() вызывается при первом отображении объекта.
• Также необходимо реализовать метод onRemove() для очистки всех элементов, добавленных внутри наложения.

Ниже подробно описаны детали каждого шага. Также приведен полноценный работающий пример: Просмотр примера (overlay-simple.html).

Создание подкласса наложения

В примере ниже OverlayView используется для создания простого наложения изображения.

// 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);
}

Теперь мы создаем конструктор для класса USGSOverlay и инициализируем переданные параметры как свойства нового объекта.

/** @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);
}

Это наложение пока нельзя прикрепить к карте в конструкторе наложения. Сначала необходимо убедиться в доступности всех панелей карты, поскольку они указывают порядок отображения объектов на карте. API предоставляет вспомогательный метод, указывающий на добавление наложения на карту. Об этом методе мы расскажем в следующем разделе.

Инициализация наложения

Когда экземпляр наложения создан и готов к отображению, его нужно прикрепить к карте с помощью модели DOM браузера. Чтобы показать, что наложение добавлено к карте, API вызывает его метод onAdd(). Для обработки этого метода мы создаем элемент <div> для хранения изображения, добавляем элемент <img>, прикрепляем его к элементу <div>, а затем прикрепляем наложение к одной из панелей карты. Панель представляет собой узел дерева DOM.

Панели типа MapPanes указывают порядок расположения разных слоев на карте. Доступны следующие панели, которые перечисляются в порядке их размещения снизу вверх:

• mapPane – самая нижняя панель, расположенная поверх листов карты. Не может получать события DOM. (Панель 0).
• overlayLayer – содержит ломаные линии, многоугольники, наземные наложения и наложения мозаичного слоя. Не может получать события DOM. (Панель 1).
• overlayShadow – содержит тени маркера. Не может получать события DOM. (Панель 2).
• overlayImage – содержит изображения маркера на переднем плане. (Панель 3).
• floatShadow – содержит тень информационного окна. Находится над панелью overlayImage, поэтому маркеры могут находиться в тени информационного окна. (Панель 4).
• overlayMouseTarget – содержит элементы, получающие события мыши DOM, например, прозрачные цели для маркеров. Находится над панелью floatShadow, поэтому маркеры в тени информационного окна могут реагировать на нажатия. (Панель 5).
• floatPane – содержит информационное окно. Располагается поверх всех наложений карты. (Панель 6).

Поскольку наше изображение представляет собой наземное наложение, мы используем панель overlayLayer . Когда эта панель становится доступной, мы прикрепляем к ней объект в качестве дочернего элемента.

/**
 * 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);
};

Рисование наложения

Следует отметить, что в приведенном выше фрагменте кода не запускается отображение никаких специальных визуальных элементов. Чтобы нарисовать наложение на карте, API вызывает для него отдельный метод draw(), в том числе при его первом добавлении.

Поэтому мы реализуем метод draw(), получаем для наложения объект MapCanvasProjection с помощью метода getProjection() и рассчитываем точные координаты, к которым будут прикреплены верхняя правая и нижняя левая точки объекта. После этого мы можем изменить размер элемента <div>. При этом размер изображения изменится в соответствии с границами, указанными в конструкторе наложения.

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';
};

Удаление собственного наложения

Мы также добавляем метод onRemove() для полного удаления наложения с карты.

// 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;
};

Скрытие и отображение собственного наложения

Если вы хотите скрыть или показать наложение, а не просто создать или удалить его, вы можете реализовать собственные методы hide() и show() для управления видимостью наложения. Также вы можете отсоединить наложение от модели DOM карты, хотя эта операция несколько сложнее. Следует учесть, что если вы заново прикрепите наложение к модели DOM карты, метод onAdd() этого наложения запустится заново.

В следующем примере к прототипу наложения добавлены методы hide() и show(), которые управляют отображением контейнера <div>. Кроме того, мы добавляем метод toggleDOM(), который прикрепляет наложение к карте или отсоединяет его от карты.

// 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_);
  }
};

Оформление пользовательского интерфейса:

<!-- 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>

Просмотр примера (overlay-hideshow.html).