Примеры

Начало работы

Для запуска примера склонируйте проект HelloSDK (./HelloSDK.xcworkspace/) из GitHub-репозитория 2GIS и задайте ваши ключи API в файле ./Example/HelloSDK/HelloVC.swift:

enum Constants {
    static let apiKey = "YOUR_MAPGL_KEY"
    static let directionsApiKey = "YOUR_DIRECTIONS_KEY"
}

Создание виджета карты

Чтобы отобразить карту, сначала добавьте MapView в ваш пользовательский интерфейс. MapView является наследником класса UIView, так что вы можете использовать Storyboards, XIB или создать MapView программно:

let map = MapView(frame: CGRect(x: 0, y: 0, width: 100, height: 100))

Затем инициализируйте виджет: вызовите метод show() и передайте в него свой ключ API. Вы также можете передать начальные координаты и необходимый масштаб. Полный список параметров смотрите в описании API.

Например, приведённый ниже фрагмент кода показывает карту Москвы с Кремлём в центре карты:

map.show(
    apiKey: "Your API key",
    center: CLLocationCoordinate2D(latitude: 55.7516, longitude: 37.6179),
    zoom: 16
)

Для вызова какой-либо функции после инициализации карты напишите trailing closure:

map.show(apiKey: "Your API key") { _ in
    // closure body
}

Добавление маркера

Вы можете добавить на карту любое количество маркеров. Чтобы добавить маркер, создайте экземпляр класса Marker и передайте этот объект в метод add() после инициализации карты. Единственный необходимый параметр - координаты маркера.

map.show(apiKey: "Your API key") { _ in
    let marker = Marker(coordinates: CLLocationCoordinate2D(latitude: 55.7516, longitude: 37.6179))
    map.add(marker)
}

Кроме того, вы можете изменить внешний вид маркера, задав изображение в image (как экземпляр класса UIImage), и якорь (координаты отображения маркера) в anchor. Подробнее о том, как задать якорь, можно прочитать в описании API.

let marker = Marker(
    coordinates: CLLocationCoordinate2D(latitude: 55.7516, longitude: 37.6179),
    image: UIImage(named: "pin")!,
    anchor: .bottom
)

Для переключения видимости маркера используйте методы hide() и show():

marker.hide()
marker.show()

Добавление текстовой метки

Вы можете добавлять на карту текстовые метки. Для этого создайте экземпляр класса Label, задав координаты, текст метки, цвет текста (как экземпляр класса UIColor) и размер шрифта. Затем передайте получившийся объект в метод карты add():

map.show(apiKey: "Your API key") { _ in
    let label = Label(
        center: CLLocationCoordinate2D(latitude: 55.7517, longitude: 37.6179),
        text: "The Kremlin label",
        color: .white,
        fontSize: 14
    )
    map.add(label)
}

Чтобы скрыть метку, используйте метод hide(). Чтобы снова показать её, используйте метод show().

label.hide()
label.show()

Отрисовка пользовательских фигур

Помимо маркеров и текстовых меток вы можете добавлять на карту другие объекты: линии, круги и многоугольники. Для каждой фигуры нужно задать координаты и цвета. Кроме того, вы можете задать Z-координату, чтобы упорядочить фигуры относительно друг друга.

Отрисовка линии

Чтобы нарисовать на карте линию, создайте экземпляр класса Polyline и передайте полученный объект в метод карты add().

Конструктор класса Polyline принимает два типа параметров: координаты точек, лежащих на линии (массив координат CLLocationCoordinate2D), и до трёх объектов класса PolylineStyle для применения стилей к линии.

Проще говоря, линия состоит из под-линий (до трёх штук), наложенных друг на друга. Каждая под-линия настраивается отдельным параметром (style1 для самой верхней под-линии, style2 для средней и style3 для нижней). style2 и style3 можно опустить для отрисовки линии без под-линий.

Код для отрисовки простой линии между двумя точками будет выглядеть примерно так:

let polyline = Polyline(
    points: [
        CLLocationCoordinate2D(latitude: 55.752164, longitude: 37.615487),
        CLLocationCoordinate2D(latitude: 55.751691, longitude: 37.621339)
    ],
    style1: PolylineStyle(color: .blue, width: 5)
)
map.add(polyline)

Код для отрисовки более сложной линии, соединяющей несколько точек и состоящей из трёх под-линий, будет выглядеть примерно так:

let polyline = Polyline(
    points: [
        CLLocationCoordinate2D(latitude: 37.615104, longitude: 55.752375),
        CLLocationCoordinate2D(latitude: 37.618022, longitude: 55.752459),
        CLLocationCoordinate2D(latitude: 37.615189, longitude: 55.750829),
        CLLocationCoordinate2D(latitude: 37.617936, longitude: 55.750865)
    ],
    style1: PolylineStyle(color: .blue, width: 6),
    style2: PolylineStyle(color: .white, width: 10),
    style3: PolylineStyle(color: .black, width: 12)
)
map.add(polyline)

