Back to Qt.io
Contact Us Blog Download Qt
Sur cette page

Map QML Type

Le type Carte permet d'afficher une carte. Plus d'informations...

Import Statement: import QtLocation 6.11
Since: QtLocation 5.0

Propriétés

Signaux

Méthodes

Description détaillée

Le type Carte est utilisé pour afficher une carte ou une image de la Terre, avec la possibilité d'afficher également des objets interactifs liés à la surface de la carte.

Il existe différentes façons de visualiser la surface de la Terre en deux dimensions, mais toutes impliquent une certaine forme de projection : une relation mathématique entre les coordonnées 3D (latitude, longitude et altitude) et les coordonnées 2D (X et Y en pixels) sur l'écran.

Différentes sources de données cartographiques peuvent utiliser différentes projections et, du point de vue du type de carte, nous les traitons comme une seule unité remplaçable : le module d'extension de carte. Un plugin de carte consiste en une source de données, ainsi que tous les autres détails nécessaires à l'affichage de ses données à l'écran.

Le plugin de carte en cours d'utilisation est contenu dans la propriété plugin de l'élément Map. Pour afficher une image dans un élément de carte, vous devez définir cette propriété. Voir le type Plugin pour une description de la manière de récupérer un plugin approprié à utiliser.

La région géographique affichée dans l'élément de carte est appelée "viewport" et est définie par les propriétés center, et zoomLevel. La propriété center contient une coordonnée spécifiant le centre de la fenêtre d'affichage, tandis que la propriété zoomLevel contrôle l'échelle de la carte. Voir chacune de ces propriétés pour plus de détails sur leurs valeurs.

Lorsque la carte est affichée, chaque coordonnée géographique visible correspond à une coordonnée X et Y sur l'écran. Pour effectuer les conversions entre les deux, Map fournit les fonctions toCoordinate et fromCoordinate, qui sont d'une utilité générale.

Objets de la carte

Les objets liés à la carte peuvent être déclarés dans le corps d'un objet Map à l'adresse Qt Quick et apparaîtront automatiquement sur la carte. Pour ajouter un objet par programme, il faut d'abord s'assurer qu'il est créé avec la carte comme parent (par exemple dans un argument de Component::createObject). Appelez ensuite la méthode addMapItem sur la carte, si le type de cet objet est l'un des suivants : MapCircle, MapRectangle, MapPolyline, MapPolygon, MapRoute ou MapQuickItem. Il existe également une méthode removeMapItem pour faire l'inverse et supprimer de la carte n'importe lequel des types d'objets susmentionnés.

Le déplacement des objets cartographiques, leur redimensionnement ou la modification de leur forme n'impliquent normalement aucune interaction particulière avec la carte elle-même - la modification de ces propriétés dans un objet cartographique met automatiquement à jour l'affichage.

Performances

Les cartes sont rendues à l'aide d'OpenGL (ES) et de la pile Qt Scene Graphs, ce qui leur confère d'excellentes performances lorsque du matériel accéléré par GL est disponible.

Pour les cartes "en ligne", la bande passante et la latence du réseau peuvent être des facteurs importants dans la perception des performances par l'utilisateur. Une mise en cache importante est effectuée pour atténuer ce phénomène, mais cette atténuation n'est pas toujours parfaite.

En général, les éléments cartographiques complexes et de grande taille, tels que les polygones et les polylignes comportant un grand nombre de sommets, peuvent avoir un effet négatif sur les performances de l'interface utilisateur.

Exemple d'utilisation

L'extrait suivant montre une carte simple et le type de plugin nécessaire pour l'utiliser. La carte est centrée sur Oslo, Norvège, avec un niveau de zoom de 14.

import QtQuick
import QtLocation
import QtPositioning

