API карт

Базовые типы данных

В данном разделе описаны классы базовых типов данных, которые часто встречаются на страницах руководства API карт и которые необходимы для работы с многими объектами карты.

DG.LatLng
DG.LatLngBounds
- Создание
- Методы
DG.Point
DG.Bounds

DG.LatLng

Географическая точка с определенной широтой и долготой.

var latlng = DG.latLng(54.98, 82.89);

Все методы, которые принимают объекты LatLng, также принимают широту и долготу в виде простого массива или объекта (если не указано иное), то есть данные записи эквивалентны:

map.panTo([54.98, 82.89]);
map.panTo({lon: 82.89, lat: 54.98});
map.panTo({lat: 54.98, lng: 82.89});
map.panTo(DG.latLng(54.98, 82.89));

Создание

Конструктор	Описание
`DG.latLng( <Number> latitude, <Number> longitude, <Number> altitude? )`	Создает объект, представляющий географическую точку с определенной широтой и долготой (и опционально высотой).
`DG.latLng( <Array> coords )`	Ожидает массив вида `[Number, Number]` или `[Number, Number, Number]` в качестве аргумента.
`DG.latLng( <Object> coords )`	Ожидает объект вида `{lat: Number, lng: Number}` или `{lat: Number, lng: Number, alt: Number}` в качестве аргумента.

Методы

Метод	Возвращает	Описание
`equals( <LatLng> otherLatLng, <Number> maxMargin? )`	`Boolean`	Возвращает `true`, если переданная широта и долгота находится в той же позиции (с небольшой погрешностью). Погрешность, используемую по умолчанию, можно изменить передав аргумент `maxMargin`.
`toString()`	`String`	Возвращает строковое представление позиции (удобно при отладке).
`distanceTo( <LatLng> otherLatLng )`	`Number`	Возвращает расстояние (в метрах) до переданной широты и долготы, рассчитанное по формуле Haversine.
`wrap()`	`LatLng`	Возвращает новый объект `LatLng`, в котором долгота нормализуется в диапазон от -180 до 180 градусов.
`toBounds( <Number> sizeInMeters )`	`LatLngBounds`	Возвращает новый объект, `LatLngBounds` в котором каждая из границ отстоит от указанной точки на `sizeInMeters` метров.

Свойства

Свойство	Тип	Описание
`lat`	`Number`	Широта в градусах.
`lng`	`Number`	Долгота в градусах.
`alt`	`Number`	Высота в метрах (опционально).

DG.LatLngBounds

Описывает прямоугольную географическую область на карте.

var southWest = DG.latLng(54.9801, 82.8974),
    northEast = DG.latLng(54.9901, 82.9074),
    bounds = DG.latLngBounds(southWest, northEast);

Все методы, которые принимают объекты LatLngBounds также принимают их в виде простого массива (если не указано иное), то есть границы могут быть указаны, как в этом примере:

map.fitBounds([
    [54.9801, 82.8974],
    [54.9901, 82.9074]
]);

Создание

Конструктор	Описание
`DG.latLngBounds( <LatLng> southWest, <LatLng> northEast )`	Создает объект `LatLngBounds`, определяя юго-западный и северо-восточный углы прямоугольника.
`DG.latLngBounds( <LatLng[]> latlngs)`	Создает объект `LatLngBounds` на основе географических точек, которые находятся внутри описываемой области. Удобно использовать, если необходимо подстроить центр и масштаб карты с помощью метода fitBounds.

Методы

Метод	Возвращает	Описание
`extend( <LatLng> latlng )`	`this`	Расширяет область таким образом, чтобы в них входила переданная точка.
`extend( <LatLngBounds> otherBounds )`	`this`	Расширяет область таким образом, чтобы в них входили переданные границы другой области.
`pad( <Number> bufferRatio )`	`LatLngBounds`	Возвращает бо́льшую область, увеличенную на заданный процент в каждом из направлений.
`getCenter()`	`LatLng`	Возвращает центральную точку области.
`getSouthWest()`	`LatLng`	Возвращает крайнюю юго-западную точку области.
`getNorthEast()`	`LatLng`	Возвращает крайнюю северо-восточную точку области.
`getNorthWest()`	`LatLng`	Возвращает крайнюю северо-западную точку области.
`getSouthEast()`	`LatLng`	Возвращает крайнюю юго-восточную точку области.
`getWest()`	`Number`	Возвращает западную границу (долготу) области.
`getSouth()`	`Number`	Возвращает южную границу (широту) области.
`getEast()`	`Number`	Возвращает восточную границу (долготу) области.
`getNorth()`	`Number`	Возвращает северную границу (широту) области.
`contains( <LatLngBounds> otherBounds )`	`Boolean`	Возвращает `true`, если область содержит переданные границы.
`contains( <LatLng> latlng )`	`Boolean`	Возвращает `true`, если область содержит переданную точку.
`intersects( <LatLngBounds> otherBounds )`	`Boolean`	Возвращает `true`, если границы области пересекают переданные границы хотя бы в одной точке.
`overlaps( <Bounds> otherBounds )`	`Boolean`	Возвращает `true`, если границы области перекрывают переданные границы в некотором пространстве.
`toBBoxString()`	`String`	Возвращает строку с координатами границ в формате `'southwest_lng,southwest_lat,northeast_lng,northeast_lat'`. Удобно использовать для отправки запросов к веб-сервисам, возвращающим геоданные.
`equals( <LatLngBounds> otherBounds )`	`Boolean`	Возвращает `true`, если координаты текущей прямоугольной области эквивалентны переданным (с небольшой погрешностью).
`isValid()`	`Boolean`	Возвращает `true`, если свойства объекта (данные границ) инициализированы должным образом.

