En esta página

Lugares (QML)

El ejemplo «Lugares» muestra cómo buscar lugares y acceder al contenido relacionado.

Ejemplo de «Lugares» con un cuadro de búsqueda y un mapa de Oslo en el que aparece un marcador con la etiqueta «The Qt Company»

El ejemplo «Lugares» muestra cómo buscar lugares. En concreto, muestra cómo se puede obtener información adicional, como reseñas, imágenes y contenido relacionado.

Ejecución del ejemplo

Puedes ejecutar el ejemplo desde:

El ejemplo funciona con cualquiera de los complementos de servicios geográficos disponibles. Sin embargo, 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 adopta la forma:

--plugin.<parameter name> <parameter value>

Consulte 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 Qt Location OpenStreetMap, que no requiere ningún parámetro.

Descripción general

El ejemplo «Lugares» presenta una ventana de aplicación en la que se muestra un mapa. En la parte superior de la ventana hay un cuadro de búsqueda que se utiliza para introducir una consulta de búsqueda de lugares. Para buscar un lugar, introduce un término de búsqueda en el cuadro de texto y haz clic en el icono de la lupa. Para buscar un lugar por categoría, haz clic en el icono de categorías para mostrar la lista de categorías disponibles y selecciona la categoría deseada. La búsqueda de lugares se centrará en aquellos que se encuentren cerca de la ubicación actual que se muestra en el mapa.

En algunos complementos, el cuadro de búsqueda ofrece sugerencias de términos de búsqueda cuando se introducen tres o más caracteres. Al seleccionar una de las sugerencias, se realizará una búsqueda de lugares con el texto de búsqueda seleccionado.

Al hacer clic en un resultado de búsqueda, se mostrarán los detalles sobre el lugar. Si un lugar tiene contenido enriquecido (artículos, reseñas e imágenes), se puede acceder a ellos mediante los botones de la página de detalles. Para encontrar lugares similares, haz clic en el botón «Buscar similares».

Se puede cambiar el proveedor de servicios geográficos accediendo al menú «Proveedor».

Visualización de categorías

Antes de poder realizar una búsqueda por categoría, es necesario recuperar la lista de categorías disponibles. Para ello, hay que crear una CategoryModel.

CategoryModel {
    id: categoryModel
    hierarchical: true
}

El tipo « CategoryModel » proporciona un modelo de las categorías disponibles. Puede ofrecer una lista plana o un modelo de árbol jerárquico. En este ejemplo, utilizamos un modelo de árbol jerárquico, estableciendo la propiedad « hierarchical » en «true». La propiedad « plugin » se establece durante la inicialización del ejemplo.

A continuación, creamos un ` ListView ` para mostrar el modelo de categorías.

ListView {
    id: root
    property var categoryModel
    property var rootIndex

    signal searchCategory(var category)
    signal showSubcategories(var index)

    snapMode: ListView.SnapToItem

    model: DelegateModel {
        id: delegeteDataModel
        model: root.categoryModel
        rootIndex: root.rootIndex
        delegate: CategoryDelegate {
            width: ListView.view.width
            onSearchCategory: root.searchCategory(category);
            onShowSubcategories: root.showSubcategories(delegeteDataModel.modelIndex(index));
        }
    }
}

Dado que se utiliza un modelo jerárquico, se necesita un DelegateModel para proporcionar la funcionalidad de navegación. Si se utilizara un modelo de lista plana, la vista podría utilizar directamente la propiedad CategoryModel.

La propiedad rootIndex establece el índice raíz del DelegateModel. Las categorías se muestran mediante el CategoryDelegate, que proporciona dos señales. La señal onShowSubcategories emite la señal showSubcategories() con el índice raíz establecido en el índice actual, lo que provoca que se muestren las subcategorías de la categoría seleccionada. El controlador onSearchCategory emite la señal searchCategory() con un parámetro «category» que indica qué categoría concreta se ha seleccionado.

El CategoryDelegate muestra el nombre de la categoría y emite la señal searchCategory() cuando se hace clic en el Label:

Label {
    id: labelItem
    text: category.name
    anchors.left: icon.right
    anchors.right: parent.right
    anchors.verticalCenter: parent.verticalCenter
}

TapHandler {
    id: tapHanlder
    onTapped: {
        if (model.hasModelChildren) {
            root.showSubcategories()
        } else {
            root.searchCategory()
        }
    }
}

Presentación de sugerencias de búsqueda

El tipo « PlaceSearchSuggestionModel » se utiliza para obtener términos de búsqueda sugeridos a partir de un término de búsqueda introducido parcialmente.

Cada vez que se modifica el término de búsqueda introducido, se activa una nueva búsqueda de sugerencias.

SearchBar {
    id: searchBar
    onSearchTextChanged: function (searchText) {
        if (searchText.length >= 3 && suggestionModel != null) {
            suggestionModel.searchTerm = searchText;
            suggestionModel.update();
        }
    }
}

Las sugerencias solo se consultan si el término de búsqueda tiene una longitud de tres o más caracteres.

Cuando cambia el estado del « PlaceSearchSuggestionModel », se muestran sugerencias de búsqueda.

PlaceSearchSuggestionModel {
    id: suggestionModel
    searchArea: searchRegion

    onStatusChanged: {
        if (status == PlaceSearchSuggestionModel.Ready)
            stackView.showSuggestions()
    }
}

El objeto principal en el estado «SuggestionsShown» es el « ListView », que muestra las sugerencias de búsqueda.

ListView {
    id: suggestionView
    property var suggestionModel
    signal suggestionSelected(string text)

    model: suggestionModel
    delegate: Item {
        width: ListView.view.width
        height: label.height * 1.5
        Label {
            id: label
            text: suggestion
        }
        MouseArea {
            anchors.fill: parent
            onClicked: suggestionSelected(suggestion)
        }
    }
}

