Тип QML Map

Тип Map отображает карту. Подробнее...

• Список всех членов, включая наследуемые члены

Свойства

• activeMapType : MapType
• bearing : real
• center : coordinate
• color : color
• copyrightsVisible : bool
• error : перечисление
• errorString : string
• fieldOfView : real
• gesture : MapGestureArea
• mapItems : list<MapItem>
• mapParameters : list<MapParameters>
• mapReady : bool
• maximumFieldOfView : real
• maximumTilt : real
• maximumZoomLevel : real
• minimumFieldOfView : real
• minimumTilt : real
• minimumZoomLevel : real
• plugin : Plugin
• supportedMapTypes : list<MapType>
• tilt : real
• visibleArea : rect
• visibleRegion : geoshape
• zoomLevel : real

Сигналы

• copyrightLinkActivated(link)

Методы

• void addMapItem(item)
• void addMapItemGroup(itemGroup)
• void addMapItemView(itemView)
• void addMapParameter(parameter)
• void alignCoordinateToPoint(coordinate, QPointF point)
• void clearData()
• void clearMapItems()
• void clearMapParameters()
• void fitViewportToGeoShape(geoShape, margins)
• void fitViewportToMapItems()
• void fitViewportToVisibleMapItems()
• point fromCoordinate(coordinate, bool clipToViewPort)
• void pan(dx, int dy)
• void prefetchData()
• void removeMapItem(item)
• void removeMapItemGroup(itemGroup)
• void removeMapItemView(itemView)
• void removeMapParameter(parameter)
• void setBearing(bearing, coordinate coordinate)
• coordinate toCoordinate(position, bool clipToViewPort)

Подробное описание

Тип Map используется для отображения карты или изображения Земли с возможностью отображения интерактивных объектов, связанных с поверхностью карты.

Существует множество способов визуализации поверхности Земли в двумерном виде, но все они предполагают некоторую проекцию: математическую зависимость между 3D координатами (широта, долгота и высота) и 2D координатами (X и Y в пикселях) на экране.

Разные источники данных карт могут использовать разные проекции, и с точки зрения типа Map мы рассматриваем их как один заменяемый блок: плагин карты. Плагин карты состоит из источника данных, а также всех других деталей, необходимых для отображения его данных на экране.

Текущий используемый плагин карты содержится в свойстве plugin элемента Map. Для отображения любого изображения в элементе Map необходимо установить это свойство. См. тип Plugin для описания того, как получить соответствующий плагин для использования.

Географическая область, отображаемая в элементе Map, называется его видимой областью, и она определяется свойствами center и zoomLevel. Свойство center содержит coordinate, определяющий центр области просмотра, а свойство zoomLevel управляет масштабом карты. См. каждое из этих свойств для получения дополнительной информации об их значениях.

При отображении карты каждая видимая географическая координата будет отображаться в виде координат X и Y пикселей на экране. Для преобразования между ними Map предоставляет функции toCoordinate и fromCoordinate, которые являются полезными во многих случаях.

Объекты карты

Объекты, относящиеся к карте, могут быть объявлены в теле объекта Map в Qt Quick и автоматически появятся на карте. Чтобы добавить объект программно, сначала убедитесь, что он создан с Map в качестве родительского элемента (например, в аргументе Component::createObject). Затем вызовите метод addMapItem на карте, если тип этого объекта — один из MapCircle, MapRectangle, MapPolyline, MapPolygon, MapRoute или MapQuickItem. Существует соответствующий метод removeMapItem для выполнения обратного действия и удаления любых вышеперечисленных типов объектов карты с карты.

Перемещение объектов карты, изменение их размера или формы обычно не требует специального взаимодействия с самой картой — изменение этих свойств в объекте карты автоматически обновит отображение.

Взаимодействие

Тип Map поддерживает жесты pinch и flick для управления масштабированием и перемещением. Они включены по умолчанию и доступны в любое время с помощью объекта gesture. Фактическая GestureArea строится специально при запуске и не может быть заменена или уничтожена. Однако ее свойства можно изменить для управления ее поведением.

