Тип QML PlaceSearchModel

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

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

Свойства

• categories : список<Category>
• count : int
• favoritesMatchParameters : VariantMap
• favoritesPlugin : Plugin
• incremental : bool
• limit : int
• nextPagesAvailable : bool
• plugin : Plugin
• previousPagesAvailable : bool
• recommendationId : строка
• relevanceHint : перечисление
• searchArea : вариант
• searchTerm : строка
• status : перечисление
• visibilityScope : перечисление

Методы

• void cancel()
• Вариант data(int index, строка role)
• строка errorString()
• void nextPage()
• void previousPage()
• void reset()
• void update()
• void updateWith(int proposedSearchIndex)

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

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

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

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

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

Роль 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 : список<Category>

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

count : int

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

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

favoritesMatchParameters : VariantMap

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

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

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

favoritesPlugin : Plugin

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

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

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

incremental : bool

Это свойство контролирует, как постраничная навигация повлияет на PlaceSearchModel. Если значение истинно, вызов previousPage или nextPage не сбросит модель, а новые результаты будут добавлены в модель. По умолчанию значение ложно.

Это свойство было введено в QtLocation 5.12.

limit : int

Это свойство содержит ограничение на количество возвращаемых элементов.

nextPagesAvailable : bool

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

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

plugin : Plugin

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

previousPagesAvailable : bool

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

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

recommendationId : string

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

relevanceHint : enumeration

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

searchArea : variant

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

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

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

searchTerm : string

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

status : перечисление

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

visibilityScope : перечисление

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

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

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

void cancel()

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

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

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

Значение data(int index, string role)

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

string errorString()

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

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

void nextPage()

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

void previousPage()

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

void reset()

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

void update()

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

Пока модель обновляется, 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, этот метод ничего не делает.