En esta página

Place QML Type

El tipo «Lugar» representa una ubicación que constituye un punto de interés. Más información...

Import Statement: import QtLocation 6.12
Since: QtLocation 5.5

Propiedades

Métodos

Descripción detallada

El tipo «Place» representa una ubicación física con metadatos adicionales que describen dicha ubicación. A diferencia de los tipos « Location », « Address » y « geoCoordinate », que se utilizan para describir dónde se encuentra una ubicación. Las propiedades básicas de un «Place» son su « name » y su « location ».

Los objetos «Place» suelen obtenerse a partir de un modelo de búsqueda y, por lo general, solo tienen definidas sus propiedades básicas. La propiedad « detailsFetched » puede utilizarse para comprobar si es necesario recuperar más valores de propiedades de « Plugin ». Esto puede hacerse invocando el método « getDetails()». El progreso de la operación de obtención se puede supervisar mediante la propiedad status, que se establecerá en Place.Fetching mientras se están obteniendo los detalles.

El tipo Place cuenta con numerosas propiedades que contienen información sobre la ubicación. Los detalles sobre cómo ponerse en contacto con el lugar están disponibles en la propiedad contactDetails. También se dispone de propiedades de conveniencia para obtener el phone principal, fax, email y website.

A cada lugar se le asignan cero o más « categories ». Las categorías suelen utilizarse al buscar un tipo concreto de lugar, como un restaurante o un hotel. Algunos lugares cuentan con un objeto « ratings », que ofrece una indicación de la calidad del lugar.

Los metadatos del lugar los proporciona un « supplier », que puede exigir que se muestre un mensaje de « attribution » al usuario cuando se consultan los detalles del lugar.

Los lugares tienen un icon asociado que puede utilizarse para representar un lugar en un mapa o para decorar un delegado en una vista.

Los lugares pueden tener asociado contenido enriquecido adicional. El contenido enriquecido compatible actualmente incluye descripciones editoriales, reseñas e imágenes. Estos se exponen como un conjunto de modelos para recuperar el contenido. Las descripciones editoriales del lugar están disponibles a través de la propiedad editorialModel. Las reseñas del lugar están disponibles a través de la propiedad reviewModel. Se puede acceder a una galería de imágenes del lugar mediante la propiedad imageModel.

Los lugares pueden tener atributos adicionales que no están incluidos en la API formal. La propiedad extendedAttributes permite acceder a ellos. El tipo de atributos ampliados disponibles es específico de cada Plugin.

Un «Place» casi siempre está vinculado a un « plugin ». La propiedad « plugin » debe establecerse antes de que sea posible llamar a « save()», « remove()» o « getDetails()». Las propiedades « reviewModel », « imageModel » y « editorialModel » solo son válidas cuando la propiedad « plugin » está establecida.

Guardar un lugar

Si el Plugin lo admite, el tipo Place se puede utilizar para guardar un lugar. En primer lugar, crea un nuevo Place y configura sus propiedades:

Place {
    id: myPlace
    plugin: myPlugin

    name: "Brisbane Technology Park"
    location: Location {
        address: Address {
            street: "53 Brandl Street"
            city: "Eight Mile Plains"
            postalCode: "4113"
            country: "Australia"
        }
        coordinate {
            latitude: -27.579646
            longitude: 153.100308
        }
    }

    visibility: Place.PrivateVisibility
}

A continuación, invoca el método save():

    myPlace.save();

La propiedad ` status ` cambiará a `Place.Saving` y, a continuación, a `Place.Ready` si el guardado se ha realizado correctamente, o a `Place.Error` si se produce un error.

Si se establece la propiedad ` placeId `, el backend actualizará un lugar existente; de lo contrario, creará uno nuevo. Si se realiza correctamente, la propiedad ` placeId ` se actualizará con el identificador del lugar recién guardado.

Advertencias

Actualmente, la API de Places está diseñada únicamente para guardar los datos de « core ». No se admite el almacenamiento de contenido enriquecido, como imágenes y reseñas, ni de datos como el proveedor y la valoración. Por lo general, un gestor ignorará estos campos al guardar y puede que se muestre un mensaje de advertencia si están rellenados.

