PlaceSearchModel QML Type

검색 결과를 확인할 수 있습니다. 더 보기...

• 상속된 멤버를 포함한 모든 멤버 목록

속성

• categories : list<Category>
• count : int
• favoritesMatchParameters : VariantMap
• favoritesPlugin : Plugin
• incremental : bool (since QtLocation 5.12)
• limit : int
• nextPagesAvailable : bool
• plugin : Plugin
• previousPagesAvailable : bool
• recommendationId : string
• relevanceHint : enumeration
• searchArea : variant
• searchTerm : string
• status : enum
• visibilityScope : enum

신호

• dataChanged()

방법

• void cancel()
• Variant 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 역할이 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
import QtPositioning
import QtLocation

PlaceSearchModel {
    id: searchModel

    plugin: myPlugin

    searchTerm: "food"
    searchArea: QtPositioning.circle(startCoordinate, 5000 /* 5 km radius */);

    Component.onCompleted: update()

}

페이징

PlaceSearchModel API는 페이징을 제한적으로 지원합니다. nextPage() 및 previousPage() 함수와 limit 속성을 사용하여 페이징된 검색 결과에 접근할 수 있습니다. limit 속성이 설정된 경우, 검색 결과 페이지에는 최대 limit 개의 항목(place result 유형)이 포함됩니다. 예를 들어, 백엔드에 총 5개의 검색 결과 [a, b, c, d, e]가 있고, 첫 페이지가 표시되며 limit이 3으로 설정된 경우 a, b, c가 반환됩니다. nextPage()는 d, e를 반환합니다. nextPagesAvailable 및 previousPagesAvailable 속성을 사용하여 다음 페이지를 확인할 수 있습니다. 현재 이 API는 백엔드에서 사용 가능한 항목의 총 수를 가져오는 기능을 지원하지 않습니다. nextPage(), previousPage() 및 limit 에 대한 지원 여부는 plugin 에 따라 다를 수 있습니다.

CategoryModel 및 QPlaceManager도 참조하십시오 .

속성 문서

categories : list<Category> [read-only]

이 속성은 검색 시 사용될 카테고리 목록을 포함합니다. 반환되는 검색 결과는 해당 카테고리 중 적어도 하나와 일치하는 장소에 대한 것입니다.

count : int [read-only]

이 속성은 모델이 가진 결과의 개수를 나타냅니다.

단, 이는 백엔드에서 제공되는 전체 검색 결과의 수를 의미하지는 않습니다. 현재 API에서는 전체 검색 결과의 수를 지원하지 않습니다.

favoritesMatchParameters : VariantMap

이 속성은 favoritesPlugin 에서 검색 결과 항목이 즐겨찾기와 어떻게 매칭되는지를 지정하는 데 사용되는 일련의 매개변수를 포함합니다.

기본적으로 매개변수 맵은 비어 있으며, 이는 즐겨찾기 플러그인이 대체 식별자를 사용하여 매칭함을 의미합니다. 일반적으로 애플리케이션 개발자는 이 속성을 설정할 필요가 없습니다.

즐겨찾기 플러그인이 대체 식별자를 통한 매칭을 지원하지 않는 경우에는, 플러그인 설명서를 참조하여 정확히 어떤 키-값 매개변수를 설정해야 하는지 확인해야 합니다.

favoritesPlugin : Plugin

이 속성은 즐겨찾기를 검색하는 데 사용될 ‘ Plugin ’를 포함합니다. 검색 결과 중 ‘favoritesPlugin’에서 상호 참조되거나 일치하는 장소가 있는 경우, 해당 장소의 ‘ favorite ’ 속성은 ‘favoritesPlugin’의 해당 ‘ Place ’로 설정됩니다.

favouritesPlugin이 설정되어 있지 않은 경우, 검색 결과에 포함된 장소의 favorite 속성은 항상 null이 됩니다.

Favorites도 참조하십시오 .

incremental : bool [since QtLocation 5.12]