Window {
    ...
    Plugin {
        id: mapPlugin
        name: "osm"
    }

    Map {
        id: map
        anchors.fill: parent
        plugin: mapPlugin
        center: QtPositioning.coordinate(59.91, 10.75) // Oslo
        zoomLevel: 14
        property geoCoordinate startCentroid

        PinchHandler {
            id: pinch
            target: null
            onActiveChanged: if (active) {
                map.startCentroid = map.toCoordinate(pinch.centroid.position, false)
            }
            onScaleChanged: (delta) => {
                map.zoomLevel += Math.log2(delta)
                map.alignCoordinateToPoint(map.startCentroid, pinch.centroid.position)
            }
            onRotationChanged: (delta) => {
                map.bearing -= delta
                map.alignCoordinateToPoint(map.startCentroid, pinch.centroid.position)
            }
            grabPermissions: PointerHandler.TakeOverForbidden
        }
        WheelHandler {
            id: wheel
            // workaround for QTBUG-87646 / QTBUG-112394 / QTBUG-112432:
            // Magic Mouse pretends to be a trackpad but doesn't work with PinchHandler
            // and we don't yet distinguish mice and trackpads on Wayland either
            acceptedDevices: Qt.platform.pluginName === "cocoa" || Qt.platform.pluginName === "wayland"
                             ? PointerDevice.Mouse | PointerDevice.TouchPad
                             : PointerDevice.Mouse
            rotationScale: 1/120
            property: "zoomLevel"
        }
        DragHandler {
            id: drag
            target: null
            onTranslationChanged: (delta) => map.pan(-delta.x, -delta.y)
        }
        Shortcut {
            enabled: map.zoomLevel < map.maximumZoomLevel
            sequence: StandardKey.ZoomIn
            onActivated: map.zoomLevel = Math.round(map.zoomLevel + 1)
        }
        Shortcut {
            enabled: map.zoomLevel > map.minimumZoomLevel
            sequence: StandardKey.ZoomOut
            onActivated: map.zoomLevel = Math.round(map.zoomLevel - 1)
        }
    }
}

Documentation sur les propriétés

activeMapType : mapType

Accès au site actuellement actif map type.

Cette propriété peut être définie pour changer le site actif map type. Voir la propriété supportedMapTypes pour les valeurs possibles.

Voir aussi mapType.

bearing : real [since QtLocation 5.9]

Cette propriété indique le relèvement de la carte. La valeur par défaut est 0. Si le plugin utilisé pour la carte prend en charge le relèvement, cette valeur est comprise entre 0 et 360. Si le plugin utilisé pour la carte ne prend pas en charge le relèvement, la modification de cette propriété n'aura aucun effet.

Cette propriété a été introduite dans QtLocation 5.9.

center : coordinate

Cette propriété contient la coordonnée qui occupe le centre de la fenêtre de visualisation de la cartographie. Les coordonnées centrales non valides sont ignorées.

La valeur par défaut est une coordonnée valide arbitraire.

color : color

Cette propriété définit la couleur d'arrière-plan de l'élément de la carte.

copyrightsVisible : bool

Cette propriété définit la visibilité de l'avis de droits d'auteur. Elle est généralement affichée dans le coin inférieur gauche. Par défaut, cette propriété est définie sur true.

Remarque : de nombreux fournisseurs de cartes exigent que l'avis soit visible dans le cadre des conditions générales d'utilisation. Veuillez consulter la documentation du fournisseur concerné avant de désactiver cet avis.

error : enumeration [read-only]

Cette propriété en lecture seule contient la dernière erreur du fournisseur de services de cartographie.

  • Carte.NoError - Aucune erreur ne s'est produite.
  • Map.NotSupportedError -La propriété du plugin maps n'a pas été définie ou il n'y a pas de gestionnaire de cartographie associé au plugin.
  • Map.UnknownParameterError -Le plugin n'a pas reconnu l'un des paramètres qui lui ont été fournis.
  • Map.MissingRequiredParameterError - Le plugin n'a pas trouvé l'un des paramètres qu'il attendait.
  • Map.ConnectionError - Le plugin n'a pas pu se connecter à son service ou à sa base de données.

Voir aussi QGeoServiceProvider::Error.

errorString : string [read-only]

Cette propriété en lecture seule contient la présentation textuelle de la dernière erreur du fournisseur de cartographie. Si aucune erreur ne s'est produite, une chaîne vide est renvoyée.

Une chaîne vide peut également être renvoyée en cas d'erreur n'ayant pas de représentation textuelle associée.

Voir également QGeoServiceProvider::errorString().

fieldOfView : real [since QtLocation 5.9]

Cette propriété indique le champ de vision de la caméra utilisée pour regarder la carte, en degrés. Si la propriété plugin de la carte n'est pas définie, ou si le plugin ne prend pas en charge la cartographie, la valeur est de 45 degrés.

Notez que la modification de cette valeur modifie implicitement la distance entre la caméra et la carte, de sorte que, pour un angle d'inclinaison de 0 degré, l'image résultante est identique quelle que soit la valeur utilisée pour cette propriété.