Производительность

Карты рендерируются с помощью OpenGL (ES) и стека Qt Scene Graph, и поэтому показывают хорошую производительность, где доступно аппаратное ускорение GL.

Для «онлайн» плагинов карты пропускная способность сети и задержка могут значительно влиять на восприятие пользователем производительности. Для минимизации этого выполняется значительный кеширование, но оно не всегда идеально. Для «офлайн» плагинов время, затрачиваемое на извлечение хранящихся географических данных и рендеринг основных элементов карты, часто играет доминирующую роль. Некоторые офлайн-плагины могут использовать аппаратное ускорение сами, чтобы (частично) предотвратить это.

В целом, большие и сложные элементы карты, такие как многоугольники и полилинии с большим количеством вершин, могут негативно влиять на производительность пользовательского интерфейса. Более подробные сведения об этом приведены в документации для каждого типа элементов карты.

Пример использования

Следующий фрагмент кода демонстрирует простую карту и необходимый тип Plugin для ее использования. Карта центрирована на Осло, Норвегия, со значением масштаба 14.

import QtQuick 2.0
import QtQuick.Window 2.14
import QtLocation 5.6
import QtPositioning 5.6

Window {
    width: Qt.platform.os == "android" ? Screen.width : 512
    height: Qt.platform.os == "android" ? Screen.height : 512
    visible: true

    Plugin {
        id: mapPlugin
        name: "osm" // "mapboxgl", "esri", ...
        // specify plugin parameters if necessary
        // PluginParameter {
        //     name:
        //     value:
        // }
    }

    Map {
        anchors.fill: parent
        plugin: mapPlugin
        center: QtPositioning.coordinate(59.91, 10.75) // Oslo
        zoomLevel: 14
    }
}

Документация свойств

activeMapType : MapType

Доступ к текущему активному типу карты.

Это свойство можно установить для изменения активного типа карты. Возможные значения см. в свойстве supportedMapTypes.

См. также MapType.

bearing : real

Это свойство содержит азимут для карты. Значение по умолчанию — 0. Если используемый для карты плагин поддерживает азимут, допустимый диапазон значений находится между 0 и 360. Если используемый для карты плагин не поддерживает азимут, изменение этого свойства не повлияет на отображение.

Это свойство было введено в QtLocation 5.9.

center : координата

Это свойство содержит координату, которая занимает центр области отображения карты. Некорректные координаты центра игнорируются.

Значение по умолчанию — произвольная допустимая координата.

color : цвет

Это свойство содержит цвет фона элемента карты.

Это свойство было добавлено в Qt 5.6.

copyrightsVisible : bool

Это свойство определяет видимость уведомления об авторских правах. Уведомление обычно отображается в левом нижнем углу. По умолчанию это свойство установлено в true.

Примечание: Многие поставщики карт требуют видимости уведомления как части условий использования. Перед отключением этого уведомления, пожалуйста, обратитесь к документации соответствующего поставщика.

Это свойство было добавлено в Qt 5.7.

error : перечисление

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

• Map.NoError - Ошибка отсутствует.
• Map.NotSupportedError - Свойство плагина карт не установлено или с плагином не связан менеджер отображения.
• Map.UnknownParameterError - Плагин не распознал один из переданных параметров.
• Map.MissingRequiredParameterError - Плагин не нашёл один из ожидаемых параметров.
• Map.ConnectionError - Плагин не смог подключиться к своему сервису или базе данных.

См. также QGeoServiceProvider::Error.

errorString : строка

Это свойство только для чтения, содержащее текстовое представление последней ошибки поставщика карт. Если ошибки нет, возвращается пустая строка.

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

См. также QGeoServiceProvider::errorString().

fieldOfView : вещественное

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

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

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

Это свойство было добавлено в QtLocation 5.9.

См. также minimumFieldOfView и maximumFieldOfView.

gesture : MapGestureArea