La API de Places solo admite el almacenamiento de los siguientes datos básicos:

  • nombre
  • ID del lugar
  • ubicación
  • datos de contacto
  • icono
  • categorías (nombres similares a etiquetas para describir un lugar)
  • ámbito de visibilidad

Es posible que los proveedores solo admitan un subconjunto de estos. Consulta la documentación del complemento para obtener más detalles.

La API de Places no admite explícitamente el almacenamiento de propiedades como la valoración, los atributos extendidos, las imágenes, las reseñas, los artículos editoriales y el proveedor.

Guardado entre complementos

A la hora de guardar lugares entre plugins, hay algunos aspectos que hay que tener en cuenta. Algunos campos de un lugar, como el ID, las categorías y los iconos, son entidades específicas de cada plugin. Por ejemplo, es posible que las categorías de un gestor no sean reconocidas por otro. Por lo tanto, no es posible intentar guardar un lugar directamente de un plugin a otro.

En general, se recomienda gestionar el guardado entre plugins como si se tratara de guardar en favorites, tal y como se explica en la sección «Favoritos». Sin embargo, existe otro enfoque que consiste en crear un nuevo lugar, establecer su plugin (de destino) y, a continuación, utilizar el método copyFrom() para copiar los detalles del lugar original. El uso de ` copyFrom()` solo copia los datos compatibles con el complemento de destino; los datos específicos del complemento, como el identificador del lugar, no se copian. Una vez realizada la copia, el lugar se encuentra en un estado adecuado para ser guardado.

El siguiente fragmento de código ofrece un ejemplo de cómo guardar un lugar en un complemento diferente utilizando el método ` copyFrom `:

var place = Qt.createQmlObject('import QtLocation; Place { }', parent);
place.plugin = destinationPlugin;
place.copyFrom(originalPlace);
place.save();

Eliminación de un lugar

Para eliminar un lugar, asegúrate de que existe un objeto Place con una propiedad placeId válida y llama a su método remove(). La propiedad status cambiará a Place.Removing y, a continuación, a Place.Ready si el guardado se ha realizado correctamente, o a Place.Error si se produce un error.

Favoritos

La API de lugares admite el concepto de favoritos. Los favoritos se implementan generalmente mediante dos complementos: el primero suele ser una fuente de lugares de solo lectura (complemento de origen) y el segundo, un complemento de lectura/escritura (complemento de destino), que se utiliza para almacenar los lugares del complemento de origen como favoritos.

Cada Place tiene una propiedad «favorite» destinada a contener el lugar correspondiente del complemento de destino (el lugar en sí mismo procede del complemento de origen). Dado que están disponibles tanto la instancia original del lugar como la de los favoritos, el desarrollador puede elegir qué propiedades mostrar al usuario. Por ejemplo, el favorito puede tener un nombre modificado que debería mostrarse en lugar del nombre original.

Text { text: place.favorite ? place.favorite.name : place.name }

A continuación se muestra cómo guardar una nueva instancia de «favorito». Se realiza una llamada para crear/inicializar la instancia de «favorito» y, a continuación, se guarda la instancia.

place.initializeFavorite(destinationPlugin);
//if necessary customizations to the favorite can be made here.
//...
place.favorite.save();

A continuación se muestra cómo eliminar un favorito:

place.favorite.remove();
    ...
//check successful removal of the favorite by monitoring its status.
//once that is done we can assign null to the favorite
place.favorite = null;

El objeto ` PlaceSearchModel ` tiene una propiedad `favoritesPlugin`. Si se establece esta propiedad, cualquier lugar encontrado durante una búsqueda se compara con el `favoritesPlugin` para ver si existe un lugar favorito correspondiente. Si es así, se establece la propiedad `favorite` del objeto `Place`; de lo contrario, dicha propiedad permanece nula.

Véase también PlaceSearchModel.

Documentación de propiedades

attribution : string

Esta propiedad contiene una cadena de atribución en formato de texto enriquecido correspondiente al lugar. Es posible que algunos proveedores exijan que la atribución se muestre al usuario cada vez que se visualice un lugar. El contenido de esta propiedad debe mostrarse al usuario si no está vacío.

categories : list<Category> [read-only]

Esta propiedad contiene la lista de categorías a las que pertenece este lugar. Las categorías que se pueden asignar a un lugar son específicas de cada plugin.

