Тип 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(строка link)

Методы

• void addMapItem(MapItem item)
• void addMapItemGroup(MapItemGroup itemGroup)
• void addMapItemView(MapItemView itemView)
• void addMapParameter(MapParameter parameter)
• void alignCoordinateToPoint(координата coordinate, QPointF point)
• void clearData()
• void clearMapItems()
• void clearMapParameters()
• void fitViewportToMapItems()
• void fitViewportToVisibleMapItems()
• точка fromCoordinate(координата 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(вещественное bearing, координата coordinate)
• координата toCoordinate(QPointF position, bool clipToViewPort)

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

Тип 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 на Map, если тип этого объекта является одним из MapCircle, MapRectangle, MapPolyline, MapPolygon, MapRoute или MapQuickItem. Также существует соответствующий метод removeMapItem для выполнения обратной операции и удаления любого из вышеперечисленных типов объектов карты с карты.

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

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

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

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

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

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

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

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

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

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

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

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

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

цвет : цвет

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

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

copyrightsVisible : bool

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

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

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

ошибка : перечисление

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

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

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

ошибкаСтрока : строка

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

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

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

уголОбзора : вещественное

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

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

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

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

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

жест : MapGestureArea

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

элементыКарты : список<MapItem>

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

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

параметрыКарты : список<MapParameters>

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

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

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

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

картаГотова : bool

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

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

максимальныйУголОбзора : вещественное

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

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

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

См. также уголОбзора и минимальныйУголОбзора.

максимальныйНаклон : вещественное

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

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

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

См. также наклон и минимальныйНаклон.

максимальныйУровеньМасштабирования : вещественное

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

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

минимальныйУголОбзора : вещественное

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

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

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

См. также уголОбзора и максимальныйУголОбзора.

минимальныйНаклон : вещественное

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

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

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

См. также наклон и максимальныйНаклон.

минимальныйУровеньМасштабирования : вещественное

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

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

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

плагин : Plugin

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

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

поддерживаемыеТипыКарт : список<MapType>

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

См. также активныйТипКарты.

наклон : вещественное

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

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

См. также минимальныйНаклон и максимальныйНаклон.

видимаяОбласть : геоформа

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

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

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

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

zoomLevel : real

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

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

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

copyrightLinkActivated(string link)

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

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

void addMapItem(MapItem item)

Добавляет заданный 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)

Добавляет объект MapParameter на карту. Действие этого вызова зависит от комбинации содержимого 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 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 перемещают карту вниз, отрицательные — вверх.

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

void prefetchData()

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

void removeMapItem(MapItem item)

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