Содержит MapGestureArea, созданную с помощью Map. Это охватывает жесты перемещения, свайпа и масштабирования. Используйте gesture.enabled: true для включения основных жестов, или см. MapGestureArea для получения дополнительной информации.

mapItems : список<MapItem>

Возвращает список всех элементов карты в произвольном порядке. Эти элементы включают элементы, которые были объявлены статически как часть объявления типа, а также динамические элементы (addMapItem, MapItemView).

См. также addMapItem, removeMapItem и clearMapItems.

mapParameters : список<MapParameters>

Возвращает список всех параметров карты в произвольном порядке. Эти элементы включают параметры карты, которые были объявлены статически как часть объявления типа, а также динамические параметры карты (addMapParameter).

Выпуск этого API с Qt 5.9 — предварительный просмотр технологии.

Это свойство было добавлено в Qt 5.9.

См. также MapParameter, addMapParameter, removeMapParameter и clearMapParameters.

mapReady : bool

Это свойство указывает, была ли карта успешно инициализирована и готова к использованию. Некоторые методы, такие как fromCoordinate и toCoordinate, не будут работать до готовности карты. Из-за архитектуры Map рекомендуется использовать сигнал, испускаемый для этого свойства, вместо Component.onCompleted, чтобы убедиться, что всё работает как ожидается.

Это свойство было добавлено в Qt 5.9.

maximumFieldOfView : вещественное

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

Минимальное поле зрения наклона, заданное используемым плагином, является верхней границей для этого свойства. Если свойство плагина не установлено или плагин не поддерживает отображение, это свойство — 179.

Это свойство было добавлено в QtLocation 5.9.

См. также fieldOfView и minimumFieldOfView.

maximumTilt : вещественное

Это свойство содержит максимальное допустимое наклонение карты в градусах.

Максимальный угол наклона, определённый используемым плагином, является верхней границей для этого свойства. Если свойство плагина не установлено или плагин не поддерживает отображение, это свойство — 89.5.

Начиная с QtLocation 5.12, плагины могут дополнительно ограничивать это значение в зависимости от текущего уровня масштабирования.

Это свойство было добавлено в QtLocation 5.9.

См. также tilt и minimumTilt.

maximumZoomLevel : вещественное

Это свойство содержит максимальный допустимый уровень масштабирования карты.

Максимальный уровень масштабирования определяется используемым плагином. Если свойство плагина не установлено или плагин не поддерживает отображение, это свойство — 30.

minimumFieldOfView : вещественное

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

Минимальное поле зрения наклона, заданное используемым плагином, является нижней границей для этого свойства. Если свойство плагина не установлено или плагин не поддерживает отображение, это свойство — 1.

Это свойство было добавлено в QtLocation 5.9.

См. также fieldOfView и maximumFieldOfView.

minimumTilt : вещественное

Это свойство содержит минимальный допустимый угол наклона карты в градусах.

Минимальный угол наклона, определённый используемым плагином, является нижней границей для этого свойства. Если свойство плагина не установлено или плагин не поддерживает отображение, это свойство — 0.

Начиная с QtLocation 5.12, плагины могут дополнительно ограничивать это значение в зависимости от текущего уровня масштабирования.

Это свойство было добавлено в QtLocation 5.9.

См. также tilt и maximumTilt.

minimumZoomLevel : вещественное

Это свойство содержит минимальный допустимый уровень масштабирования карты.

Минимальный уровень масштабирования, определённый используемым плагином, является нижней границей для этого свойства. Однако возвращаемое значение также зависит от размера холста и может быть больше, чем заданное пользователем значение, или чем минимальный уровень масштабирования, определённый используемым плагином, чтобы предотвратить отображение карты, меньшего, чем область просмотра по любой размерности.

Если свойство плагина не установлено или плагин не поддерживает отображение, это свойство — 0.

plugin : Плагин

Это свойство содержит плагин, предоставляющий функциональность отображения карты.

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

supportedMapTypes : список<ТипКарты>

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

См. также activeMapType.

tilt : вещественное