contactDetails : ContactDetails [read-only]

Esta propiedad contiene la información de contacto de este lugar, por ejemplo, un número de teléfono o la URL de una página web. Esta propiedad es un mapa de objetos « contactDetail ».

detailsFetched : bool [read-only]

Esta propiedad indica si se han recuperado los datos del lugar. Si esta propiedad es «false», aún no se han recuperado los datos del lugar. La recuperación se puede realizar llamando al método getDetails().

Véase también getDetails().

editorialModel : EditorialModel [read-only]

Esta propiedad contiene un modelo que puede utilizarse para recuperar descripciones editoriales del lugar.

extendedAttributes : ExtendedAttributes [read-only]

Esta propiedad contiene los atributos ampliados de un lugar. Los atributos ampliados son información adicional sobre un lugar que no se recoge en las propiedades del mismo.

favorite : Place

Esta propiedad contiene la instancia favorita de un lugar.

icon : Icon

Esta propiedad contiene un icono gráfico que puede utilizarse para representar el lugar.

imageModel : ImageModel [read-only]

Esta propiedad contiene un modelo que puede utilizarse para obtener imágenes del lugar.

location : QtPositioning::Location

Esta propiedad contiene la ubicación del lugar, que puede utilizarse para obtener las coordenadas, la dirección y el rectángulo delimitador.

name : string

Esta propiedad contiene el nombre del lugar, que puede utilizarse para referirse a él.

placeId : string

Esta propiedad contiene el identificador único del lugar. El identificador del lugar solo tiene sentido para el Plugin que lo generó y no es transferible entre Plugins. No se garantiza que el identificador del lugar sea universalmente único, pero sí es único dentro del Plugin que lo generó.

Si solo se conoce el identificador del lugar, el resto de datos sobre el mismo pueden obtenerse de Plugin.

    place.plugin = myPlugin;
    place.placeId = "known-place-id";
    place.getDetails();

plugin : Plugin

Esta propiedad contiene la propiedad « Plugin », que proporciona esta ubicación y puede utilizarse para obtener más información sobre el servicio.

primaryEmail : string [read-only]

Esta propiedad contiene la dirección de correo electrónico principal del lugar. Si no se ha definido ningún dato de contacto de «correo electrónico» para este lugar, esta propiedad será una cadena vacía. Es equivalente a

    var primaryEmail;
    if (place.contactDetails["email"].length > 0)
        primaryEmail = place.contactDetails["email"][0].value;

primaryFax : string [read-only]

Esta propiedad contiene el número de fax principal del lugar. Si no se ha definido ningún dato de contacto de «fax» para este lugar, esta propiedad será una cadena vacía. Es equivalente a

    var primaryFax;
    if (place.contactDetails["fax"].length > 0)
        primaryFax = place.contactDetails["fax"][0].value;

primaryPhone : string [read-only]

Esta propiedad contiene el número de teléfono principal del lugar. Si no se ha definido ningún dato de contacto de «teléfono» para este lugar, esta propiedad será una cadena vacía. Es equivalente a:

    var primaryPhone;
    if (place.contactDetails["phone"].length > 0)
        primaryPhone = place.contactDetails["phone"][0].value;

primaryWebsite : string [read-only]

Esta propiedad contiene la URL principal del sitio web del lugar. Si no se ha definido ningún dato de contacto de «sitio web» para este lugar, esta propiedad será una cadena vacía. Es equivalente a

    var primaryWebsite;
    if (place.contactDetails["website"].length > 0)
        primaryWebsite = place.contactDetails["website"][0].value;

ratings : Ratings

Esta propiedad recoge las valoraciones del lugar. Las valoraciones ofrecen una indicación de la calidad del lugar.

reviewModel : ReviewModel [read-only]

Esta propiedad contiene un modelo que se puede utilizar para obtener opiniones sobre el lugar.

status : enumeration [read-only]

Esta propiedad indica el estado del lugar. Puede ser una de las siguientes opciones:

