Тип QML PlaceSearchModel

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

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

Свойства

• categories : список<Category>
• count : int
• favoritesMatchParameters : VariantMap
• favoritesPlugin : Плагин
• incremental : bool
• limit : int
• nextPagesAvailable : bool
• 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()

}

Пейджинг

PlaceSearchModel API имеет ограниченную поддержку пейджинга. Функции 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 : Плагин

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

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

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

incremental : bool

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

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

limit : int

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

nextPagesAvailable : bool

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

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

plugin : Plugin

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

previousPagesAvailable : bool

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

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

recommendationId : string

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

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

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

searchArea : variant

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

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

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

searchTerm : string

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

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

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

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

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

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

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

void cancel()

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

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

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

Variant data(int index, string role)

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

string errorString()

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

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

void nextPage()

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

void previousPage()

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

void reset()

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

void update()

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

Во время обновления модели состояние модели status установлено в PlaceSearchModel.Loading. Если модель успешно обновлена, состояние status установлено в PlaceSearchModel.Ready, а при неудачном завершении — в 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, этот метод ничего не делает.