QML Places API

개요

Places API를 사용하면 사용자가 관심 장소를 검색하고 주소 및 연락처 정보와 같은 세부 정보를 확인할 수 있습니다. 일부 장소에는 이미지나 리뷰와 같은 추가 콘텐츠가 연결되어 있을 수 있습니다. 또한 Places API를 사용하면 장소와 카테고리를 관리하여 저장하거나 삭제할 수 있습니다. 장소에는 경로, 도로 또는 교통 수단이 포함될 수도 있어 내비게이션 최적화 및 지원이 가능합니다. 내비게이션에 대한 자세한 내용은 routes를 참조하십시오.

기본 개념

플러그인

Plugin 는 백엔드를 추상화한 것입니다. 어떤 Plugin 는 REST 서버에서 장소에 접근할 수 있는 반면, 다른 는 로컬 데이터베이스에서 장소에 접근할 수 있습니다. 다음 코드는 "osm"이라는 이름을 제공하여 Plugin 객체를 생성합니다. Plugin 이름은 선택할 백엔드를 식별합니다. 플러그인에는 일련의 parameters 이 제공될 수도 있는데, 이는 본질적으로 키-값 쌍의 집합 형태를 띱니다. 지정할 수 있는 parameters 는 각 Plugin 백엔드에 따라 다릅니다. 사용 가능한 parameters 및 각 Plugin 의 세부 사항에 대한 문서는 플러그인 참조( Plugin References)를 참조하십시오.

Plugin {
    id: myPlugin
    name: "osm"
    //specify plugin parameters as necessary
    //PluginParameter {...}
    //PluginParameter {...}
    //...
}

모델, 뷰 및 델리게이트

QML Places API는 모델, 뷰 및 델리게이트라는 개념을 기반으로 구축되었습니다.

아래의 ‘일반적인 사용 사례’ 섹션에서는 이러한 개념들이 어떻게 결합되는지 구체적인 예시를 보여줍니다.

일반적인 사용 사례

장소 검색

검색은 ` PlaceSearchModel`을 통해 수행됩니다. ` plugin ` 속성은 검색 작업을 수행할 백엔드를 지정합니다. 검색 매개변수는 ` searchTerm ` 및 ` searchArea`과 같은 속성을 통해 제공될 수 있습니다. 그런 다음 ` update()` 메서드를 호출하여 검색 작업을 시작할 수 있습니다. 간편성을 위해 아래 코드 조각에서는 모델 생성이 완료된 후 update()을 호출하지만, 일반적으로는 버튼 클릭과 같은 사용자 동작에 반응하여 update()이 호출됩니다. 검색 작업이 진행되는 동안 PlaceSearchModel::status 속성은 Loading 상태로 전환되며, 작업이 성공적으로 완료되면 Ready 상태로 이동합니다.

PlaceSearchModel {
    id: searchModel

    plugin: myPlugin

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

    Component.onCompleted: update()

}

ListView를 사용하여 검색 결과 표시

ListView 를 사용하여 모델에서 찾은 검색 결과를 표시할 수 있습니다. 이 컨트롤은 결과가 표시될 시각적 영역을 정의하며, 아래 예시에서는 상위 컨트롤 전체를 채웁니다. ListView 에는 해당 영역이 플릭(flicking) 이벤트에 반응하고 적절하게 스크롤되도록 하는 기본 동작이 내장되어 있습니다.

아래 코드 조각에서 검색 모델이 ListView 의 model 속성에 할당되었습니다. 모델이 새로운 결과로 업데이트되면, ListView 은 모델의 새로운 데이터 항목을 반영하도록 자동으로 업데이트됩니다.

간단한 델리게이트가 ListView 의 delegate 속성에 바인딩되었습니다. PlaceSearchModel 는 일련의 roles 를 노출하며, 아래에서는 그 중 title 및 place 역할이 사용되었습니다. 이 역할들은 각각 string 및 Place 유형입니다. 기본적으로 뷰에 표시되어야 하는 각 데이터 항목에 대해, 뷰는 델리게이트를 호출하여 해당 항목의 시각적 표현을 생성합니다.