DG.Point

Точка с пиксельными координатами x и y.

var point = DG.point(200, 300);

Все методы, которые принимают объекты Point, также принимают координаты в виде простого массива (если не указано иное), то есть данные записи эквивалентны:

map.panBy([200, 300]);
map.panBy(DG.point(200, 300));

Создание

Конструктор	Описание
`DG.point( <Number> x, <Number> y, <Boolean> round? )`	Создает объект Point с заданными координатами `x` и `y`, при необходимости округляя значения (если `round` установлен в `true`).
`DG.point( <Number[]> coords)`	Ожидает массив вида `[x, y]`.

Методы

Метод	Возвращает	Описание
`clone()`	`Point`	Возвращает копию оригинального объекта.
`add( <Point> otherPoint )`	`Point`	Возвращает результат сложения координат заданной точки и текущей.
`subtract( <Point> otherPoint )`	`Point`	Возвращает результат вычитания координат заданной точки из текущей.
`divideBy( <Number> num )`	`Point`	Возвращает результат деления координат текущей точки на произвольное число.
`multiplyBy( <Number> num )`	`Point`	Возвращает результат умножения координат текущей точки на произвольное число.
`scaleBy( <Point> scale )`	`Point`	Возвращает новую точку, каждая координата которой получена умножением на соответствующую координату `scale`. В терминах линейной алгебры, данная операция производит умножение на матрицу масштабирования, заданную `scale`.
`unscaleBy( <Point> scale )`	`Point`	Обратная операция, относительно `scaleBy`.
`round()`	`Point`	Возвращает копию оригинального объекта с округленными координатами.
`floor()`	`Point`	Возвращает копию оригинального объекта с координатами, округленными вниз.
`ceil()`	`Point`	Возвращает копию оригинального объекта с координатами, округленными вверх.
`distanceTo( <Point> otherPoint )`	`Number`	Возвращает декартово расстояние между текущй и заданной точками.
`equals( <Point> otherPoint )`	`Boolean`	Возвращает `true`, если заданная точка имеет аналогичные координаты.
`contains( <Point> otherPoint )`	`Boolean`	Возвращает `true`, если обе координаты заданной точки меньше (в абсолютных величинах) координат текущей точки.
`toString()`	`String`	Возвращает строковое представление точки (удобно для отладки).

Свойства

Свойство	Тип	Описание
`x`	`Number`	Координата x.
`y`	`Number`	Координата y.

DG.Bounds

Описывает прямоугольную область на карте в пиксельных координатах.

var p1 = DG.point(10, 10),
    p2 = DG.point(40, 60),
    bounds = DG.bounds(p1, p2);

Все методы, которые принимают объекты Point также принимают их в виде простого массива (если не указано иное), то есть границы могут быть указаны, как в этом примере:

otherBounds.intersects([[10, 10], [40, 60]]);

Создание

Конструктор	Описание
`DG.bounds( <Point> topLeft, <Point> bottomRight )`	Создает объект Bounds на основе переданных координат (обычно, координат левого-верхнего и правого-нижнего углов).
`DG.bounds( <Point[]> points )`	Создает объект Bounds на основе массива координат переданных точек.

Методы

Метод	Возвращает	Описание
`extend( <Point> point )`	`this`	Расширяет область таким образом, чтобы в нее входила переданная точка.
`getCenter( <Boolean> round? )`	`Point`	Возвращает центральную точку области.
`getBottomLeft()`	`Point`	Возвращает координаты левого-нижнего угла области.
`getTopRight()`	`Point`	Возвращает координаты правого-верхнего угла области.
`getSize()`	`Point`	Возвращает размер области.
`contains( <Bounds> otherBounds )`	`Boolean`	Возвращает `true`, если область содержит переданные границы.
`contains( <Point> point )`	`Boolean`	Возвращает `true`, если область содержит переданную точку.
`intersects( <Bounds> otherBounds )`	`Boolean`	Возвращает `true`, если границы области пересекают переданные границы хотя бы в одной точке.
`overlaps( <Bounds> otherBounds )`	`Boolean`	Возвращает `true`, если границы области перекрывают переданные границы в некотором пространстве.

Свойства

Свойство	Тип	Описание
`min`	`Point`	Левый верхний угол прямоугольной области.
`max`	`Point`	Правый нижний угол прямоугольной области.