Pour plus d'informations sur ce paramètre, consultez les articles de Wikipédia intitulés Champ de vision et Angle de vision.

Cette propriété a été introduite dans QtLocation 5.9.

Voir aussi minimumFieldOfView et maximumFieldOfView.

mapItems : list<MapItem> [read-only]

Renvoie la liste de tous les éléments de la carte, sans ordre particulier. Ces éléments comprennent les éléments déclarés statiquement dans le cadre de la déclaration de type, ainsi que les éléments dynamiques (addMapItem, MapItemView).

Voir également addMapItem, removeMapItem, et clearMapItems.

mapReady : bool [read-only]

Cette propriété indique si la carte a été initialisée avec succès et si elle est prête à être utilisée. Certaines méthodes, telles que fromCoordinate et toCoordinate, ne fonctionneront pas tant que la carte ne sera pas prête. En raison de l'architecture de Map, il est conseillé d'utiliser le signal émis pour cette propriété à la place de Component.onCompleted, afin de s'assurer que tout se passe comme prévu.

maximumFieldOfView : real [since QtLocation 5.9]

Cette propriété indique le champ de vision maximal valide pour la carte, en degrés.

L'inclinaison minimale du champ de vision par le plugin utilisé est une limite supérieure pour cette propriété. Si la propriété plugin n'est pas définie ou si le plugin ne prend pas en charge la cartographie, cette propriété est 179.

Cette propriété a été introduite dans QtLocation 5.9.

Voir aussi fieldOfView et minimumFieldOfView.

maximumTilt : real [since QtLocation 5.9]

Cette propriété indique l'inclinaison maximale valide de la carte, en degrés.

L'inclinaison maximale définie par le site plugin utilisé est une limite supérieure pour cette propriété. Si la propriété plugin n'est pas définie ou si le plugin ne prend pas en charge la cartographie, cette propriété vaut 89.5.

Depuis QtLocation 5.12, les plugins peuvent en outre limiter cette valeur en fonction du niveau de zoom actuel.

Cette propriété a été introduite dans QtLocation 5.9.

Voir également tilt et minimumTilt.

maximumZoomLevel : real

Cette propriété indique le niveau de zoom maximum valide pour la carte.

Le niveau de zoom maximum est défini par le site plugin utilisé. Si la propriété plugin n'est pas définie ou si le plugin ne prend pas en charge la cartographie, cette propriété vaut 30.

minimumFieldOfView : real [since QtLocation 5.9]

Cette propriété indique le champ de vision minimum valide pour la carte, en degrés.

Le champ de vision minimal de l'inclinaison du site plugin utilisé est une limite inférieure pour cette propriété. Si la propriété plugin n'est pas définie ou si le plugin ne prend pas en charge la cartographie, cette propriété est 1.

Cette propriété a été introduite dans QtLocation 5.9.

Voir aussi fieldOfView et maximumFieldOfView.

minimumTilt : real [since QtLocation 5.9]

Cette propriété indique l'inclinaison minimale valide de la carte, en degrés.

L'inclinaison minimale définie par le site plugin utilisé est une limite inférieure pour cette propriété. Si la propriété plugin n'est pas définie ou si le plugin ne prend pas en charge la cartographie, cette propriété vaut 0.

Depuis QtLocation 5.12, les plugins peuvent en outre limiter cette valeur en fonction du niveau de zoom actuel.

Cette propriété a été introduite dans QtLocation 5.9.

Voir également tilt et maximumTilt.

minimumZoomLevel : real

Cette propriété indique le niveau de zoom minimum valide pour la carte.

Le niveau de zoom minimum défini par le site plugin utilisé est une limite inférieure pour cette propriété. Cependant, la valeur renvoyée dépend également de la taille du canevas et peut être supérieure à la valeur spécifiée par l'utilisateur ou au niveau de zoom minimum défini par le plugin utilisé, afin d'éviter que la carte ne soit plus petite que la fenêtre de visualisation dans l'une ou l'autre dimension.

Si la propriété plugin n'est pas définie ou si le plugin ne prend pas en charge la cartographie, cette propriété est 0.

plugin : Plugin

Cette propriété contient le plugin qui fournit la fonctionnalité de mappage.

Il s'agit d'une propriété "write-once". Une fois que la carte est associée à un plugin, toute tentative de modification du plugin sera ignorée.

supportedMapTypes : list<mapType> [read-only]

