Visor de mapas (QML)
El ejemplo del visor de mapas muestra cómo visualizar un mapa e interactuar con él, buscar una dirección y obtener indicaciones para llegar en coche.

Se trata de un ejemplo extenso que abarca muchos usos básicos de los mapas, el posicionamiento y los servicios de navegación en Qt Location. Esta página se divide en secciones que abarcan cada una de estas áreas de funcionalidad con fragmentos del código.
Ejecución del ejemplo
Puedes ejecutar el ejemplo desde:
- Qt Creator
Abre el modo « Welcome » y selecciona el ejemplo en Examples. Para obtener más información, consulta Qt Creator: Tutorial: Compilar y ejecutar.
- Qt Extension for Visual Studio Code
Ejecute el comando « Qt: Open Qt examples » desde Command Palette y seleccione el ejemplo de la lista. Para obtener más información, consulte Qt Extension for Visual Studio Code: Tutorial: Compilar y ejecutar.
El ejemplo funciona con cualquiera de los complementos de servicios geográficos disponibles. No obstante, es posible que algunos complementos requieran un « plugin parameters » adicional para funcionar correctamente. Se puede pasar Plugin parameters en la línea de comandos utilizando el argumento --plugin, que tiene el siguiente formato:
--plugin.<parameter name> <parameter value>Consulta la documentación de cada uno de los complementos de servicios geográficos para obtener más detalles sobre los parámetros que admiten. El complemento predeterminado utilizado en este ejemplo es el complemento OpenStreetMap deQt Location , que no requiere ningún parámetro.
Resumen
Tipos QML que aparecen en este ejemplo:
- Visualización de un mapa
- Búsqueda de una dirección
- Indicaciones y rutas de viaje
Visualización de un mapa
Para dibujar un mapa en pantalla se utiliza el tipo « MapView », tal y como se muestra a continuación.
MapView {
id: view
map.zoomLevel: (maximumZoomLevel - minimumZoomLevel)/2
map.center {
// The Qt Company in Oslo
latitude: 59.9485
longitude: 10.7686
}
}El tipo ` MapView ` se compone de un ` map ` y lo amplía para ofrecer funciones básicas de navegación. En este ejemplo, asignamos al mapa un centro inicial geoCoordinate con una latitud y una longitud determinadas. También establecemos el nivel de zoom inicial en el 50 % (a medio camino entre el máximo y el mínimo).
Búsqueda de una dirección (geocodificación)
Para localizar una dirección o un lugar concreto en el mapa se utiliza un proceso denominado geocodificación. Para realizar una operación de geocodificación, primero debemos configurar nuestro objeto Map para que pueda recibir el resultado.
La recepción de los resultados de la geocodificación se realiza a través de un ` GeocodeModel`:
GeocodeModel {
id: geocodeModel
plugin: view.map.plugin
onStatusChanged: {
if ((status == GeocodeModel.Ready) || (status == GeocodeModel.Error))
view.geocodeFinished()
}
onLocationsChanged:
{
if (count === 1) {
view.map.center.latitude = get(0).coordinate.latitude
view.map.center.longitude = get(0).coordinate.longitude
}
}
}Para mostrar el contenido del ` GeocodeModel `, utilizamos un ` MapItemView`:
MapItemView {
parent: view.map
model: geocodeModel
delegate: pointDelegate
}MapItemView utiliza un objeto denominado « delegate » que actúa como plantilla para los elementos que crea. Este puede contener cualquier objeto de mapa que se desee, pero en este caso mostramos un « MapQuickItem » que contiene una imagen de un marcador:
Component {
id: pointDelegate
MapQuickItem {
id: point
parent: view.map
coordinate: locationData.coordinate
sourceItem: Image {
id: pointMarker
source: "../resources/marker_blue.png"
}
}
}Con estos tres objetos, tenemos lo necesario para recibir respuestas de geocodificación y mostrarlas en nuestro mapa. El último paso es enviar la solicitud de geocodificación propiamente dicha.
Para enviar una solicitud de geocodificación, primero creamos un objeto ` Address ` y lo rellenamos con los parámetros deseados.
Address {
id :fromAddress
street: "Sandakerveien 116"
city: "Oslo"
country: "Norway"
state : ""
postalCode: "0484"
}A continuación, asignamos geocodeModel.query a Address una vez rellenado, y llamamos a update() en GeocodeModel.
// send the geocode request
geocodeModel.query = fromAddress
geocodeModel.update()Indicaciones y rutas de viaje
Al igual que el ` GeocodeModel`, el ` Qt Location ` también cuenta con el tipo ` RouteModel `, que permite recibir información sobre rutas (por ejemplo, indicaciones para llegar en coche) entre dos o más puntos, y utilizarla con un ` Map`.
De nuevo, instanciamos el ` RouteModel ` como una propiedad de nuestro `Map`:
RouteModel {
id: routeModel
plugin : view.map.plugin
query: RouteQuery {
id: routeQuery
}
onStatusChanged: {
if (status == RouteModel.Ready) {
switch (count) {
case 0:
// technically not an error
view.routeError()
break
case 1:
view.showRouteList()
break
}
} else if (status == RouteModel.Error) {
view.routeError()
}
}
}Para mostrar el contenido de un modelo al usuario, necesitamos una vista. Una vez más, utilizaremos un MapItemView para mostrar las rutas como objetos en el mapa:
MapItemView {
parent: view.map
model: routeModel
delegate: routeDelegatePara que sirva de plantilla a los objetos que queremos que cree la vista, creamos un componente delegado:
Component {
id: routeDelegate
MapRoute {
id: route
route: routeData
line.color: "#46a2da"
line.width: 5
smooth: true
opacity: 0.8Ahora que el modelo, la vista y el delegado están completos, el único componente que falta es algún tipo de control sobre el modelo para iniciar el proceso de solicitud de ruta. En el caso más sencillo, podemos rellenar una solicitud de ruta utilizando dos coordinates ya disponibles:
property variant fromCoordinate: QtPositioning.coordinate(59.9483, 10.7695)
property variant toCoordinate: QtPositioning.coordinate(59.9645, 10.671)En el siguiente fragmento de código, mostramos cómo configurar el objeto de solicitud e indicar al modelo que se actualice. También indicamos al mapa que se centre en la coordenada de inicio de nuestra solicitud de ruta.
// clear away any old data in the query
routeQuery.clearWaypoints();
// add the start and end coords as waypoints on the route
routeQuery.addWaypoint(startCoordinate)
routeQuery.addWaypoint(endCoordinate)
routeQuery.travelModes = RouteQuery.CarTravel
routeQuery.routeOptimizations = RouteQuery.FastestRoute
routeModel.update();
// center the map on the start coord
view.map.center = startCoordinate;Esto es todo lo que se necesita para mostrar una ruta en el mapa. Sin embargo, también resulta útil poder recuperar las indicaciones escritas y la explicación de la ruta de viaje. En el ejemplo, estas se muestran en un elemento ` ListView `. Para crear este contenido, utilizamos un par estándar de `ListModel` y ` ListView `. Los datos del ` ListModel` se construyen a partir de la salida del `routeModel`:
ListView {
interactive: true
model: ListModel { id: routeInfoModel }
header: RouteListHeader {}
delegate: RouteListDelegate{
routeIndex.text: index + 1
routeInstruction.text: instruction
routeDistance.text: distance
}
}Dentro del elemento ` RouteModel`, como se puede ver más arriba, añadimos un controlador ` onStatusChanged `, que llama a la función ` showRouteList() `, la cual actualiza el ` routeInfoModel`:
routeInfoModel.clear()
if (routeModel.count > 0) {
for (var i = 0; i < routeModel.get(0).segments.length; i++) {
routeInfoModel.append({
"instruction": routeModel.get(0).segments[i].maneuver.instructionText,
"distance": Helper.formatDistance(routeModel.get(0).segments[i].maneuver.distanceToNextInstruction)
});
}
}© 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.