En esta página

Map QML Type

El tipo «Mapa» muestra un mapa. Más información...

Import Statement: import QtLocation 6.12
Since: QtLocation 5.0

Propiedades

Señales

Métodos

Descripción detallada

El tipo «Mapa» se utiliza para mostrar un mapa o una imagen de la Tierra, con la capacidad de mostrar también objetos interactivos vinculados a la superficie del mapa.

Existen diversas formas de visualizar la superficie terrestre en dos dimensiones, pero todas ellas implican algún tipo de proyección: una relación matemática entre las coordenadas tridimensionales (latitud, longitud y altitud) y las coordenadas bidimensionales (X e Y en píxeles) en la pantalla.

Las diferentes fuentes de datos cartográficos pueden utilizar distintas proyecciones y, desde el punto de vista del tipo «Mapa», las tratamos como una unidad sustituible: el complemento de mapa. Un complemento de mapa consta de una fuente de datos, así como de todos los demás detalles necesarios para mostrar sus datos en pantalla.

El complemento «Mapa» actualmente en uso se encuentra en la propiedad « plugin » del elemento «Mapa». Para mostrar cualquier imagen en un elemento «Mapa», deberá configurar esta propiedad. Consulte el tipo « Plugin » para obtener una descripción de cómo recuperar un complemento adecuado para su uso.

La región geográfica que se muestra en el elemento «Map» se denomina «ventana de visualización» (viewport) y viene definida por las propiedades « center » y « zoomLevel ». La propiedad « center » contiene un « geoCoordinate » que especifica el centro de la ventana de visualización, mientras que « zoomLevel » controla la escala del mapa. Consulte cada una de estas propiedades para obtener más detalles sobre sus valores.

Cuando se muestra el mapa, cada coordenada geográfica visible se asigna a unas coordenadas X e Y en píxeles en la pantalla. Para realizar conversiones entre ambas, Map proporciona las funciones « toCoordinate » y « fromCoordinate », que son de utilidad general.

Objetos de Map

Los objetos relacionados con el mapa pueden declararse dentro del cuerpo de un objeto Map en Qt Quick y aparecerán automáticamente en el mapa. Para añadir un objeto mediante programación, asegúrate primero de que se haya creado con el Map como padre (por ejemplo, en un argumento de Component::createObject). A continuación, llama al método ` addMapItem ` en el `Map`, si el tipo de este objeto es uno de los siguientes: ` MapCircle`, ` MapRectangle`, ` MapPolyline`, ` MapPolygon`, ` MapRoute ` o ` MapQuickItem`. También existe el método correspondiente ` removeMapItem ` para realizar la operación inversa y eliminar cualquiera de los tipos de objetos de mapa mencionados anteriormente del `Map`.

Mover objetos del mapa, cambiar su tamaño o modificar su forma no suele requerir ninguna interacción especial con el propio Map: al cambiar estas propiedades en un objeto del mapa, la visualización se actualiza automáticamente.

Rendimiento

Los mapas se representan mediante OpenGL (ES) y la pila Qt Scene Graph, por lo que ofrecen un rendimiento bastante bueno cuando se dispone de hardware con aceleración GL.

En el caso de los mapas «en línea», el ancho de banda de la red y la latencia pueden influir considerablemente en la percepción que tiene el usuario del rendimiento. Para mitigar esto, se lleva a cabo un almacenamiento en caché exhaustivo, aunque dicha mitigación no siempre es perfecta.

En general, los elementos de mapa grandes y complejos, como los polígonos y las polilíneas con un gran número de vértices, pueden afectar negativamente al rendimiento de la interfaz de usuario.

Ejemplo de uso

El siguiente fragmento de código muestra un mapa sencillo y el tipo de complemento necesario para utilizarlo. El mapa está centrado en Oslo, Noruega, con un nivel de zoom 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)
        }
    }
}

Elemento del mapa centrado en Oslo, con un nivel de zoom 14

Documentación de propiedades

activeMapType : mapType

Acceso a la propiedad « map type » actualmente activa.

Esta propiedad se puede configurar para cambiar el map type activo. Consulta la propiedad supportedMapTypes para conocer los valores posibles.

Véase también mapType.

bearing : real [since QtLocation 5.9]

Esta propiedad contiene el rumbo del mapa. El valor por defecto es 0. Si el complemento utilizado para el mapa admite el rumbo, el rango válido para este valor está comprendido entre 0 y 360. Si el complemento utilizado para el mapa no admite el rumbo, cambiar esta propiedad no tendrá ningún efecto.

Esta propiedad se introdujo en QtLocation 5.9.

center : coordinate

Esta propiedad contiene la coordenada que ocupa el centro de la ventana de visualización del mapa. Las coordenadas centrales no válidas se ignoran.