Cette propriété en lecture seule contient l'ensemble des map types pris en charge par cette carte.

Voir aussi activeMapType.

tilt : real [since QtLocation 5.9]

Cette propriété indique l'inclinaison de la carte, en degrés. La valeur par défaut est 0. La plage de validité de cette valeur est [ minimumTilt, maximumTilt ]. Si le plugin utilisé pour la carte ne prend pas en charge l'inclinaison, la modification de cette propriété n'aura aucun effet.

Cette propriété a été introduite dans QtLocation 5.9.

Voir également minimumTilt et maximumTilt.

visibleArea : rect

Cette propriété définit la zone visible à l'intérieur de l'élément QML Map. Il s'agit d'un rect dont les coordonnées sont relatives à l'élément Map. Sa taille sera adaptée à celle de l'élément Map. Une zone visible nulle signifie que toute la carte est visible.

visibleRegion : geoShape

Cette propriété contient la région qui occupe la fenêtre de visualisation de la carte. La caméra est positionnée au centre de la forme et au niveau de zoom intégral le plus élevé possible, ce qui permet à la forme entière d'être visible à l'écran. Cela signifie qu'en relisant cette propriété peu de temps après l'avoir définie, la zone renvoyée est égale ou supérieure à la zone définie.

La définition de cette propriété modifie implicitement center et zoomLevel de la carte. Toute valeur précédemment définie pour ces propriétés sera remplacée.

Remarque : depuis Qt 5.14, cette propriété fournit des notifications de changement.

zoomLevel : real

Cette propriété indique le niveau de zoom de la carte.

Des valeurs plus élevées du niveau de zoom permettent d'obtenir plus de détails. Les niveaux de zoom sont toujours non négatifs. La valeur par défaut est 8.0. Selon le plugin utilisé, les valeurs en dehors de la plage [minimumZoomLevel, maximumZoomLevel], qui représentent la plage pour laquelle des tuiles sont disponibles, peuvent être acceptées ou bloquées.

Documentation sur les signaux

copyrightLinkActivated(string link)

Ce signal est émis lorsque l'utilisateur clique sur un lien link dans l'avis de droit d'auteur. L'application doit ouvrir le lien dans un navigateur ou afficher son contenu à l'utilisateur.

Remarque : le gestionnaire correspondant est onCopyrightLinkActivated.

Documentation de la méthode

void addMapItem(MapItem item)

Ajoute l'objet item à la carte (par exemple MapQuickItem, MapCircle). Si l'objet figure déjà sur la carte, il ne sera pas ajouté à nouveau.

Prenons l'exemple d'un objet MapCircle représentant votre position actuelle :

import QtQuick
import QtPositioning
import QtLocation

PositionSource {
    id: positionSource
}

Map {
    id: map
    property MapCircle circle

    Component.onCompleted: {
        circle = Qt.createQmlObject('import QtLocation; MapCircle {}', page)
        circle.center = positionSource.position.coordinate
        circle.radius = 5000.0
        circle.color = 'green'
        circle.border.width = 3
        map.addMapItem(circle)
    }
}

Remarque : cette méthode ne permet pas d'ajouter des MapItemViews.

Voir également mapItems, removeMapItem, et clearMapItems.

void addMapItemGroup(MapItemGroup itemGroup)

Ajoute à la carte les éléments contenus dans l'adresse itemGroup (par exemple MapQuickItem, MapCircle).

Voir aussi MapItemGroup et removeMapItemGroup.

void addMapItemView(MapItemView itemView)

Ajoute itemView à la carte.

Voir aussi MapItemView et removeMapItemView.

void alignCoordinateToPoint(coordinate coordinate, QPointF point)

Aligne coordinate sur point Cette méthode étend efficacement la fonctionnalité offerte par la propriété qml center, en permettant d'aligner une coordonnée sur un point de l'élément Map autre que son centre. Cette méthode est utile dans les applications où le centre de la scène (par exemple, un curseur) ne doit pas être placé exactement au centre de la carte.

Si la carte est inclinée et que coordinate se trouve derrière la caméra, ou si la carte n'est pas prête (voir mapReady), l'appel à cette méthode n'aura aucun effet.

La version de cette API avec Qt 5.10 est un aperçu technologique.

Voir également center.

void clearData()

Efface les données cartographiques collectées par le plugin sélectionné.

Remarque : cette méthode supprime les fichiers mis en cache.

Voir aussi plugin.

