Map QML Type

El tipo Mapa muestra un mapa. Más...

• Lista de todos los miembros, incluyendo los heredados
• Map es parte de QML Maps Plugin.

Propiedades

• activeMapType : mapType
• bearing : real (since QtLocation 5.9)
• center : coordinate
• color : color
• copyrightsVisible : bool
• error : enumeration
• errorString : string
• fieldOfView : real (since QtLocation 5.9)
• mapItems : list<MapItem>
• mapReady : bool
• maximumFieldOfView : real (since QtLocation 5.9)
• maximumTilt : real (since QtLocation 5.9)
• maximumZoomLevel : real
• minimumFieldOfView : real (since QtLocation 5.9)
• minimumTilt : real (since QtLocation 5.9)
• minimumZoomLevel : real
• plugin : Plugin
• supportedMapTypes : list<mapType>
• tilt : real (since QtLocation 5.9)
• visibleArea : rect
• visibleRegion : geoShape
• zoomLevel : real

Señales

• copyrightLinkActivated(string link)

Métodos

• void addMapItem(MapItem item)
• void addMapItemGroup(MapItemGroup itemGroup)
• void addMapItemView(MapItemView itemView)
• void alignCoordinateToPoint(coordinate coordinate, QPointF point)
• void clearData()
• void clearMapItems()
• void fitViewportToGeoShape(geoShape, margins)
• void fitViewportToMapItems(list<MapItems> items)
• void fitViewportToVisibleMapItems()
• point fromCoordinate(coordinate coordinate, bool clipToViewPort)
• void pan(int dx, int dy)
• void prefetchData()
• void removeMapItem(MapItem item)
• void removeMapItemGroup(MapItemGroup itemGroup)
• void removeMapItemView(MapItemView itemView)
• void setBearing(real bearing, coordinate coordinate)
• coordinate toCoordinate(QPointF position, bool clipToViewPort)

Descripción detallada

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

Existe una gran variedad de formas de visualizar la superficie de la Tierra en 2 dimensiones, pero todas ellas implican algún tipo de proyección: una relación matemática entre las coordenadas 3D (latitud, longitud y altitud) y las coordenadas 2D (X e Y en píxeles) en la pantalla.

Diferentes fuentes de datos cartográficos pueden utilizar diferentes proyecciones y, desde el punto de vista del tipo Mapa, las tratamos como una unidad reemplazable: el complemento Mapa. Un plugin de Mapa consiste en una fuente de datos, así como todos los demás detalles necesarios para mostrar sus datos en pantalla.

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

La región geográfica mostrada en el elemento Mapa se denomina ventana gráfica y se define mediante las propiedades center y zoomLevel. La propiedad center contiene una coordenada que especifica el centro de la ventana gráfica, mientras que zoomLevel controla la escala del mapa. Consulte cada una de estas propiedades para obtener más información sobre sus valores.

Cuando se muestra el mapa, cada coordenada geográfica posible que sea visible se asignará a alguna coordenada X e Y de píxel en la pantalla. Para realizar conversiones entre ambas, Map proporciona las funciones toCoordinate y fromCoordinate, que son de utilidad general.

Objetos de mapa

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

Desplazar los objetos de mapa, cambiar su tamaño o modificar su forma normalmente no implica ninguna interacción especial con el propio mapa: si se modifican estas propiedades en un objeto de mapa, la visualización se actualizará automáticamente.

Rendimiento

Los mapas se renderizan utilizando OpenGL (ES) y la pila Qt Scene Graph, por lo que su rendimiento es bastante bueno cuando se dispone de hardware con aceleración GL.

En el caso de los mapas "en línea", el ancho de banda y la latencia de la red pueden contribuir en gran medida a la percepción del rendimiento por parte del usuario. Para mitigar este efecto, se utiliza una gran cantidad de memoria caché, pero esta mitigación no siempre es perfecta.

En general, los elementos de mapa grandes y complejos, como polígonos y 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 muestra un Mapa sencillo y el tipo de Plugin 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)
        }
    }
}

Documentación de propiedades

activeMapType : mapType

Acceso a la página map type activa en ese momento.