Это свойство содержит наклон карты в градусах. Значение по умолчанию равно 0. Допустимый диапазон значений — [minimumTilt, maximumTilt]. Если используемый плагин для карты не поддерживает наклон, изменение этого свойства не повлияет на карту.

Это свойство было введено в QtLocation 5.9.

См. также minimumTilt и maximumTilt.

visibleArea : rect

Это свойство содержит видимую область внутри элемента Map QML. Это прямоугольник, координаты которого относительны к элементу Map. Его размер будет ограничен размером элемента Map. Значение null для visibleArea означает, что вся карта видна.

Это свойство было введено в Qt 5.12.

visibleRegion : geoshape

Это свойство содержит область, занимающую область просмотра карты. Камера размещается в центре фигуры и на максимально возможном целочисленном уровне масштабирования, при котором вся фигура видна на экране. Это подразумевает, что при считывании этого свойства вскоре после его установки возвращаемая область равна или больше установленной области.

Установка этого свойства неявно изменяет center и zoomLevel карты. Любое ранее установленное значение этих свойств будет перезаписано.

Примечание: начиная с Qt 5.14 это свойство предоставляет уведомления о изменениях.

Это свойство было введено в Qt 5.6.

zoomLevel : real

Это свойство содержит уровень масштабирования карты.

Более высокие значения уровня масштабирования обеспечивают больше деталей. Уровни масштабирования всегда неотрицательны. Значение по умолчанию равно 8,0. В зависимости от используемого плагина, значения за пределами диапазона [minimumZoomLevel, maximumZoomLevel] (представляющего диапазон доступных тайлов) могут быть приняты или ограничены.

Документация сигналов

copyrightLinkActivated(link)

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

Документация методов

void addMapItem(item)

Добавляет заданный элемент на карту (например, MapQuickItem, MapCircle). Если объект уже находится на карте, он не будет добавлен повторно.

В качестве примера, рассмотрим случай, когда у вас есть MapCircle, представляющий ваше текущее положение:

import QtQuick 2.0
import QtPositioning 5.5
import QtLocation 5.6

PositionSource {
    id: positionSource
}

Map {
    id: map
    property MapCircle circle

    Component.onCompleted: {
        circle = Qt.createQmlObject('import QtLocation 5.3; MapCircle {}', page)
        circle.center = positionSource.position.coordinate
        circle.radius = 5000.0
        circle.color = 'green'
        circle.border.width = 3
        map.addMapItem(circle)
    }
}

Примечание: MapItemView нельзя добавлять с помощью этого метода.

См. также mapItems, removeMapItem и clearMapItems.

void addMapItemGroup(itemGroup)

Добавляет элементы карты, содержащиеся в заданной группе элементов, на карту (например, MapQuickItem, MapCircle).

Этот метод был введён в Qt 5.9.

См. также MapItemGroup и removeMapItemGroup.

void addMapItemView(itemView)

Добавляет itemView на карту.

Этот метод был введён в Qt 5.10.

См. также MapItemView и removeMapItemView.

void addMapParameter(parameter)

Добавляет объект parameter на карту. Эффект этого вызова зависит от сочетания содержимого MapParameter и типа базового QGeoMap. Если добавлен MapParameter, не поддерживаемый базовым QGeoMap, вызов не оказывает никакого эффекта.

Выпуск этого API с Qt 5.9 — предварительный просмотр технологии.

Этот метод был введён в Qt 5.9.

См. также MapParameter, removeMapParameter, mapParameters и clearMapParameters.

void alignCoordinateToPoint(coordinate, QPointF point)

Выравнивает coordinate по point. Этот метод фактически расширяет функциональность, предоставляемую свойством qml center, позволяя выравнивать координату по точке элемента Map, отличной от его центра. Это полезно в тех приложениях, где центр сцены (например, курсор) не должен располагаться точно в центре карты.

Если карта наклонена, а coordinate оказывается позади камеры, или если карта не готова (см. mapReady), вызов этого метода не повлияет на карту.

Выпуск этого API с Qt 5.10 — предварительный просмотр технологии.

