Тип 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(string link)

Методы

• void addMapItem(MapItem item)
• void addMapItemGroup(MapItemGroup itemGroup)
• void addMapItemView(MapItemView itemView)
• void addMapParameter(MapParameter parameter)
• void alignCoordinateToPoint(coordinate coordinate, QPointF point)
• void clearData()
• void clearMapItems()
• void clearMapParameters()
• void fitViewportToGeoShape(geoShape, margins)
• void fitViewportToMapItems(list<MapItems> items)
• void fitViewportToVisibleMapItems()
• point fromCoordinate(coordinate coordinate, bool clipToViewPort)
• void pan(int dx, int dy)
• void prefetchData()
• void removeMapItem(MapItem item)
• void removeMapItemGroup(MapItemGroup itemGroup)
• void removeMapItemView(MapItemView itemView)
• void removeMapParameter(MapParameter parameter)
• void setBearing(real bearing, coordinate coordinate)
• coordinate toCoordinate(QPointF 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 на Map, если тип этого объекта является одним из MapCircle, MapRectangle, MapPolyline, MapPolygon, MapRoute или MapQuickItem. Существует соответствующий метод removeMapItem, чтобы сделать то же самое и удалить любой из вышеперечисленных типов объектов карты с карты.

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

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

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

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

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

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

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

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

Следующий фрагмент показывает простую карту и необходимый тип плагина для ее использования. Карта центрирована над Осло, Норвегия, с уровнем масштаба 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, созданный с картой. Это охватывает жесты перемещения, быстрой прокрутки и масштабирования. Используйте 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 : real

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

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

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

visibleArea : rect

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

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

visibleRegion : geoshape

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

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

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

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

zoomLevel : real

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

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

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

copyrightLinkActivated(string link)

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

Примечание: соответствующий обработчик — onCopyrightLinkActivated.

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

void addMapItem(MapItem 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)
    }
}

Примечание: MapItemViews не могут быть добавлены с помощью этого метода.

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

void addMapItemGroup(MapItemGroup itemGroup)

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

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

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

void addMapItemView(MapItemView itemView)

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

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

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

void addMapParameter(MapParameter parameter)

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

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

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

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

void alignCoordinateToPoint(coordinate coordinate, QPointF point)

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

Если карта наклонена, а 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(list<MapItems> items = {})

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

Примечание: Этот метод получил необязательный аргумент items начиная с Qt 5.15. В предыдущих версиях этот метод подстраивал карту под все элементы карты.

См. также fitViewportToVisibleMapItems.

void fitViewportToVisibleMapItems()

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

См. также fitViewportToMapItems.

point fromCoordinate(coordinate coordinate, bool clipToViewPort)

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

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

void pan(int dx, int dy)

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

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

При панорамировании центра и уровня масштабирования могут измениться.

void prefetchData()

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

void removeMapItem(MapItem item)

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

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

void removeMapItemGroup(MapItemGroup itemGroup)

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

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

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

void removeMapItemView(MapItemView itemView)

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

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

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

void removeMapParameter(MapParameter parameter)

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

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

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

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

void setBearing(real bearing, coordinate coordinate)

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

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

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

coordinate toCoordinate(QPointF position, bool clipToViewPort)

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

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