Esta propiedad puede establecerse para cambiar el map type activo. Véase la propiedad supportedMapTypes para los posibles valores.

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 Plugin utilizado para el Mapa soporta el rumbo, el rango válido para este valor está entre 0 y 360. Si el Plugin utilizado para el Mapa no soporta marcación, 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 gráfica. Las coordenadas centrales no válidas se ignoran.

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

color : color

Esta propiedad contiene el color de fondo del elemento mapa.

copyrightsVisible : bool

Esta propiedad mantiene la visibilidad del aviso de derechos de autor. El aviso se muestra normalmente en la esquina inferior izquierda. Por defecto, esta propiedad está establecida en true.

error : enumeration [read-only]

Esta propiedad de sólo lectura contiene el último error de proveedor de servicios de mapeo ocurrido.

• Mapa.NoError - No se ha producido ningún error.
• Map.NotSupportedError -No se ha establecido la propiedad del complemento de mapas o no hay ningún gestor de mapas 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 backend o base de datos.

Véase también QGeoServiceProvider::Error.

errorString : string [read-only]

Esta propiedad de sólo lectura contiene la presentació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 representación textual asociada.

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

fieldOfView : real [since QtLocation 5.9]

Esta propiedad contiene el campo de visión de la cámara utilizada para mirar el mapa, en grados. Si la propiedad plugin del mapa no está establecida, o el plugin no soporta mapeado, el valor es 45 grados.

Tenga en cuenta que al cambiar este valor también cambia 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 para cualquier valor utilizado para esta propiedad.

Para más información sobre este parámetro, consulte 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 en particular. Estos elementos incluyen elementos que fueron declarados estáticamente como parte de la declaración del tipo, así como elementos dinámicos (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 ser utilizado. Algunos métodos, como fromCoordinate y toCoordinate, no funcionarán antes de que el mapa esté listo. Debido a la arquitectura de Map, se aconseja utilizar la señal emitida para esta propiedad en lugar de Component.onCompleted, para asegurarse de que todo se comporta como se espera.

maximumFieldOfView : real [since QtLocation 5.9]

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

El campo de visión de inclinación mínima por el plugin utilizado es un límite superior para esta propiedad. Si la propiedad plugin no está establecida o el plugin no soporta 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, en grados.

La inclinación máxima definida por el plugin utilizado es un límite superior para esta propiedad. Si la propiedad plugin no está definida o el plugin no soporta mapeado, esta propiedad es 89.5.

Desde QtLocation 5.12, los plugins pueden restringir adicionalmente este valor dependiendo 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 máximo de zoom viene definido por la propiedad plugin utilizada. Si la propiedad plugin no está establecida o el plugin no soporta mapeo, esta propiedad es 30.

minimumFieldOfView : real [since QtLocation 5.9]

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

El campo de visión de inclinación mínima por el plugin utilizado es un límite inferior para esta propiedad. Si la propiedad plugin no está establecida o el plugin no soporta 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 contiene la inclinación mínima válida para el mapa, en grados.

La inclinación mínima definida por el plugin utilizado es un límite inferior para esta propiedad. Si la propiedad plugin no está definida o el plugin no soporta mapeado, esta propiedad es 0.

Desde QtLocation 5.12, los plugins 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 contiene el nivel de zoom mínimo válido para el mapa.

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

Si la propiedad plugin no está establecida o el plugin no admite el mapeado, esta propiedad es 0.

plugin : Plugin

Esta propiedad contiene el plugin que proporciona la funcionalidad de mapeo.

Se trata de una propiedad "write-once". Una vez que el mapa tiene un plugin asociado, cualquier intento de modificación del plugin será ignorado.

supportedMapTypes : list<mapType> [read-only]

Esta propiedad de sólo lectura contiene el conjunto de map types que admite este mapa.

Véase también activeMapType.

tilt : real [since QtLocation 5.9]

Esta propiedad contiene la inclinación del mapa, en grados. El valor por defecto es 0. El rango válido para este valor es [ minimumTilt, maximumTilt ]. Si el Plugin utilizado para el Mapa no soporta inclinación, cambiar esta propiedad no tendrá efecto.

Esta propiedad se introdujo en QtLocation 5.9.

Ver también minimumTilt y maximumTilt.

visibleArea : rect

Esta propiedad contiene el área visible dentro del elemento Map QML. Es un rect cuyas coordenadas son relativas al elemento Map. Su tamaño se ajustará al tamaño del elemento Map. Un visibleArea nulo significa que todo el Map es visible.

visibleRegion : geoShape

Esta propiedad contiene la región que ocupa la ventana gráfica del mapa. La cámara se sitúa en el centro de la forma, y en el mayor nivel de zoom integral posible que permita que toda la forma sea visible en la pantalla. Esto implica que al leer esta propiedad poco después de haber sido establecida el área devuelta es igual o mayor que el área establecida.

Al establecer esta propiedad se modifican implícitamente las propiedades center y zoomLevel del mapa. Cualquier valor previamente establecido para esas propiedades será anulado.

zoomLevel : real

Esta propiedad contiene el nivel de zoom del mapa.

Los valores mayores del nivel de zoom proporcionan más detalle. Los niveles de zoom son siempre no negativos. El valor por defecto es 8.0. Dependiendo del plugin en uso, los valores fuera del rango [minimumZoomLevel, maximumZoomLevel], que representan el rango para el que los mosaicos están disponibles, pueden ser aceptados, o fijados.

Documentación sobre señales

copyrightLinkActivated(string link)

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

Documentación del método

void addMapItem(MapItem item)

Añade el item dado al Mapa (por ejemplo MapQuickItem, MapCircle). Si el objeto ya está en el Mapa, no se añadirá de nuevo.

Como ejemplo, considere el caso en el que tiene un MapCircle que representa su 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)
    }
}

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