Этот метод был введён в Qt 5.10.

См. также center.

void clearData()

Очищает данные карты, собранные текущим выбранным плагином.

Примечание: Этот метод удалит кэшированные файлы.

См. также plugin.

void clearMapItems()

Удаляет все элементы и группы элементов с карты.

См. также mapItems, addMapItem, removeMapItem, addMapItemGroup и removeMapItemGroup.

void clearMapParameters()

Удаляет все параметры карты с карты.

Выпуск этого API с Qt 5.9 — предварительный просмотр технологии.

Этот метод был введён в Qt 5.9.

См. также MapParameter, mapParameters, addMapParameter, removeMapParameter и clearMapParameters.

void fitViewportToGeoShape(geoShape, margins)

Подстраивает область просмотра к определённой геометрической фигуре geoShape. Поля margins задаются в пикселях.

Примечание: Если проекция, используемая плагином, не WebMercator, и плагин не поддерживает приспособление к форме, этот метод ничего не сделает.

Этот метод был введён в Qt 5.13.

См. также visibleRegion.

void fitViewportToMapItems()

Подстраивает текущую область просмотра к границам всех элементов карты. Камера размещается в центре элементов карты и на максимальном целочисленном уровне масштабирования, при котором все элементы карты видны на экране.

См. также fitViewportToVisibleMapItems.

void fitViewportToVisibleMapItems()

Подстраивает текущую область просмотра к границам всех видимых элементов карты. Камера размещается в центре элементов карты и на максимальном целочисленном уровне масштабирования, при котором все элементы карты видны на экране.

См. также fitViewportToMapItems.

point fromCoordinate(coordinate, bool clipToViewPort)

Возвращает положение относительно элемента карты, соответствующее coordinate.

Если clipToViewPort равно true, или не указано, возвращает недопустимый QPointF, если coordinate не находится в текущей области просмотра.

void pan(dx, int dy)

Начинает перемещение карты на dx пикселей по оси x и на dy пикселей по оси y.

Положительные значения для dx перемещают карту вправо, отрицательные — влево. Положительные значения для dy перемещают карту вниз, отрицательные — вверх.

Во время перемещения center и zoomLevel могут измениться.

void prefetchData()

Необязательное указание, позволяющее карте предварительно загрузить данные в этот момент бездействия

void removeMapItem(item)

Удаляет заданный элемент с карты (например, MapQuickItem, MapCircle). Если элемент карты не существует или не был ранее добавлен на карту, метод ничего не делает.

См. также mapItems, addMapItem и clearMapItems.

void removeMapItemGroup(itemGroup)

Удаляет itemGroup и содержащиеся в нём элементы с карты.

Этот метод был введён в Qt 5.9.

См. также MapItemGroup и addMapItemGroup.

void removeMapItemView(itemView)

Удаляет itemView и элементы, созданные им, из карты.

Этот метод был введён в Qt 5.10.

См. также MapItemView и addMapItemView.

void removeMapParameter(parameter)

Удаляет заданный объект parameter из карты.

Выпуск этого API с Qt 5.9 — предварительный просмотр технологии.

Этот метод был введён в Qt 5.9.

См. также MapParameter, addMapParameter, mapParameters и clearMapParameters.

void setBearing(bearing, coordinate coordinate)

Устанавливает направление (bearing) карты, вращая её вокруг coordinate. Если плагин, используемый для карты, поддерживает направление, допустимый диапазон значений bearing составляет от 0 до 360. Если плагин, используемый для карты, не поддерживает направление, или если карта наклонена, а coordinate оказывается позади камеры, или если карта не готова (см. mapReady), вызов этого метода не окажет никакого эффекта.

Выпуск этого API с Qt 5.10 — предварительный просмотр технологии.

Этот метод был введён в Qt 5.10.

coordinate toCoordinate(position, bool clipToViewPort)

Возвращает координату, соответствующую position относительно элемента карты.

Если clipToViewPort — true, или не задан, то возвращает недействительные координаты, если position не находится в текущем области просмотра.