QML 플레이스 API

개요

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

소개 개념

플러그인

Plugin 은 백엔드를 위한 추상화입니다. Plugin 하나는 REST 서버에서 장소에 액세스할 수 있고 다른 하나는 로컬 데이터베이스에서 장소에 액세스할 수 있습니다. 다음은 "osm"이라는 이름을 제공하여 Plugin 객체를 인스턴스화합니다. Plugin 이름은 선택할 백엔드를 식별합니다. 플러그인에는 기본적으로 키-값 쌍의 형태를 취하는 parameters 세트가 제공될 수도 있습니다. 지정할 수 있는 parameters 는 Plugin 백엔드마다 다릅니다. 가능한 parameters 및 각 Plugin 의 뉘앙스에 대한 설명은 플러그인 참조를 참조하세요.

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 의 model 속성에 할당되었습니다. 모델이 새 결과로 업데이트되면 ListView 은 모델의 새 데이터 항목을 반영하도록 자동으로 업데이트됩니다.

간단한 델리게이트가 ListView 의 delegate 프로퍼티에 바인딩되었습니다. PlaceSearchModel 은 roles 의 집합을 노출하며, 이 중 제목 및 장소 역할은 각각 문자열 및 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 } } } } }

전체 소스 코드는 장소 목록 예제를 참조하세요.

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

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

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

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 } } } } }

전체 소스 코드는 장소 맵 예시를 참조하세요.

장소 세부정보 가져오기

대역폭을 절약하기 위해 백엔드에서 부분적으로 세부 정보가 채워진 장소만 반환하는 경우가 있습니다. 이는 사용 가능한 모든 세부 정보를 가져왔는지 여부를 나타내는 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();

자세히 알아보기

위의 코드 조각은 장소 기능의 일부만 보여줍니다. images , reviews 등과 같은 더 풍부한 콘텐츠와 더 자세한 설명 및 설명을 보려면 아래에 표시된 장소 유형을 참조하세요.

API 사용 방법에 대한 보다 포괄적인 데모는 장소(QML ) 예시도 참조하세요.

장소 유형

데이터 유형

모델