Тип 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 : Плагин
• supportedMapTypes : список<MapType>
• tilt : real
• visibleArea : прямоугольник
• visibleRegion : геофигура
• zoomLevel : real

Сигналы

• copyrightLinkActivated(строка 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 fitViewportToMapItems()
• 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 вам необходимо установить это свойство. См. тип Плагин для описания получения соответствующего плагина для использования.

Географическая область, отображаемая в элементе Map, называется его viewport, и она определяется свойствами center и zoomLevel. Свойство center содержит coordinate, определяющий центр viewport, а 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.

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

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

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

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

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

Это свойство было добавлено в 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 : вещественное

Это свойство хранит наклон карты в градусах. Значение по умолчанию равно 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.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)
    }
}

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

См. также 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)

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

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

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

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

void alignCoordinateToPoint(coordinate coordinate, QPointF point)

Выравнивает coordinate по point. Этот метод расширяет функциональность, предлагаемую свойством center qml, позволяя выровнять координату по точке элемента 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 fitViewportToMapItems()

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

См. также 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 перемещают карту вниз, отрицательные — вверх.

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

void prefetchData()

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

void removeMapItem(MapItem item)

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

См. также 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)

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

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