El valor por defecto es una coordenada válida arbitraria.

color : color

Esta propiedad establece el color de fondo del elemento del mapa.

copyrightsVisible : bool

Esta propiedad determina la visibilidad del aviso de derechos de autor. El aviso suele aparecer en la esquina inferior izquierda. Por defecto, esta propiedad está configurada en « true ».

Nota: Muchos proveedores de mapas exigen que el aviso sea visible como parte de los términos y condiciones. Consulte la documentación correspondiente del proveedor antes de desactivar este aviso.

error : enumeration [read-only]

Esta propiedad de solo lectura contiene el último error producido por el proveedor del servicio de mapas.

  • Map.NoError: no se ha producido ningún error.
  • Map.NotSupportedError: la propiedad del complemento de mapas no se ha configurado o no hay ningún gestor de mapeo asociado al complemento.
  • Map.UnknownParameterError: el complemento no ha reconocido uno de los parámetros que se le han proporcionado.
  • Map.MissingRequiredParameterError: el complemento no ha encontrado uno de los parámetros que esperaba.
  • Map.ConnectionError: el complemento no ha podido conectarse a su servicio de fondo o a su base de datos.

Véase también QGeoServiceProvider::Error.

errorString : string [read-only]

Esta propiedad de solo lectura contiene la representación textual del último error del proveedor de mapeo. Si no se ha producido ningún error, se devuelve una cadena vacía.

También puede devolverse una cadena vacía si se ha producido un error que no tiene una representación textual asociada.

Véase también QGeoServiceProvider::errorString().

fieldOfView : real [since QtLocation 5.9]

Esta propiedad indica el campo de visión de la cámara utilizada para visualizar el mapa, expresado en grados. Si no se ha configurado la propiedad «plugin» del mapa, o si el plugin no admite la visualización de mapas, el valor es de 45 grados.

Ten en cuenta que al modificar este valor también se modifica implícitamente la distancia entre la cámara y el mapa, de modo que, con un ángulo de inclinación de 0 grados, la imagen resultante es idéntica independientemente del valor que se utilice para esta propiedad.

Para obtener más información sobre este parámetro, consulta los artículos de Wikipedia sobre «Campo de visión » y «Ángulo de visión».

Esta propiedad se introdujo en QtLocation 5.9.

Véase también minimumFieldOfView y maximumFieldOfView.

mapItems : list<MapItem> [read-only]

Devuelve la lista de todos los elementos del mapa sin ningún orden concreto. Estos elementos incluyen tanto los declarados de forma estática como parte de la declaración del tipo, como los declarados de forma dinámica (addMapItem, MapItemView).

Véase también addMapItem, removeMapItem y clearMapItems.

mapReady : bool [read-only]

Esta propiedad indica si el mapa se ha inicializado correctamente y está listo para su uso. Algunos métodos, como « fromCoordinate » y « toCoordinate », no funcionarán hasta que el mapa esté listo. Debido a la arquitectura de « Map », se recomienda utilizar la señal emitida por esta propiedad en lugar de « Component.onCompleted », para asegurarse de que todo funciona según lo esperado.

maximumFieldOfView : real [since QtLocation 5.9]

Esta propiedad indica el campo de visión máximo válido para el mapa, en grados.

El campo de visión de inclinación mínimo establecido por el complemento « plugin » utilizado constituye un límite superior para esta propiedad. Si la propiedad « plugin » no está definida o el complemento no admite la función de mapeo, esta propiedad es « 179 ».

Esta propiedad se introdujo en QtLocation 5.9.

Véase también fieldOfView y minimumFieldOfView.

maximumTilt : real [since QtLocation 5.9]

Esta propiedad contiene la inclinación máxima válida para el mapa, expresada en grados.

La inclinación máxima definida por el plugin utilizado constituye un límite superior para esta propiedad. Si la propiedad plugin no está configurada o el complemento no admite la función de inclinación, esta propiedad es 89.5.

Desde la versión QtLocation 5.12, los complementos pueden restringir adicionalmente este valor en función del nivel de zoom actual.

Esta propiedad se introdujo en QtLocation 5.9.

Véase también tilt y minimumTilt.

maximumZoomLevel : real

Esta propiedad contiene el nivel de zoom máximo válido para el mapa.

El nivel de zoom máximo viene definido por el complemento « plugin » utilizado. Si la propiedad « plugin » no está configurada o el complemento no admite la visualización de mapas, esta propiedad es « 30 ».

minimumFieldOfView : real [since QtLocation 5.9]

Esta propiedad indica el campo de visión mínimo válido para el mapa, expresado en grados.

El campo de visión de inclinación mínimo establecido por el « plugin » utilizado constituye un límite inferior para esta propiedad. Si la propiedad « plugin » no está definida o el complemento no admite la función de mapeo, esta propiedad es « 1 ».