Se utiliza un objeto Label como delegado para mostrar el texto de la sugerencia. Al hacer clic en el término de búsqueda sugerido, se actualiza dicho término y se activa una búsqueda de lugares utilizando la sugerencia de búsqueda.

Búsqueda de lugares

El tipo PlaceSearchModel se utiliza para buscar lugares.

PlaceSearchModel {
    id: placeSearchModel
    searchArea: searchRegion

    function searchForCategory(category) {
        searchTerm = "";
        categories = category;
        recommendationId = "";
        searchArea = searchRegion
        limit = -1;
        update();
    }

    function searchForText(text) {
        searchTerm = text;
        categories = null;
        recommendationId = "";
        searchArea = searchRegion
        limit = -1;
        update();
    }

    function searchForRecommendations(placeId) {
        searchTerm = "";
        categories = null;
        recommendationId = placeId;
        searchArea = null;
        limit = -1;
        update();
    }

    onStatusChanged: {
        switch (status) {
        case PlaceSearchModel.Ready:
            if (count > 0)
                stackView.showPlaces()
            else
                stackView.showMessage(qsTr("Search Place Error"),qsTr("Place not found !"))
            break;
        case PlaceSearchModel.Error:
            stackView.showMessage(qsTr("Search Place Error"),errorString())
            break;
        }
    }
}

En primer lugar, se configuran algunas de las propiedades del modelo, que se utilizarán para formar la solicitud de búsqueda. La propiedad « searchArea » se establece en el objeto «searchRegion», que es un « geoCircle » cuyo centro está vinculado a la ubicación actual que se muestra en « Map ».

Por último, definimos tres funciones auxiliares: `searchForCategory()`, `searchForText() ` y `searchForRecommendations() `, que establecen las propiedades ` categories `, ` searchTerm ` o ` recommendationId ` e invocan el método ` update()` para iniciar la búsqueda de lugares. Los resultados de la búsqueda se muestran en un ` ListView`.

ListView {
    id: searchView

    property var placeSearchModel
    signal showPlaceDetails(var place, var distance)
    signal showMap()

    model: placeSearchModel
    delegate: SearchResultDelegate {
        width: ListView.view.width
        onShowPlaceDetails: function (place, distance) { searchView.showPlaceDetails(place, distance) }
        onSearchFor: function (query) { placeSearchModel.searchForText(query) }
    }

    footer: RowLayout {
        width: parent.width

        Button {
            text: qsTr("Previous")
            enabled: placeSearchModel.previousPagesAvailable
            onClicked: placeSearchModel.previousPage()
            Layout.alignment: Qt.AlignHCenter
        }

        Button {
            text: qsTr("Clear")
            onClicked: {
                placeSearchModel.reset()
                showMap()
            }
            Layout.alignment: Qt.AlignHCenter
        }

        Button {
            text: qsTr("Next")
            enabled: placeSearchModel.nextPagesAvailable
            onClicked: placeSearchModel.nextPage()
            Layout.alignment: Qt.AlignHCenter
        }
    }
}

El delegado utilizado en ListView, SearchResultDelegate, está diseñado para gestionar múltiples tipos de resultados de búsqueda a través de un objeto Loader. Para los resultados de tipo PlaceResult, el delegado es:

Component {
    id: placeComponent
    Item {
        id: placeRoot
        width: root.width
        height: Math.max(icon.height, 3 * placeName.height)

        Rectangle {
            anchors.fill: parent
            color: "#44ffffff"
            visible: mouse.pressed
        }

        Rectangle {
            anchors.fill: parent
            color: "#dbffde"
            visible: model.sponsored !== undefined ? model.sponsored : false

            Label {
                text: qsTr("Sponsored result")
                horizontalAlignment: Text.AlignRight
                anchors.right: parent.right
                anchors.bottom: parent.bottom
                font.pixelSize: 8
                visible: model.sponsored !== undefined ? model.sponsored : false
            }
        }

        GridLayout {
            rows: 2
            columns: 2
            anchors.fill: parent
            anchors.leftMargin: 30
            flow: GridLayout.TopToBottom

            Image {
                // anchors.verticalCenter: parent.verticalCenter
                id:icon
                source: place.favorite ? Qt.resolvedUrl("../resources/star.png") : place.icon.url()
                Layout.rowSpan: 2
            }

            Label {
                id: placeName
                text: place.favorite ? place.favorite.name : place.name
                Layout.fillWidth: true
            }

            Label {
                id: distanceText
                font.italic: true
                text: Helper.formatDistance(distance)
                Layout.fillWidth: true
            }
        }

        Rectangle {
            anchors.left: parent.left
            anchors.right: parent.right
            anchors.margins: 15
            height: 1
            color: "#46a2da"
        }

        MouseArea {
            id: mouse
            anchors.fill: parent
            onClicked: {
                if (model.type === undefined || type === PlaceSearchModel.PlaceResult) {
                    if (!place.detailsFetched)
                        place.getDetails();
                    root.showPlaceDetails(model.place, model.distance);
                }
            }
        }
    }
}

Visualización del contenido de un lugar

Los lugares pueden tener contenido enriquecido adicional, como artículos, reseñas e imágenes. Se accede al contenido enriquecido a través de un conjunto de modelos. Por lo general, los modelos de contenido no los crea directamente el desarrollador de la aplicación, sino que se obtienen de las propiedades editorialModel, reviewModel y imageModel del tipo Place.

ListView {
    id:view
    property Place place
    signal showEditorial(var editorial)
    model: place.editorialModel
    delegate: EditorialDelegate {
        width: ListView.view.width
        onShowEditorial: view.showEditorial(model)
    }
}

Proyecto de ejemplo en @code.qt.io

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