void addMapItemGroup(MapItemGroup itemGroup)

Añade al mapa los elementos contenidos en itemGroup (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 a point. Este método amplía efectivamente la funcionalidad ofrecida por la propiedad center qml, permitiendo alinear una coordenada a un punto del elemento Mapa 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 (ver mapReady), llamar a este método no tendrá ningún efecto.

El lanzamiento de esta API con Qt 5.10 es una Technology Preview.

Véase también center.

void clearData()

Borra los datos de mapa recogidos por el plugin actualmente seleccionado.

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 gráfica a una forma geográfica específica geoShape. Los margins están en píxeles de pantalla.

Véase también visibleRegion.

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

Si no se proporciona ningún argumento, ajusta la ventana gráfica 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 mayor nivel de zoom integral posible que permita que todos los elementos del mapa sean visibles en la pantalla. Si se proporciona items, la ventana gráfica actual se ajusta sólo a los límites de los elementos de mapa especificados.

Véase también fitViewportToVisibleMapItems.

void fitViewportToVisibleMapItems()

Ajusta la ventana gráfica 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 mayor nivel de zoom integral posible que permita que todos los elementos del mapa sean visibles en la 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 proporciona, entonces devuelve un QPointF inválido si coordinate no se encuentra dentro de la ventana gráfica actual.

void pan(int dx, int dy)

Inicia la panorámica del mapa en dx píxeles a lo largo del eje x y en dy píxeles a lo largo del eje y.

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

Durante la panorámica, center y zoomLevel pueden cambiar.

void prefetchData()

Sugerencia opcional que permite al mapa precargar durante este periodo de inactividad.

void removeMapItem(MapItem item)

Elimina el item dado del Mapa (por ejemplo MapQuickItem, MapCircle). Si el MapItem no existe o no se ha añadido previamente al mapa, el método no hace nada.

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 itemView y los elementos instanciados por él del Mapa.

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 plugin utilizado para el mapa soporta la orientación, el rango válido para bearing está entre 0 y 360. Si el plugin utilizado para el mapa no soporta la orientación, o si el mapa está inclinado y coordinate se encuentra detrás de la cámara, o si el mapa no está listo (ver mapReady), llamar a este método no tendrá ningún efecto.

El lanzamiento de esta API con Qt 5.10 es una Muestra de Tecnología.

coordinate toCoordinate(QPointF position, bool clipToViewPort)

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

Si clipToViewPort es true, o no se proporciona, devuelve una coordenada no válida si position no se encuentra dentro de la ventana gráfica actual.