Тип QML PlaceSearchModel

Предоставляет доступ к результатам поиска мест. Подробнее...

• Список всех членов, включая унаследованные

Свойства

• categories : list<Category>
• count : int
• favoritesMatchParameters : VariantMap
• favoritesPlugin : Plugin
• limit : int
• nextPagesAvailable : bool
• plugin : Plugin
• previousPagesAvailable : bool
• recommendationId : string
• relevanceHint : перечисление
• searchArea : variant
• searchTerm : string
• status : перечисление
• visibilityScope : перечисление

Методы

• void cancel()
• void data(int index, string role)
• string errorString()
• void nextPage()
• void previousPage()
• void reset()
• void update()
• void updateWith(int proposedSearchIndex)

Подробное описание

PlaceSearchModel предоставляет модель результатов поиска мест в пределах searchArea. Свойства searchTerm и categories могут быть установлены для ограничения результатов поиска местами, соответствующими этим критериям.

Модель PlaceSearchModel возвращает результаты как спонсируемых, так и органических поисков. У спонсируемых результатов будет установлено значение sponsored для роли sponsored.

Модель возвращает данные для следующих ролей:

Типы результатов поиска

Роль type может принимать следующие значения:

Часто полезно использовать Loader для создания делегата, который будет выбирать разные Component в зависимости от типа результата поиска.

Component {
    id: resultDelegate
    Loader {
        Component {
            id: placeResult

            Column {
                Text { text: title }
                Text { text: place.location.address.text }
            }
        }

        Component {
            id: otherResult
            Text { text: title }
        }

        sourceComponent: type == PlaceSearchModel.PlaceResult ? placeResult :
                                                                otherResult
    }
}

Обнаружение обновлённых и удалённых мест

Модель PlaceSearchModel прослушивает места, которые были обновлены или удалены из бэкэнда плагина. Если она обнаруживает, что место было обновлено, и это место присутствует в модели, то она вызывает Place::getDetails для обновления деталей. Если она обнаруживает, что место было удалено, то соответствующим образом место будет удалено из модели, если оно присутствует.

Пример

Следующий пример показывает, как использовать PlaceSearchModel для поиска пиццерий вблизи заданного положения. Модели предоставляются searchTerm и searchArea, и используется update() для выполнения запроса поиска. Обратите внимание, что модель не извлекает результаты поиска по частям, а выполняет один запрос при запуске update(). Свойство count устанавливается в количество результатов поиска, возвращаемых при запросе.

import QtQuick 2.0
import QtPositioning 5.5
import QtLocation 5.6

PlaceSearchModel {
    id: searchModel

    plugin: myPlugin

    searchTerm: "pizza"
    searchArea: QtPositioning.circle(startCoordinate);

    Component.onCompleted: update()

}

Пагинация

API PlaceSearchModel имеет ограниченную поддержку пагинации. Функции nextPage() и previousPage(), а также свойство limit могут использоваться для доступа к результатам поиска с пагинацией. При установке свойства limit страница результата поиска содержит не более limit элементов (типа результата места). Например, если бэкэнд имеет 5 результатов поиска в общей сложности [a,b,c,d,e], и предполагается, что отображается первая страница, и установлено ограничение в 3, то возвращаются a,b,c. nextPage() вернёт d,e. Свойства nextPagesAvailable и previousPagesAvailable могут использоваться для проверки наличия дополнительных страниц. В настоящий момент API не поддерживает способ получения общего количества элементов, доступных из бэкэнда. Обратите внимание, что поддержка nextPage(), previousPage() и limit может варьироваться в зависимости от plugin.

См. также CategoryModel и QPlaceManager.

Документация по свойствам

categories : list<Category>

Это свойство содержит список категорий, которые будут использоваться при поиске. Возвращаемые результаты поиска будут относиться к местам, которые соответствуют хотя бы одной из категорий.

count : int

Это свойство содержит количество результатов модели.

Обратите внимание, что оно не относится к общему количеству результатов поиска, доступных в бэкэнде. Общее количество результатов поиска в настоящее время API не поддерживается.

favoritesMatchParameters : VariantMap

Это свойство содержит набор параметров, используемых для указания способа сопоставления мест результатов поиска с избранными в favoritesPlugin.

По умолчанию карта параметров пуста и подразумевает, что плагин избранных сопоставляет места по альтернативным идентификаторам. Как правило, разработчику приложения не нужно устанавливать это свойство.

В случаях, когда плагин избранных не поддерживает сопоставление по альтернативным идентификаторам, необходимо обратиться к документации по плагину, чтобы точно определить, какие параметры пары ключ-значение необходимо установить.

favoritesPlugin : Plugin

Это свойство содержит Plugin, который будет использоваться для поиска избранных. Любые места из поиска, которые могут быть перекрестно проверены или сопоставлены в favoritesPlugin, будут иметь своё свойство favorite, установленное на соответствующее Place из favoritesPlugin.