이 속성은 페이징이 ` PlaceSearchModel`에 미치는 영향을 제어합니다. `true`인 경우, ` previousPage ` 또는 ` nextPage `를 호출해도 모델이 재설정되지 않고, 대신 새로운 결과가 모델에 추가됩니다. 기본값은 `false`입니다.

이 속성은 QtLocation 5.12에서 도입되었습니다.

limit : int

이 속성은 반환될 항목 수의 상한을 지정합니다.

nextPagesAvailable : bool [read-only]

이 속성은 검색 결과 페이지가 하나 더 있는지, 아니면 여러 개가 더 있는지 여부와 관계없이 적용됩니다.

nextPage()도 참조하십시오 .

plugin : Plugin

이 속성은 검색을 수행하는 데 사용될 Plugin 를 포함하고 있습니다.

previousPagesAvailable : bool [read-only]

이 속성은 이전 검색 결과 페이지가 하나이든 여러 개이든 상관없이 적용됩니다.

previousPage()도 참조하십시오 .

recommendationId : string

이 속성에는 유사한 장소에 대한 추천을 찾기 위해 사용되는 placeId가 저장됩니다.

relevanceHint : enumeration

이 속성은 검색 쿼리에 사용되는 관련성 힌트를 포함합니다. 이 힌트는 결과의 순위를 결정하는 것이 아니라, 이를 돕기 위해 제공자에게 제공됩니다. 예를 들어, 거리 힌트는 더 가까운 장소에 더 높은 순위를 부여할 수 있지만, 결과가 반드시 거리에 따라 엄격하게 정렬된다는 의미는 아닙니다. 제공자는 이 힌트를 완전히 무시할 수도 있습니다.

searchArea : variant

이 속성은 검색 영역을 지정합니다. 모델이 반환하는 검색 결과는 이 검색 영역 내에 포함됩니다.

이 속성이 ‘ geoCircle ’로 설정된 경우, ‘ radius ’ 속성은 설정하지 않아도 되며, 이 경우 ‘ Plugin ’가 검색에 적합한 반경을 자동으로 선택합니다.

검색 영역 지정에 대한 지원 여부는 ` plugin ` 백엔드 구현에 따라 다를 수 있습니다. 예를 들어, 일부는 검색 중심점만 지원하는 반면, 다른 일부는 지리적 직사각형만 지원할 수 있습니다.

searchTerm : string

이 속성은 쿼리에 사용된 검색어를 저장합니다. 검색어는 자유 형식의 텍스트 문자열입니다.

status : enum [read-only]

이 속성은 모델의 상태를 나타냅니다. 다음 중 하나일 수 있습니다:

visibilityScope : enum

이 속성은 검색 대상 장소의 공개 범위를 지정합니다. 검색 결과에는 지정된 공개 범위에 해당하는 장소만 표시됩니다.

가시성 범위는 다음 중 하나일 수 있습니다:

Signal 문서

dataChanged()

이 신호는 기본 데이터 저장소에 중대한 변경 사항이 발생했을 때 전송됩니다.

애플리케이션은 이 신호에 대해 자체적인 판단에 따라 대응해야 합니다. 모델이 제공하는 데이터가 최신 상태가 아닐 수 있으므로 언젠가는 모델을 다시 업데이트해야 하지만, 사용자가 아무런 조치를 취하지 않았는데도 결과가 변경된다면 즉각적인 재업데이트는 사용자에게 혼란을 줄 수 있습니다.

해당 핸들러는 onDataChanged 입니다.

메서드 문서

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, 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)

proposedSearchIndex 인덱스의 ProposedSearchResult를 기반으로 모델을 업데이트합니다. 모델에는 제안된 검색 조건에 맞는 장소 목록이 채워집니다. 모델 상태는 ‘ PlaceSearchModel.Loading’으로 설정됩니다. 모델 업데이트가 성공하면 상태는 ‘ PlaceSearchModel.Ready’로 설정됩니다. 오류가 발생하면 상태는 ‘ PlaceSearchModel.Error’로 설정되고 모델이 지워집니다.

proposedSearchIndex 가 ProposedSearchResult를 참조하지 않는 경우, 이 메서드는 아무 작업도 수행하지 않습니다.