Place.ReadyNo se ha producido ningún error durante la última operación; se pueden realizar más operaciones en el lugar.
Place.SavingEl lugar se está guardando actualmente; no se puede realizar ninguna otra operación hasta que se haya completado.
Place.FetchingSe están recuperando los detalles del lugar; no se pueden realizar otras operaciones hasta que finalice el proceso.
Place.RemovingSe está eliminando el lugar; no se puede realizar ninguna otra operación hasta que finalice el proceso.
Lugar.ErrorSe ha producido un error durante la última operación; aún así, se pueden seguir realizando operaciones en el lugar.

El estado de un lugar se puede comprobar conectando la propiedad «status» a una función de gestión y, a continuación, haciendo que dicha función procese el cambio de estado.

place.statusChanged.connect(statusChangedHandler);
    ...
function statusChangedHandler() {
    if (statusChangedHandler.prevStatus === Place.Saving) {
        switch (place.status) {
        case Place.Ready:
            console.log('Save successful');
            break;
        case Place.Error:
            console.log('Save failed');
            break;
        default:
            break;
        }
    }
    statusChangedHandler.prevStatus = place.status;
}

supplier : Supplier

Esta propiedad indica quién es el proveedor de los datos sobre el lugar. El proveedor suele ser una empresa u organización que ha recopilado los datos sobre el lugar.

visibility : enumeration

Esta propiedad indica la visibilidad del lugar. Puede ser una de las siguientes:

Place.UnspecifiedVisibilityLa visibilidad del lugar no está especificada; se utilizará la visibilidad predeterminada de Plugin.
Place.DeviceVisibilityEl lugar está limitado al dispositivo actual. El lugar no se transferirá fuera del dispositivo.
Place.PrivateVisibilityEl lugar es privado para el usuario actual. El lugar puede transferirse a un servicio en línea, pero solo será visible para el usuario actual.
Place.PublicVisibilityEl lugar es público.

Ten en cuenta que la visibilidad no afecta a cómo se muestra el lugar en la interfaz de usuario de una aplicación en el dispositivo. En cambio, define la semántica de uso compartido del lugar.

Documentación de métodos

void copyFrom(Place original)

Copia los datos de un lugar de « original » a este lugar. Solo se copian los datos compatibles con el complemento de este lugar; los datos específicos del complemento, como el identificador del lugar, no se copian.

string errorString()

Devuelve una cadena que describe el error de la última operación. Si la última operación se ha completado correctamente, la cadena estará vacía.

void getDetails()

Este método comienza a recuperar los detalles del lugar.

La propiedad « status » cambiará a «Place.Fetching» mientras se realiza la recuperación. Si se realiza correctamente, se actualizarán las propiedades del objeto, « status » se establecerá en «Place.Ready» y « detailsFetched » se establecerá en «true». Si se produce un error, « status » se establecerá en «Place.Error». Se puede utilizar el método « errorString()» para obtener los detalles del error.

void initializeFavorite(Plugin destinationPlugin)

Crea una instancia «favorita» para el lugar que se va a guardar en el complemento de destino destinationPlugin. Este método no realiza ninguna acción si la propiedad «favorite» no es « null ».

void remove()

Este método realiza una operación de eliminación en el lugar.

La propiedad status cambiará a Place.Removing mientras se está llevando a cabo la operación de guardado. Si se realiza correctamente, status se establecerá en Place.Ready. Si se produce un error, status se establecerá en Place.Error. El método errorString() se puede utilizar para obtener los detalles del error.

void save()

Este método realiza una operación de guardado en el lugar.

La propiedad ` status ` cambiará a `Place.Saving` mientras se está llevando a cabo la operación de guardado. Si se realiza correctamente, la propiedad ` status ` se establecerá en `Place.Ready`. En caso de error, la propiedad ` status ` se establecerá en `Place.Error`. Se puede utilizar el método ` errorString()` para obtener los detalles del error.

Si la propiedad placeId estaba vacía anteriormente, se le asignará un valor válido automáticamente durante una operación de guardado correcta.

Ten en cuenta que un ` PlaceSearchModel ` llamará a ` Place::getDetails ` en cualquier lugar en el que detecte una actualización. Una consecuencia de esto es que, cada vez que se guarde correctamente un `Place` de un ` PlaceSearchModel `, se realizará una recuperación de los detalles del lugar, lo que dará lugar a una secuencia de cambios de estado de ` Saving`, ` Ready`, ` Fetching` y ` Ready`.

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