Тип QML Map

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

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

Свойства

• activeMapType : MapType
• bearing : вещественное
• center : координата
• color : цвет
• copyrightsVisible : bool
• error : перечисление
• errorString : строка
• fieldOfView : вещественное
• gesture : MapGestureArea
• mapItems : список<MapItem>
• mapParameters : список<MapParameters>
• mapReady : bool
• maximumFieldOfView : вещественное
• maximumTilt : вещественное
• maximumZoomLevel : вещественное
• minimumFieldOfView : вещественное
• minimumTilt : вещественное
• minimumZoomLevel : вещественное
• plugin : Плагин
• supportedMapTypes : список<MapType>
• tilt : вещественное
• visibleRegion : геофигура
• zoomLevel : вещественное

Сигналы

• copyrightLinkActivated(строка ссылка)

Методы

• void addMapItem(MapItem элемент)
• void addMapItemGroup(MapItemGroup группа элементов)
• void addMapParameter(MapParameter параметр)
• void clearData()
• void clearMapItems()
• void clearMapParameters()
• void fitViewportToMapItems()
• void fitViewportToVisibleMapItems()
• точка fromCoordinate(координата координата, bool обрезать по области просмотра)
• void pan(int dx, int dy)
• void prefetchData()
• void removeMapItem(MapItem элемент)
• void removeMapItemGroup(MapItemGroup группа элементов)
• void removeMapParameter(MapParameter параметр)
• координата toCoordinate(QPointF позиция, bool обрезать по области просмотра)

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

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

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

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

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

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

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

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

Объекты, относящиеся к карте, могут быть объявлены в теле объекта Map в Qt Quick и автоматически появятся на карте. Для добавления объектов программно, сначала убедитесь, что они созданы с Map в качестве родительского элемента (например, в качестве аргумента Component::createObject), а затем вызовите метод addMapItem на карте. Также существует соответствующий метод removeMapItem для выполнения обратного действия и удаления объекта из карты.

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

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

Тип Map поддерживает жесты масштабирования и перетаскивания для управления масштабированием и перемещением. Они включены по умолчанию и доступны в любое время с помощью объекта 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 : вещественное

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

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

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

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

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

color : цвет

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

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

copyrightsVisible : bool

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

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

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

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

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

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

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

errorString : string

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

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

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

fieldOfView : real

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

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

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

Это свойство QML было добавлено в Qt Location 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 — это предварительный просмотр технологии.

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

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

mapReady : bool

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

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

maximumFieldOfView : real

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

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

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

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

maximumTilt : real

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

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

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

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

maximumZoomLevel : real

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

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

minimumFieldOfView : real

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

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

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

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

minimumTilt : real

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

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

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

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

minimumZoomLevel : real

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

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

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

plugin : Plugin

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

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

supportedMapTypes : list<MapType>

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

См. также activeMapType.

tilt : real

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

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

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

visibleRegion : geoshape

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

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

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

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

zoomLevel : real

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

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

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

copyrightLinkActivated(string link)

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

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

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)

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

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

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

void addMapParameter(MapParameter parameter)

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

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

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

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

void clearData()

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

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

См. также plugin.

void clearMapItems()

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

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

void clearMapParameters()

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

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

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

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

void fitViewportToMapItems()

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

См. также fitViewportToVisibleMapItems.

void fitViewportToVisibleMapItems()

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

См. также fitViewportToMapItems.

point fromCoordinate(coordinate coordinate, bool clipToViewPort)

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

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

void pan(int dx, int dy)

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

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

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

void prefetchData()

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

void removeMapItem(MapItem item)

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

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

void removeMapItemGroup(MapItemGroup itemGroup)

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

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

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

void removeMapParameter(MapParameter parameter)

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

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

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

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

coordinate toCoordinate(QPointF position, bool clipToViewPort)

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

Если cliptoViewPort равно true, или не указано, возвращает недействительную координату, если position не находится в текущем viewport.