void clearMapItems()

Supprime tous les éléments et groupes d'éléments de la carte.

Voir aussi mapItems, addMapItem, removeMapItem, addMapItemGroup, et removeMapItemGroup.

void fitViewportToGeoShape(geoShape, margins)

Adapte la fenêtre de visualisation à une forme géographique spécifique geoShape. L'adresse margins est exprimée en pixels d'écran.

Note : Si la projection utilisée par le plugin n'est pas WebMercator, et que le plugin n'a pas la capacité de s'adapter à la forme, cette méthode ne fera rien.

Voir aussi visibleRegion.

void fitViewportToMapItems(list<MapItems> items = {})

Si aucun argument n'est fourni, la fenêtre de visualisation actuelle s'adapte aux limites de tous les éléments de la carte. La caméra est placée au centre des éléments de la carte et au niveau de zoom intégral le plus élevé possible qui permet à tous les éléments de la carte d'être visibles à l'écran. Si items est fourni, la fenêtre de visualisation actuelle s'adapte uniquement aux limites des éléments de la carte spécifiés.

Note : Cette méthode a obtenu l'argument optionnel items depuis Qt 5.15. Dans les versions précédentes, cette méthode ajustait la carte à tous les éléments de la carte.

Voir aussi fitViewportToVisibleMapItems.

void fitViewportToVisibleMapItems()

Ajuste la fenêtre de visualisation actuelle aux limites de tous les éléments visibles de la carte. La caméra est placée au centre des éléments de la carte et au niveau de zoom intégral le plus élevé possible, ce qui permet à tous les éléments de la carte d'être visibles à l'écran.

Voir également fitViewportToMapItems.

point fromCoordinate(coordinate coordinate, bool clipToViewPort)

Renvoie la position relative à l'élément de la carte qui correspond à coordinate.

Si clipToViewPort est true, ou n'est pas fourni, il renvoie un QPointF invalide si coordinate n'est pas dans la fenêtre de visualisation actuelle.

void pan(int dx, int dy)

Commence à faire pivoter la carte de dx pixels le long de l'axe x et de dy pixels le long de l'axe y.

Les valeurs positives de dx déplacent la carte vers la droite, les valeurs négatives vers la gauche. Les valeurs positives de dy déplacent la carte vers le bas, les valeurs négatives vers le haut.

Lors d'un panoramique, les valeurs center, et zoomLevel peuvent changer.

void prefetchData()

Indice facultatif permettant à la carte d'effectuer des recherches préalables pendant cette période d'inactivité.

void removeMapItem(MapItem item)

Supprime l'élément item de la carte (par exemple MapQuickItem, MapCircle). Si le MapItem n'existe pas ou n'a pas été ajouté précédemment à la carte, la méthode ne fait rien.

Voir aussi mapItems, addMapItem, et clearMapItems.

void removeMapItemGroup(MapItemGroup itemGroup)

Supprime de la carte itemGroup et les éléments qu'elle contient.

Voir également MapItemGroup et addMapItemGroup.

void removeMapItemView(MapItemView itemView)

Supprime itemView et les éléments qu'il instancie de la carte.

Voir aussi MapItemView et addMapItemView.

void setBearing(real bearing, coordinate coordinate)

Fixe l'orientation de la carte à bearing, en la faisant pivoter autour de coordinate. Si le plugin utilisé pour la carte prend en charge le relèvement, la plage valide pour bearing est comprise entre 0 et 360. Si le plugin utilisé pour la carte ne prend pas en charge le relèvement, ou si la carte est inclinée et que coordinate se trouve derrière la caméra, ou si la carte n'est pas prête (voir mapReady), l'appel à cette méthode n'aura aucun effet.

La version de cette API avec Qt 5.10 est un aperçu technologique.

coordinate toCoordinate(QPointF position, bool clipToViewPort)

Renvoie la coordonnée correspondant à position par rapport à l'élément de la carte.

Si clipToViewPort est true ou n'est pas fourni, il renvoie une coordonnée non valide si position ne se trouve pas dans la fenêtre d'affichage actuelle.

© 2026 The Qt Company Ltd. Documentation contributions included herein are the copyrights of their respective owners. The documentation provided herein is licensed under the terms of the GNU Free Documentation License version 1.3 as published by the Free Software Foundation. Qt and respective logos are trademarks of The Qt Company Ltd. in Finland and/or other countries worldwide. All other trademarks are property of their respective owners.