Esta propiedad se introdujo en QtLocation 5.9.

Véase también fieldOfView y maximumFieldOfView.

minimumTilt : real [since QtLocation 5.9]

Esta propiedad indica la inclinación mínima válida para el mapa, expresada en grados.

La inclinación mínima definida por el plugin utilizado constituye el límite inferior de esta propiedad. Si la propiedad plugin no está configurada o el complemento no admite la función de mapeo, esta propiedad es 0.

Desde la versión QtLocation 5.12, los complementos pueden restringir adicionalmente este valor en función del nivel de zoom actual.

Esta propiedad se introdujo en QtLocation 5.9.

Véase también tilt y maximumTilt.

minimumZoomLevel : real

Esta propiedad indica el nivel de zoom mínimo válido para el mapa.

El nivel de zoom mínimo definido por el complemento « plugin » utilizado constituye el límite inferior de esta propiedad. Sin embargo, el valor devuelto también depende del tamaño del lienzo y puede ser superior al valor especificado por el usuario o al nivel de zoom mínimo definido por el complemento utilizado, con el fin de evitar que el mapa sea más pequeño que la ventana gráfica en cualquiera de sus dimensiones.

Si la propiedad « plugin » no está configurada o el complemento no admite la función de zoom, el valor de esta propiedad es « 0 ».

plugin : Plugin

Esta propiedad contiene el complemento que proporciona la funcionalidad de asignación.

Se trata de una propiedad de escritura única. Una vez que el mapa tenga un complemento asociado, se ignorará cualquier intento de modificación del mismo.

supportedMapTypes : list<mapType> [read-only]

Esta propiedad de solo lectura contiene el conjunto de valores de « map types » que admite este mapa.

Véase también « activeMapType ».

tilt : real [since QtLocation 5.9]

Esta propiedad almacena la inclinación del mapa, expresada en grados. El valor por defecto es 0. El rango válido para este valor es [ minimumTilt, maximumTilt ]. Si el complemento utilizado para el mapa no admite la inclinación, cambiar esta propiedad no tendrá ningún efecto.

Esta propiedad se introdujo en QtLocation 5.9.

Véase también minimumTilt y maximumTilt.

visibleArea : rect

Esta propiedad contiene el área visible dentro del elemento QML «Map». Se trata de un rectángulo cuyas coordenadas son relativas al elemento «Map». Su tamaño se ajustará al tamaño del elemento «Map». Si «visibleArea» es nulo, significa que todo el «Map» está visible.

visibleRegion : geoShape

Esta propiedad contiene la región que ocupa el área de visualización del mapa. La cámara se sitúa en el centro de la forma y en el nivel de zoom entero más alto posible que permita que toda la forma sea visible en la pantalla. Esto implica que, si se vuelve a leer esta propiedad poco después de haberla establecido, el área devuelta será igual o mayor que el área establecida.

Al establecer esta propiedad se modifican implícitamente las propiedades ` center ` y ` zoomLevel ` del mapa. Cualquier valor establecido previamente en dichas propiedades quedará anulado.

Nota: A partir de Qt 5.14, esta propiedad proporciona notificaciones de cambio.

zoomLevel : real

Esta propiedad establece el nivel de zoom del mapa.

Cuanto mayor sea el valor del nivel de zoom, mayor será el nivel de detalle. Los niveles de zoom siempre son no negativos. El valor por defecto es 8,0. Dependiendo del complemento que se utilice, los valores fuera del rango [minimumZoomLevel, maximumZoomLevel], que representa el rango para el que hay mosaicos disponibles, pueden aceptarse o limitarse.

Documentación de Signal

copyrightLinkActivated(string link)

Esta señal se emite cuando el usuario hace clic en un enlace link en el aviso de derechos de autor. La aplicación debe abrir el enlace en un navegador o mostrar su contenido al usuario.

Nota: El controlador correspondiente es onCopyrightLinkActivated.

Documentación del método

void addMapItem(MapItem item)

Añade la dirección item indicada al mapa (por ejemplo, MapQuickItem, MapCircle). Si el objeto ya se encuentra en el mapa, no se volverá a añadir.

A modo de ejemplo, imagina el caso en el que tienes un ` MapCircle ` que representa tu posición actual:

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

Nota: Los MapItemViews no se pueden añadir con este método.

Véase también mapItems, removeMapItem y clearMapItems.

void addMapItemGroup(MapItemGroup itemGroup)

Añade al mapa los elementos que contiene el archivo « itemGroup » especificado (por ejemplo, MapQuickItem, MapCircle).

Véase también MapItemGroup y removeMapItemGroup.

void addMapItemView(MapItemView itemView)

Añade itemView al mapa.

Véase también MapItemView y removeMapItemView.