Если favoritesPlugin не установлен, свойство favorite мест в результатах всегда будет равно null.

См. также Избранные.

limit : int

Это свойство содержит предел количества элементов, которые будут возвращены.

nextPagesAvailable : bool

Это свойство указывает, доступны ли одна или несколько дополнительных страниц результатов поиска.

См. такжеnextPage().

plugin : Plugin

Это свойство содержит плагин, который будет использоваться для выполнения поиска.

previousPagesAvailable : bool

Это свойство указывает, доступны ли одна или несколько предыдущих страниц результатов поиска.

См. такжеpreviousPage().

recommendationId : string

Это свойство содержит placeId, который будет использоваться для поиска рекомендаций по похожим местам.

relevanceHint : enumeration

Это свойство содержит подсказку релевантности, используемую в запросе поиска. Подсказка предоставляется поставщику, чтобы помочь, но не диктовать ранжирование результатов. Например, подсказка расстояния может присваивать более близким местам более высокий рейтинг, но это не обязательно означает, что результаты будут строго упорядочены по расстоянию. Поставщик может вообще проигнорировать подсказку.

searchArea : variant

Это свойство содержит область поиска. Результаты поиска, возвращаемые моделью, будут находиться внутри области поиска.

Если это свойство установлено в geocircle, его свойство radius может быть не установлено, в этом случае плагин выберет подходящий радиус для поиска.

Поддержка указания области поиска может различаться в зависимости от реализации бэкенда плагина. Например, некоторые могут поддерживать только центр поиска, а другие только геопрямоугольники.

searchTerm : string

Это свойство содержит поисковый термин, используемый в запросе. Поисковый термин — это текстовая строка произвольной формы.

status : enum

Это свойство содержит состояние модели. Оно может быть одним из следующих:

visibilityScope : enum

Это свойство содержит область видимости мест для поиска. В результатах поиска будут отображаться только места с указанной видимостью.

Область видимости может быть одной из следующих:

Документация по методам

void cancel()

Немедленно отменяет текущую операцию поиска и устанавливает состояние модели в PlaceSearchModel.Ready. Модель сохраняет любые результаты поиска, которые у нее были до начала операции.

Если операция не выполняется, вызов cancel() не оказывает никакого эффекта.

См. такжеupdate() и status.

void data(int index, string role)

Возвращает данные для заданного role в указанной строке index.

string errorString() const

Это свойство только для чтения содержит текстовое представление последней ошибки модели поиска места. Если ошибка не произошла или модель была очищена, возвращается пустая строка.

Пустая строка также может быть возвращена, если произошла ошибка, которая не имеет связанного текстового представления.

void nextPage()

Обновляет модель, чтобы отобразить следующую страницу результатов поиска. Если следующей страницы нет, этот метод ничего не делает.

void previousPage()

Обновляет модель, чтобы отобразить предыдущую страницу результатов поиска. Если предыдущей страницы нет, этот метод ничего не делает.

void reset()

Сбрасывает модель. Все результаты поиска очищаются, любые ожидающие запросы прерываются, и возможные ошибки очищаются. Состояние модели будет установлено в PlaceSearchModel.Null.

void update()

Обновляет модель на основе предоставленных параметров запроса. Модель будет заполнена списком мест, соответствующих параметрам поиска, заданным свойствами типа. Критерии поиска задаются путем установки свойств, таких как searchTerm, categories, searchArea и limit. Поддержка этих свойств может различаться в зависимости от плагина. update() Затем набор критериев отправляется в плагин для обработки.

Пока модель обновляется, состояние модели status устанавливается в PlaceSearchModel.Loading. Если модель успешно обновлена, состояние status устанавливается в PlaceSearchModel.Ready, в то время как при неудачном завершении состояние status устанавливается в PlaceSearchModel.Error, и модель очищается.

PlaceSearchModel {
    id: model
    plugin: backendPlugin
    searchArea: QtPositioning.circle(QtPositioning.coordinate(10, 10))
    ...
}

MouseArea {
    ...
    onClicked: {
        model.searchTerm = "pizza";
        model.categories = null;  //not searching by any category
        model.searchArea.center.latitude = -27.5;
        model.searchArea.center.longitude = 153;
        model.update();
    }
}

См. такжеcancel() и status.

void updateWith(int proposedSearchIndex)

Обновляет модель на основе ProposedSearchResult с индексом proposedSearchIndex. Модель будет заполнена списком мест, соответствующих предложенному поиску. Состояние модели будет установлено в PlaceSearchModel.Loading. Если модель обновлена успешно, состояние будет установлено в PlaceSearchModel.Ready. При возникновении ошибки состояние будет установлено в PlaceSearchModel.Error, и модель очистится.

Если proposedSearchIndex не ссылается на ProposedSearchResult, этот метод ничего не делает.