Circle для рисования кругов

Класс Circle в Google Maps JavaScript API представляет собой объект для отображения окружностей на карте, где круг определяется центром (latitude/longitude) и радиусом в метрах. Геометрия реализуется в виде геодезической окружности на поверхности Земли, поэтому визуальное представление корректно учитывает кривизну планеты.

Круги используются для визуализации зон покрытия, радиусов поиска, географических ограничений, анализа доступности объектов и построения интерактивных картографических интерфейсов.

Базовая инициализация выполняется через конструктор google.maps.Circle, которому передаётся объект параметров CircleOptions.

const circle = new google.maps.Circle({
  map: map,
  center: { lat: 55.751244, lng: 37.618423 },
  radius: 5000
});

Ключевые свойства:

  • map — карта, на которой отображается окружность
  • center — координаты центра
  • radius — радиус в метрах

Основные параметры CircleOptions

center

Определяет географический центр окружности.

center: { lat: 40.7128, lng: -74.0060 }

Центр может изменяться динамически через метод setCenter().

radius

Радиус окружности задаётся в метрах.

radius: 10000

Радиус можно обновлять методом setRadius().

map

Связывает объект круга с экземпляром карты Google Maps JavaScript API.

map: mapInstance

Если значение null, окружность создаётся, но не отображается.

strokeColor и strokeOpacity

Определяют стиль границы круга.

strokeColor: "#FF0000",
strokeOpacity: 0.8

strokeWeight

Толщина линии границы в пикселях.

strokeWeight: 2

fillColor и fillOpacity

Задают заливку внутренней области окружности.

fillColor: "#FF0000",
fillOpacity: 0.35

draggable и editable

Позволяют пользователю взаимодействовать с кругом:

draggable: true,
editable: true
  • draggable — перемещение центра
  • editable — изменение радиуса и границ

Методы класса Circle

getCenter / setCenter

Получение и изменение центра окружности.

const center = circle.getCenter();

circle.setCenter({ lat: 48.8566, lng: 2.3522 });

getRadius / setRadius

Работа с радиусом.

const radius = circle.getRadius();

circle.setRadius(15000);

getMap / setMap

Управление привязкой к карте.

circle.setMap(null); // скрыть
circle.setMap(map);  // показать

setOptions

Позволяет обновить сразу несколько параметров.

circle.setOptions({
  fillColor: "#00FF00",
  strokeWeight: 3,
  radius: 8000
});

События Circle

Класс поддерживает события, основанные на пользовательском взаимодействии.

click

Срабатывает при клике по окружности.

circle.addListener("click", (event) => {
  console.log("Клик по кругу", event.latLng);
});

radius_changed

Вызывается при изменении радиуса.

circle.addListener("radius_changed", () => {
  console.log(circle.getRadius());
});

center_changed

Срабатывает при изменении центра.

circle.addListener("center_changed", () => {
  console.log(circle.getCenter());
});

drag и dragend

Работают при включённом draggable.

circle.addListener("dragend", () => {
  console.log("Новый центр:", circle.getCenter());
});

Геодезическая природа круга

Circle не является идеальной 2D-геометрией. Внутри Google Maps JavaScript API используется геодезическая проекция:

  • расстояния рассчитываются по поверхности Земли
  • форма корректируется при масштабировании
  • радиус всегда измеряется в метрах, а не в пикселях

Это особенно важно при больших радиусах, где плоская модель дала бы значительные искажения.

Взаимодействие с другими объектами карты

Circle может использоваться совместно с маркерами и информационными окнами.

const marker = new google.maps.Marker({
  position: circle.getCenter(),
  map: map
});

Изменение центра круга может синхронизироваться с маркером:

circle.addListener("center_changed", () => {
  marker.setPosition(circle.getCenter());
});

Проверка попадания точки в круг

Часто требуется определить, находится ли координата внутри окружности.

function isPointInCircle(point, circle) {
  const center = circle.getCenter();
  const radius = circle.getRadius();

  const distance = google.maps.geometry.spherical.computeDistanceBetween(
    new google.maps.LatLng(point),
    center
  );

  return distance <= radius;
}

Для этого используется библиотека geometry, входящая в Google Maps JavaScript API.

Динамическое обновление круга

Круги часто используются в интерфейсах фильтрации данных на карте.

map.addListener("click", (e) => {
  circle.setCenter(e.latLng);
});

Или изменение радиуса через UI:

slider.addEventListener("input", (e) => {
  circle.setRadius(Number(e.target.value));
});

Практика стилизации

Разные сценарии требуют различного визуального оформления:

Зона поиска

fillColor: "#4285F4",
fillOpacity: 0.2,
strokeColor: "#4285F4"

Зона риска

fillColor: "#FF0000",
fillOpacity: 0.25,
strokeWeight: 1

Зона доступности

fillColor: "#00C853",
fillOpacity: 0.15,
strokeColor: "#00C853"

Ограничения и особенности

  • максимальный радиус ограничен практическими пределами производительности
  • при большом количестве кругов снижается FPS рендеринга
  • редактируемые круги создают дополнительные DOM/overlay-слои
  • точность зависит от проекции и масштаба карты

Синхронизация с данными

Circle часто используется как фильтр геоданных:

fetch("/api/places")
  .then(res => res.json())
  .then(points => {
    return points.filter(p =>
      isPointInCircle(p, circle)
    );
  });

Поведение при масштабировании карты

При изменении zoom:

  • визуальный размер круга на экране меняется
  • географический радиус остаётся постоянным
  • центр остаётся фиксированным

Это отличает Circle от экранных overlay-объектов, привязанных к пикселям.

Оглавление