MapQuickItem QML Type
El tipo `MapQuickItem` muestra un objeto ` Qt Quick ` arbitrario en un mapa. Más información...
| Import Statement: | import QtLocation 6.12 |
| Since: | QtLocation 5.5 |
- Lista de todos los miembros, incluidos los heredados
- MapQuickItem forma parte del complemento QML Maps.
Propiedades
- anchorPoint : point
- autoFadeIn : bool
- coordinate : coordinate
- sourceItem : object
- zoomLevel : real
Descripción detallada
El tipo MapQuickItem se utiliza para colocar un objeto Qt Quick arbitrario en un mapa, en una ubicación y con un tamaño específicos. A diferencia de lo que ocurre cuando se coloca un elemento flotante sobre el mapa, un MapQuickItem seguirá el desplazamiento (y, opcionalmente, el zoom) del mapa como si estuviera sobre la superficie del mismo.
La propiedad ` sourceItem ` contiene el elemento ` Qt Quick ` que se va a dibujar, que puede ser de cualquier tipo visible.
Posicionamiento y tamaño
El posicionamiento del `MapQuickItem` en el mapa se controla mediante dos propiedades: ` coordinate ` y ` anchorPoint`. Si solo se establece ` coordinate `, se especifica una coordenada de longitud/latitud en la que se colocará el elemento. La coordenada establecida se alineará con la esquina superior izquierda del elemento contenido cuando se muestre en pantalla.
La propiedad anchorPoint permite alinear la coordenada con otras partes del elemento, además de la esquina superior izquierda, estableciendo un número de píxeles de desplazamiento del elemento. Una forma sencilla de entenderlo es tener en cuenta que el punto indicado por anchorPoint en el propio elemento es el punto que se alineará con la coordinate especificada cuando se muestre.
Además de estar anclado al mapa, el MapQuickItem puede, opcionalmente, seguir la escala del mapa y cambiar de tamaño cuando se amplía o se reduce el mapa. Este comportamiento se controla mediante la propiedad zoomLevel. El comportamiento por defecto, si no se establece « zoomLevel », es que el elemento se dibuje «en la pantalla» en lugar de «en el mapa», de modo que su tamaño permanezca igual independientemente del nivel de zoom del mapa.
Rendimiento
El rendimiento de un MapQuickItem suele ser similar al del elemento Qt Quick que contiene por sí solo. La sobrecarga añadida corresponde a una traslación y (posiblemente) a un escalado del elemento original, así como a una transformación de la longitud y la latitud a la posición en pantalla.
Limitaciones
Nota: Debido a un detalle de implementación, los elementos colocados dentro de un `MapQuickItem` tendrán un elemento ` parent ` que no es el propio `MapQuickItem`. Haz referencia al `MapQuickItem` mediante su ` id` y evita el uso de ` anchor ` en el ` sourceItem`.
Ejemplo de uso
El siguiente fragmento de código muestra un `MapQuickItem` que contiene un objeto `Image` para mostrar un marcador en el mapa. Esta estrategia se utiliza para mostrar los marcadores del mapa en el ejemplo `MapViewer`.
MapQuickItem {
id: marker
anchorPoint.x: image.width/4
anchorPoint.y: image.height
HoverHandler {
id: hoverHandler
}
TapHandler {
id: tapHandler
acceptedButtons: Qt.RightButton
gesturePolicy: TapHandler.WithinBounds
onTapped: {
mapview.currentMarker = -1
for (var i = 0; i< mapview.markers.length; i++){
if (marker == mapview.markers[i]){
mapview.currentMarker = i
break
}
}
mapview.showMarkerMenu(marker.coordinate)
}
}
DragHandler {
id: dragHandler
grabPermissions: PointerHandler.CanTakeOverFromItems | PointerHandler.CanTakeOverFromHandlersOfDifferentType
}
sourceItem: Image {
id: image
}
}
Documentación de las propiedades
anchorPoint : point
Esta propiedad determina qué punto de la tabla de correspondencias ( sourceItem ) se alineará con la coordenada del mapa.
autoFadeIn : bool
Esta propiedad determina si el elemento aparece gradualmente al ampliar el mapa partiendo de niveles de zoom muy bajos. Por defecto, el valor es « true ». Si se establece esta propiedad en « false », el elemento del mapa tendrá siempre la opacidad especificada con la propiedad « QtQuick::Item::opacity », cuyo valor por defecto es 1,0.
coordinate : coordinate
Esta propiedad contiene la coordenada de anclaje del elemento « MapQuickItem ». El punto del elemento « sourceItem » especificado por « anchorPoint » se mantiene alineado con esta coordenada cuando se dibuja en el mapa.
En la imagen siguiente, hay tres MapQuickItems que son idénticos salvo por el valor de sus propiedades « anchorPoint ». Los valores de « anchorPoint » de cada uno de ellos aparecen escritos encima del elemento.

sourceItem : object
Esta propiedad contiene el elemento de origen que se dibujará en el mapa.
zoomLevel : real
Esta propiedad controla el comportamiento de escalado del contenido de MapQuickItem. En concreto, al configurar esta propiedad es posible elegir entre objetos que se dibujan en la pantalla (y cuyo tamaño se mide en píxeles de pantalla) y aquellos que se dibujan en la superficie del mapa (cuyo tamaño varía según el nivel de zoom del mapa).
El valor por defecto de esta propiedad es 0,0, lo que corresponde a dibujar el objeto en la superficie de la pantalla. Si se establece en otro valor, el objeto se dibujará en la superficie del mapa. El valor (si no es cero) especifica el nivel de zoom en el que el objeto será visible a una escala de 1:1 (es decir, donde los píxeles del objeto y los píxeles de la pantalla son iguales). A niveles de zoom inferiores a este, el objeto aparecerá más pequeño, y a niveles de zoom superiores, aparecerá más grande. Esto contrasta con el caso en que esta propiedad se establece en cero, en el que el objeto mantiene el mismo tamaño en pantalla en todos los niveles de zoom.
© 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.