void alignCoordinateToPoint(coordinate coordinate, QPointF point)

Alinea coordinate con point. Este método amplía de forma efectiva la funcionalidad que ofrece la propiedad qml center, permitiendo alinear una coordenada con un punto del elemento Map distinto de su centro. Esto resulta útil en aquellas aplicaciones en las que el centro de la escena (por ejemplo, un cursor) no debe situarse exactamente en el centro del mapa.

Si el mapa está inclinado y coordinate se encuentra detrás de la cámara, o si el mapa no está listo (véase mapReady), llamar a este método no tendrá ningún efecto.

El lanzamiento de esta API con Qt 5.10 es una vista previa tecnológica.

Véase también center.

void clearData()

Borra los datos del mapa recopilados por el complemento seleccionado actualmente.

Nota: Este método eliminará los archivos almacenados en caché.

Véase también plugin.

void clearMapItems()

Elimina todos los elementos y grupos de elementos del mapa.

Véase también mapItems, addMapItem, removeMapItem, addMapItemGroup y removeMapItemGroup.

void fitViewportToGeoShape(geoShape, margins)

Ajusta la ventana de visualización a una forma geográfica específica geoShape. Las coordenadas margins se expresan en píxeles de pantalla.

Nota: Si la proyección utilizada por el complemento no es WebMercator y el complemento no dispone de la función de ajuste a la forma, este método no realizará ninguna acción.

Véase también visibleRegion.

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

Si no se proporciona ningún argumento, ajusta la ventana de visualización actual a los límites de todos los elementos del mapa. La cámara se sitúa en el centro de los elementos del mapa y en el nivel de zoom entero más alto posible que permita que todos los elementos del mapa sean visibles en pantalla. Si se proporciona items, ajusta la ventana de visualización actual únicamente a los límites de los elementos del mapa especificados.

Nota: Este método incorporó el argumento opcional ` items ` a partir de Qt 5.15. En versiones anteriores, este método ajustaba el mapa a todos los elementos del mapa.

Véase también fitViewportToVisibleMapItems.

void fitViewportToVisibleMapItems()

Ajusta la ventana de visualización actual a los límites de todos los elementos visibles del mapa. La cámara se sitúa en el centro de los elementos del mapa y en el nivel de zoom entero más alto posible que permita que todos los elementos del mapa sean visibles en pantalla.

Véase también fitViewportToMapItems.

point fromCoordinate(coordinate coordinate, bool clipToViewPort)

Devuelve la posición relativa al elemento del mapa que corresponde a coordinate.

Si clipToViewPort es true o no se ha proporcionado, devuelve un QPointF no válido si coordinate no se encuentra dentro de la ventana gráfica actual.

void pan(int dx, int dy)

Comienza a desplazar el mapa dx píxeles a lo largo del eje x y dy píxeles a lo largo del eje y.

Los valores positivos de dx desplazan el mapa hacia la derecha; los valores negativos, hacia la izquierda. Los valores positivos de dy desplazan el mapa hacia abajo; los valores negativos, hacia arriba.

Durante el desplazamiento, los valores de « center » y « zoomLevel » pueden variar.

void prefetchData()

Sugerencia opcional que permite que el mapa se precargue durante este periodo de inactividad

void removeMapItem(MapItem item)

Elimina el elemento « item » especificado del mapa (por ejemplo, MapQuickItem, MapCircle). Si el elemento «MapItem» no existe o no se ha añadido previamente al mapa, el método no realiza ninguna acción.

Véase también mapItems, addMapItem y clearMapItems.

void removeMapItemGroup(MapItemGroup itemGroup)

Elimina « itemGroup » y los elementos que contiene del mapa.

Véase también MapItemGroup y addMapItemGroup.

void removeMapItemView(MapItemView itemView)

Elimina de la tabla «Map» el objeto ` itemView ` y los elementos que este ha instanciado.

Véase también MapItemView y addMapItemView.

void setBearing(real bearing, coordinate coordinate)

Establece el rumbo del mapa en bearing, girándolo alrededor de coordinate. Si el complemento utilizado para el mapa admite el rumbo, el rango válido para bearing está comprendido entre 0 y 360. Si el complemento utilizado para el mapa no admite el rumbo, o si el mapa está inclinado y coordinate se encuentra detrás de la cámara, o si el mapa no está listo (véase mapReady), llamar a este método no tendrá ningún efecto.

El lanzamiento de esta API con Qt 5.10 es una versión preliminar tecnológica.

coordinate toCoordinate(QPointF position, bool clipToViewPort)

Devuelve la coordenada que corresponde al « position » en relación con el elemento del mapa.

Si clipToViewPort es true o no se ha proporcionado, devuelve una coordenada no válida si position no se encuentra dentro de la ventana de visualización actual.

© 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.