Тип QML карты

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

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

Свойства

• activeMapType : MapType
• bearing : real
• center : coordinate
• color : color
• copyrightsVisible : bool
• error : перечисление
• errorString : строка
• fieldOfView : real
• gesture : MapGestureArea
• mapItems : список<MapItem>
• mapParameters : список<MapParameters>
• mapReady : bool
• maximumFieldOfView : real
• maximumTilt : real
• maximumZoomLevel : real
• minimumFieldOfView : real
• minimumTilt : real
• minimumZoomLevel : real
• plugin : Plugin
• supportedMapTypes : список<MapType>
• tilt : real
• visibleArea : прямоугольник
• visibleRegion : геофигура
• 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 используется для отображения карты или изображения Земли, а также для отображения интерактивных объектов, связанных с поверхностью карты.

Существует множество способов визуализации поверхности Земли в двухмерном виде, но все они включают некоторого рода проекцию: математическое соответствие между трехмерными координатами (широта, долгота и высота) и двухмерными координатами (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 для выполнения обратного действия и удаления любых из вышеперечисленных типов объектов карты с карты.

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

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

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

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

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

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

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

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

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

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

Window {
    width: 512
    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 : coordinate

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

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

color : color

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

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

copyrightsVisible : bool

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

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

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

error : enumeration

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

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

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

errorString : string

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

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

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

fieldOfView : real

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

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

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

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

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

gesture : MapGestureArea

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

mapItems : list<MapItem>

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

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

mapParameters : list<MapParameters>

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

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

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

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

mapReady : bool

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

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

maximumFieldOfView : real

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

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

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

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

maximumTilt : real

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

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

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

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

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

maximumZoomLevel : real

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

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

minimumFieldOfView : real

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

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

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

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

minimumTilt : real

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

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

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

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

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

minimumZoomLevel : real

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

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

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

plugin : Plugin

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

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

supportedMapTypes : list<MapType>

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

См. также activeMapType.

tilt : real

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

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

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

visibleArea : прямоугольник

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

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

visibleRegion : геофигура

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

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

Это свойство не предоставляет уведомлений об изменениях.

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

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

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

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

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

copyrightLinkActivated(ссылка)

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

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

void addMapItem(элемент)

Добавляет указанный элемент на карту (например, 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(группаЭлементов)

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

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

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

void addMapItemView(itemView)

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

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

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

void addMapParameter(параметр)

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

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

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

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

void alignCoordinateToPoint(координата, QPointF точка)

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

Если карта наклонена, а координата находится за камерой, или если карта не готова (см. 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, отступы)

Подгоняет область просмотра к определенной геофигуре geoShape. Отступы — в пикселях экрана.

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

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

См. также visibleRegion.

void fitViewportToMapItems()

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

См. также fitViewportToVisibleMapItems.

void fitViewportToVisibleMapItems()

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

См. также fitViewportToMapItems.

точка fromCoordinate(координата, bool обрезкаПоОбласт)

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

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

void pan(dx, целое dy)

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

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

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

void prefetchData()

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

void removeMapItem(элемент)

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

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

void removeMapItemGroup(группаЭлементов)

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

Этот метод был добавлен в 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 не находится в текущем области просмотра.