ListView { anchors.fill: parent model: searchModel delegate: Component { Row { spacing: 5 Marker { height: parent.height } Column { Text { text: title; font.bold: true } Text { text: place.location.address.text } } } } }

전체 소스 코드는 ‘장소 목록( Places List )’ 예제를 참조하십시오.

MapItemView를 사용하여 검색 결과 표시하기

ListView 대신, PlaceSearchModel 를 MapItemView 와 함께 사용하여 지도에 마커를 표시할 수 있습니다. 먼저 Map 를 사용하여 지도가 차지하는 시각적 영역을 정의합니다. 이 경우 지도 요소는 상위 요소의 전체 영역을 채웁니다. 지도를 제공하는 plugin 과 지도의 center 및 zoomLevel 과 같은 다른 속성도 지정됩니다.

Map 내부에서는 MapItemView 가 선언되어 있으며, 여기서 model 속성은 검색 모델로 설정되어 있고, MapQuickItem 로 구성된 delegate 가 마커 이미지를 표시하는 데 사용됩니다. 검색 모델이 찾은 모든 장소에 대해 마커가 표시됩니다. 델리게이트는 place 역할을 사용하여 마커의 위치를 지정합니다.

MapView { id: view anchors.fill: parent map.plugin: myPlugin; map.center: positionSource.lastSearchPosition map.zoomLevel: 13 MapItemView { model: searchModel parent: view.map delegate: MapQuickItem { coordinate: place.location.coordinate anchorPoint.x: image.width * 0.5 anchorPoint.y: image.height sourceItem: Column { Image { id: image; source: "marker.png" } Text { text: title; font.bold: true } } } } }

전체 소스 코드는 ‘장소 지도 ( Places Map )’ 예제를 참조하십시오.

장소 세부 정보 가져오기

대역폭을 절약하기 위해, 때때로 백엔드는 세부 정보가 부분적으로만 채워진 장소만 반환하기도 합니다. 이는 사용 가능한 모든 세부 정보가 가져왔는지 여부를 나타내는 Place::detailsFetched 속성을 통해 확인할 수 있습니다. 그렇지 않은 경우, Place::getDetails() 메서드를 호출하여 나머지 세부 정보를 가져올 수 있습니다.

if (!place.detailsFetched)
    place.getDetails();

장소 저장 및 삭제

일부 백엔드는 장소 저장 및 삭제를 지원할 수 있습니다. 이는 각각 ` Place::save()` 및 ` Place::remove()` 메서드를 호출하여 수행할 수 있습니다. Place 를 저장하려면, 저장할 백엔드를 지정하기 위해 Plugin 를 할당해야 합니다. 저장 작업이 진행되는 동안 status 속성은 Saving 상태로 전환되며, 작업이 성공적으로 완료되면 Ready 상태로 이동합니다. 다음 코드 조각은 자바스크립트를 사용하여 장소를 저장하고 삭제하는 방법을 보여줍니다.

//creating and saving a place
var place = Qt.createQmlObject('import QtLocation; Place { }', parent);
place.plugin = myPlugin;
place.name = "New York";
place.location.coordinate.latitude = 40.7
place.location.coordinate.longitude = -74.0
place.save();

//removing a place
place.remove();

자세히 알아보기

위의 코드 조각은 Places 기능의 일부만 보여줍니다. images, reviews 등과 같은 더 풍부한 콘텐츠는 물론, 더 심층적인 설명과 해설을 보려면 아래에 표시된 Places 유형을 참조하십시오.

API 사용 방법에 대한 보다 포괄적인 시연은 Places (QML) 예제를 참조하십시오.

Places 유형

데이터 유형

모델