В этом примере под синей линией рисуется белая, а под белой - черная. В результате получается линия с эффектом двойной обводки.

Отрисовка круга

Чтобы нарисовать на карте круг, создайте экземпляр класса Circle и передайте полученный объект в метод карты add().

Конструктор класса Circle принимает несколько параметров. Укажите координаты центра круга и его размер (в метрах), задав параметры center и radius соответственно. Для выбора цвета заливки используйте fillColor, передав экземпляр класса UIColor. Чтобы задать цвет и толщину линии, используйте strokeColor и strokeWidth. Наконец, чтобы задать порядок отрисовки по оси Z, используйте параметр z.

let circle = Circle(
    center: CLLocationCoordinate2D(latitude: 55.7516, longitude: 37.6179),
    radius: 100,
    fillColor: UIColor.blue.withAlphaComponent(0.2),
    strokeColor: .blue,
    strokeWidth: 2,
    z: 5
)
map.add(circle)

Отрисовка многоугольника

Чтобы нарисовать на карте многоугольник, создайте экземпляр класса Polygon и передайте полученный объект в метод карты add().

Конструктор класса Polygon принимает несколько параметров. Для указания координат вершин многоугольника задайте значение параметра points как массив координат CLLocationCoordinate2D. Для выбора цвета заливки используйте fillColor, передав экземпляр класса UIColor. Чтобы задать цвет и толщину линии, используйте strokeColor и strokeWidth. Наконец, чтобы задать порядок по координате Z, используйте параметр z.

let polygon = Polygon(
    points: [
        CLLocationCoordinate2D(latitude: 55.7526, longitude: 37.6179),
        CLLocationCoordinate2D(latitude: 55.7506, longitude: 37.6161),
        CLLocationCoordinate2D(latitude: 55.7506, longitude: 37.6197)
    ],
    fillColor: UIColor.blue.withAlphaComponent(0.2),
    strokeColor: .blue,
    strokeWidth: 2,
    z: 5
)
map.add(polygon)

Обработка событий нажатия

Для получения координат нажатия на карту вы можете добавить для неё click listener:

map.mapClick = { coordinates in
    let latitude = coordinates.latitude
}

Чтобы получить ID объекта, на который произведено нажатие (здание, дорога, маркер, произвольная фигура и т.д.), реализуйте дополнительный метод протокола MapViewDelegate:

func mapView(_ mapView: MapView, didSelectObject object: MapObject) {
    let objectId = object.id
}

После этого вы сможете использовать ID объекта для выделения его на карте (подробнее в разделе Выделение объектов). Этот же ID можно использовать для получения полной информации об объекте через Places API, так как для всех API используется одинаковый ID.

Выделение объектов

Вы можете выделять на карте объекты: здания, дороги и т. д.

Для этого вызовите метод setSelectedObjects() и передайте ему массив ID объектов, которые нужно выделить. Чтобы получить ID объектов, добавьте для карты click listener (подробнее в разделе Обработка событий нажатия).

map.setSelectedObjects(["48231504731808815", "23520539192555249"])

Чтобы изменить список выделенных объектов, вызовите этот метод снова и передайте в него массив новых ID.

Чтобы убрать все выделения с карты, передайте в метод setSelectedObjects() пустой массив:

map.setSelectedObjects([])

Маршруты

Если у вас есть ключ Directions API, вы можете прокладывать маршруты на карте.

Чтобы проложить маршрут, сначала создайте объект класса Directions: вызовите метод makeDirections() и передайте свой ключ:

let directions = map.makeDirections(with: "Your Directions API key")

Затем вызовите метод showCarRoute() и передайте массив с координатами (до 10 точек), чтобы вычислить и отобразить оптимальный маршрут:

directions.showCarRoute(points: [
    CLLocationCoordinate2D(latitude: 55.746069, longitude: 37.622074),
    CLLocationCoordinate2D(latitude: 55.747313, longitude: 37.615573)
])

Чтобы скрыть маршрут, вызовите метод clear():

directions.clear()

Изменение стиля карты

Вы можете изменять стиль карты с помощью метода setStyle (by:). В первом аргументе метода передайте идентификатор стиля карты. По умолчанию используется светлый стиль, которому соответствует идентификатор c080bb6a-8134-4993-93a1-5b4d8c36a59b. В будущем могут быть добавлены новые стили.

Как задать светлую тему (пример):

map.setStyle (by: "c080bb6a-8134-4993-93a1-5b4d8c36a59b")

Как задать тёмную тему (пример):

map.setStyle (by: "e05ac437-fcc2-4845-ad74-b1de9ce07555")

Также можно задать стиль карты при её инициализации (подробнее в разделе Создание виджета карты). Для этого при инициализации карты используйте дополнительный аргумент mapStyleId.