Тип QML Map

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

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

Свойства

• activeMapType : MapType
• center : координата
• color : цвет
• error : перечисление
• errorString : строка
• gesture : MapGestureArea
• mapItems : список<MapItem>
• maximumZoomLevel : вещественное число
• minimumZoomLevel : вещественное число
• plugin : Плагин
• supportedMapTypes : список<MapType>
• visibleRegion : геофигура
• zoomLevel : вещественное число

Сигналы

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

Методы

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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: osmPlugin
        name: "osm"
        // specify plugin parameters if necessary
        // PluginParameter {
        //     name:
        //     value:
        // }
    }

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

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

activeMapType : MapType

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

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

См. также MapType.

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

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

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

color : цвет

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

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

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

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

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

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

errorString : строка

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

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

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

gesture : MapGestureArea

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

mapItems : список<MapItem>

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

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

maximumZoomLevel : вещественное число

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

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

minimumZoomLevel : вещественное число

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

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

plugin : Plugin

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

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

supportedMapTypes : list<MapType>

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

См. также activeMapType.

visibleRegion : geoshape

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

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

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

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

zoomLevel : real

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

Более высокие значения уровня масштабирования обеспечивают более подробное отображение. Уровни масштабирования всегда неотрицательны. Значение по умолчанию равно 8.0.

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

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 clearData()

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

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

См. также plugin.

void clearMapItems()

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

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

void 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)

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

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

coordinate toCoordinate(QPointF position, bool clipToViewPort)

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

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