Place QML Type

'장소' 유형은 주목할 만한 위치를 나타냅니다. 더 보기...

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

속성

• attribution : string
• categories : list<Category>
• contactDetails : ContactDetails
• detailsFetched : bool
• editorialModel : EditorialModel
• extendedAttributes : ExtendedAttributes
• favorite : Place
• icon : Icon
• imageModel : ImageModel
• location : QtPositioning::Location
• name : string
• placeId : string
• plugin : Plugin
• primaryEmail : string
• primaryFax : string
• primaryPhone : string
• primaryWebsite : string
• ratings : Ratings
• reviewModel : ReviewModel
• status : enumeration
• supplier : Supplier
• visibility : enumeration

방법

• void copyFrom(Place original)
• string errorString()
• void getDetails()
• void initializeFavorite(Plugin destinationPlugin)
• void remove()
• void save()

상세 설명

Place 유형은 물리적 위치를 나타내며, 해당 위치를 설명하는 추가 메타데이터를 포함합니다. 이는 위치가 어디에 있는지를 설명하는 데 사용되는 Location, Address 및 geoCoordinate 유형과는 대조됩니다. Place의 기본 속성은 name 및 location 입니다.

Place 객체는 일반적으로 검색 모델을 통해 얻어지며, 대개 기본 속성만 설정되어 있습니다. detailsFetched 속성을 사용하면 Plugin 에서 추가 속성 값을 가져와야 하는지 확인할 수 있습니다. 이는 getDetails() 메서드를 호출하여 수행할 수 있습니다. 검색 작업의 진행 상황은 ` status ` 속성을 통해 모니터링할 수 있으며, 세부 정보가 검색 중일 때는 이 속성이 `Place.Fetching`으로 설정됩니다.

Place 유형에는 위치에 대한 정보를 담고 있는 여러 속성이 있습니다. 해당 장소에 연락하는 방법에 대한 세부 정보는 contactDetails 속성에서 확인할 수 있습니다. 또한, 기본 phone, fax, email 및 website 를 가져오는 데 편리한 속성들도 제공됩니다.

각 장소에는 0개 이상의 categories 가 할당됩니다. 카테고리는 일반적으로 식당이나 호텔과 같은 특정 종류의 장소를 검색할 때 사용됩니다. 일부 장소에는 해당 장소의 품질을 나타내는 ratings 객체가 있습니다.

장소 메타데이터는 supplier 에 의해 제공되며, 이 제공자는 장소 세부 정보를 볼 때 사용자에게 attribution 메시지가 표시되도록 요구할 수 있습니다.

장소에는 연관된 icon 가 있으며, 이를 사용하여 지도상에서 장소를 표시하거나 뷰 내에서 델리게이트를 꾸밀 수 있습니다.

장소에는 추가적인 리치 콘텐츠가 연관될 수 있습니다. 현재 지원되는 리치 콘텐츠에는 편집 설명, 리뷰 및 이미지가 포함됩니다. 이러한 콘텐츠는 콘텐츠를 검색하기 위한 일련의 모델로 노출됩니다. 장소에 대한 편집 설명은 editorialModel 속성을 통해 확인할 수 있습니다. 장소에 대한 리뷰는 reviewModel 속성을 통해 확인할 수 있습니다. 장소의 사진 갤러리는 imageModel 속성을 사용하여 액세스할 수 있습니다.

장소에는 공식 API에서 다루지 않는 추가 속성이 있을 수 있습니다. ` extendedAttributes ` 속성을 통해 이러한 속성에 접근할 수 있습니다. 사용 가능한 확장 속성의 유형은 각 ` Plugin`에 따라 다릅니다.

Place는 거의 항상 plugin 와 연결되어 있습니다. save(), remove() 또는 getDetails()을 호출하려면 먼저 plugin 속성을 설정해야 합니다. reviewModel, imageModel 및 editorialModel 는 plugin 속성이 설정된 경우에만 유효합니다.

장소 저장하기

Plugin 가 이를 지원하는 경우, Place 유형을 사용하여 장소를 저장할 수 있습니다. 먼저 새로운 Place를 생성하고 속성을 설정합니다:

Place {
    id: myPlace
    plugin: myPlugin

    name: "Brisbane Technology Park"
    location: Location {
        address: Address {
            street: "53 Brandl Street"
            city: "Eight Mile Plains"
            postalCode: "4113"
            country: "Australia"
        }
        coordinate {
            latitude: -27.579646
            longitude: 153.100308
        }
    }

    visibility: Place.PrivateVisibility
}

그런 다음 save() 메서드를 호출합니다:

    myPlace.save();

status 속성은 Place.Saving으로 변경된 후, 저장이 성공하면 Place.Ready로, 오류가 발생하면 Place.Error로 변경됩니다.

placeId 속성이 설정된 경우 백엔드는 기존 장소를 업데이트하고, 그렇지 않은 경우 새로운 장소를 생성합니다. 성공 시 placeId 속성이 새로 저장된 장소의 식별자로 업데이트됩니다.

주의 사항

Places API는 현재 core 정보만 저장하도록 설계되어 있습니다. 이미지나 리뷰와 같은 리치 콘텐츠, 또는 공급자나 평점과 같은 세부 정보를 저장하는 것은 지원되지 않는 사용 사례입니다. 일반적으로 관리자는 저장 시 이러한 필드를 무시하며, 해당 필드가 채워져 있는 경우 경고 메시지를 표시할 수 있습니다.

Places API는 다음 핵심 정보의 저장만 지원합니다:

• 이름
• 장소 ID
• 위치
• 연락처 정보
• 아이콘
• 카테고리 (장소를 설명하는 태그와 유사한 이름)
• 표시 범위

제공업체에 따라 이 중 일부만 지원될 수 있습니다. 자세한 내용은 플러그인 설명서를 참조하십시오.

평점, 확장 속성, 이미지, 리뷰, 편집 기사 및 공급업체와 같은 속성의 저장은 Places API에서 명시적으로 지원되지 않습니다.

플러그인 간 저장

플러그인 간에 장소를 저장할 때 유의해야 할 몇 가지 사항이 있습니다. ID, 카테고리, 아이콘과 같은 장소의 일부 필드는 플러그인별 고유 엔티티입니다. 예를 들어, 한 관리자의 카테고리가 다른 관리자에서는 인식되지 않을 수 있습니다. 따라서 한 플러그인에서 다른 플러그인으로 장소를 직접 저장하는 것은 불가능합니다.

일반적으로 플러그인 간 저장은 ‘즐겨찾기( favorites )’ 섹션에서 설명한 대로 즐겨찾기로 저장하는 방식으로 처리하는 것이 권장됩니다. 그러나 다른 접근 방식도 있는데, 이는 새로운 장소를 생성하고 해당 장소의 (대상) 플러그인을 설정한 다음, ` copyFrom()` 메서드를 사용하여 원본 장소의 세부 정보를 복사하는 것입니다. copyFrom()을 사용하면 대상 플러그인에서 지원하는 데이터만 복사되며, 장소 식별자와 같은 플러그인 고유의 데이터는 복사되지 않습니다. 복사가 완료되면 해당 장소는 저장할 수 있는 상태가 됩니다.

다음 코드 조각은 ` copyFrom ` 메서드를 사용하여 장소를 다른 플러그인에 저장하는 예제를 보여줍니다:

var place = Qt.createQmlObject('import QtLocation; Place { }', parent);
place.plugin = destinationPlugin;
place.copyFrom(originalPlace);
place.save();

장소 제거

장소를 제거하려면 유효한 placeId 속성을 가진 Place 객체가 존재하는지 확인한 후, 해당 객체의 remove() 메서드를 호출하십시오. status 속성은 Place.Removing으로 변경된 후, 저장이 성공하면 Place.Ready로, 오류가 발생하면 Place.Error로 변경됩니다.

즐겨찾기

Places API는 즐겨찾기 기능을 지원합니다. 즐겨찾기는 일반적으로 두 개의 플러그인을 사용하여 구현됩니다. 첫 번째 플러그인은 대개 읽기 전용 장소 소스(원본 플러그인)이며, 두 번째 읽기/쓰기 플러그인(대상 플러그인)은 원본 플러그인의 장소를 즐겨찾기로 저장하는 데 사용됩니다.

각 Place에는 대상 플러그인의 해당 장소를 포함하도록 설계된 favorite 속성이 있습니다(장소 자체는 원본 플러그인에서 가져옵니다). 원본 장소와 즐겨찾기 인스턴스 모두 사용할 수 있으므로, 개발자는 사용자에게 표시할 속성을 선택할 수 있습니다. 예를 들어, 즐겨찾기에는 원본 이름 대신 표시되어야 할 수정된 이름이 있을 수 있습니다.

Text { text: place.favorite ? place.favorite.name : place.name }

다음은 새로운 즐겨찾기 인스턴스를 저장하는 방법을 보여줍니다. 먼저 즐겨찾기 인스턴스를 생성/초기화하는 호출이 수행되고, 그 후 인스턴스가 저장됩니다.

place.initializeFavorite(destinationPlugin);
//if necessary customizations to the favorite can be made here.
//...
place.favorite.save();

다음은 즐겨찾기를 삭제하는 방법을 보여줍니다:

place.favorite.remove();
    ...
//check successful removal of the favorite by monitoring its status.
//once that is done we can assign null to the favorite
place.favorite = null;

PlaceSearchModel 에는 favoritesPlugin 속성이 있습니다. 이 속성이 설정되어 있으면, 검색 중에 발견된 모든 장소에 대해 favoritesPlugin을 참조하여 해당 즐겨찾기 장소가 있는지 확인합니다. 해당 장소가 있으면 Place의 favorite 속성이 설정되고, 그렇지 않으면 favorite 속성은 null로 유지됩니다.

PlaceSearchModel도 참조하십시오 .

속성 문서

attribution : string

이 속성은 해당 장소에 대한 서식 있는 출처 정보 문자열을 포함합니다. 일부 제공업체는 장소가 표시될 때마다 사용자에게 출처 정보를 표시하도록 요구할 수 있습니다. 이 속성의 내용이 비어 있지 않은 경우, 해당 내용을 사용자에게 표시해야 합니다.

categories : list<Category> [read-only]

이 속성은 해당 장소가 속해 있는 카테고리 목록을 포함합니다. 장소에 할당할 수 있는 카테고리는 각 plugin 에 따라 다릅니다.

contactDetails : ContactDetails [read-only]

이 속성은 해당 장소의 연락처 정보(예: 전화번호 또는 웹사이트 URL)를 포함합니다. 이 속성은 ` contactDetail ` 객체들의 맵입니다.

detailsFetched : bool [read-only]

이 속성은 장소의 세부 정보가 가져와졌는지 여부를 나타냅니다. 이 속성이 false인 경우, 장소 세부 정보는 아직 가져오지 않은 상태입니다. getDetails() 메서드를 호출하여 세부 정보를 가져올 수 있습니다.

getDetails()도 참조하십시오 .

editorialModel : EditorialModel [read-only]

이 속성에는 해당 장소에 대한 편집 설명 정보를 가져오는 데 사용할 수 있는 모델이 포함되어 있습니다.

extendedAttributes : ExtendedAttributes [read-only]

이 속성은 장소의 확장 속성을 포함합니다. 확장 속성은 해당 장소의 속성에서 다루지 않는 장소에 대한 추가 정보입니다.

favorite : Place

이 속성은 장소의 즐겨찾기 인스턴스를 저장합니다.

icon : Icon

이 속성은 해당 장소를 나타내는 데 사용할 수 있는 그래픽 아이콘을 포함합니다.

imageModel : ImageModel [read-only]

이 속성에는 해당 장소의 이미지를 가져오는 데 사용할 수 있는 모델이 포함되어 있습니다.

location : QtPositioning::Location

이 속성은 좌표, 주소 및 경계 상자를 가져오는 데 사용할 수 있는 위치 정보를 포함합니다.

name : string

이 속성은 해당 장소를 나타내는 데 사용할 수 있는 장소의 이름을 포함합니다.

placeId : string

이 속성은 장소의 고유 식별자를 포함합니다. 장소 식별자는 이를 생성한 Plugin 에서만 의미가 있으며, Plugins 간에는 이전할 수 없습니다. 장소 ID는 전 세계적으로 고유함을 보장하지는 않지만, 이를 생성한 Plugin 내에서만 고유합니다.

장소 식별자만 알고 있는 경우, 다른 모든 장소 데이터는 Plugin 에서 가져올 수 있습니다.

    place.plugin = myPlugin;
    place.placeId = "known-place-id";
    place.getDetails();

plugin : Plugin

이 속성에는 이 장소를 제공한 Plugin 가 포함되어 있으며, 이를 통해 해당 서비스에 대한 자세한 정보를 확인할 수 있습니다.

primaryEmail : string [read-only]

이 속성은 해당 장소의 기본 이메일 주소를 저장합니다. 이 장소에 대해 “이메일” 연락처 정보가 정의되어 있지 않은 경우, 이 속성은 빈 문자열이 됩니다. 이는 다음과 동일합니다.

    var primaryEmail;
    if (place.contactDetails["email"].length > 0)
        primaryEmail = place.contactDetails["email"][0].value;

primaryFax : string [read-only]

이 속성은 해당 장소의 기본 팩스 번호를 나타냅니다. 이 장소에 "팩스" 연락처 정보가 정의되어 있지 않은 경우, 이 속성은 빈 문자열이 됩니다. 이는 다음과 동일합니다.

    var primaryFax;
    if (place.contactDetails["fax"].length > 0)
        primaryFax = place.contactDetails["fax"][0].value;

primaryPhone : string [read-only]

이 속성은 해당 장소의 주 전화번호를 나타냅니다. 이 장소에 "전화번호" 연락처 정보가 정의되어 있지 않은 경우, 이 속성은 빈 문자열이 됩니다. 이는 다음과 동일합니다:

    var primaryPhone;
    if (place.contactDetails["phone"].length > 0)
        primaryPhone = place.contactDetails["phone"][0].value;

primaryWebsite : string [read-only]

이 속성은 해당 장소의 기본 웹사이트 URL을 저장합니다. 이 장소에 대해 “웹사이트” 연락처 정보가 정의되어 있지 않은 경우, 이 속성은 빈 문자열이 됩니다. 이는 다음과 동일합니다.

    var primaryWebsite;
    if (place.contactDetails["website"].length > 0)
        primaryWebsite = place.contactDetails["website"][0].value;

ratings : Ratings

이 속성에는 해당 장소에 대한 평점이 포함되어 있습니다. 이 평점은 해당 장소의 품질을 가늠할 수 있는 지표가 됩니다.

reviewModel : ReviewModel [read-only]

이 속성에는 해당 장소에 대한 리뷰를 가져오는 데 사용할 수 있는 모델이 포함되어 있습니다.

status : enumeration [read-only]

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

status 속성을 핸들러 함수에 연결한 다음, 핸들러 함수가 상태 변화를 처리하도록 하여 장소의 상태를 확인할 수 있습니다.

place.statusChanged.connect(statusChangedHandler);
    ...
function statusChangedHandler() {
    if (statusChangedHandler.prevStatus === Place.Saving) {
        switch (place.status) {
        case Place.Ready:
            console.log('Save successful');
            break;
        case Place.Error:
            console.log('Save failed');
            break;
        default:
            break;
        }
    }
    statusChangedHandler.prevStatus = place.status;
}

supplier : Supplier

이 속성은 장소 데이터의 제공자를 나타냅니다. 제공자는 일반적으로 해당 장소에 대한 데이터를 수집한 기업이나 기관입니다.

visibility : enumeration

이 속성은 장소의 공개 범위를 나타냅니다. 다음 중 하나일 수 있습니다:

가시성 설정은 기기 내 애플리케이션의 사용자 인터페이스에 장소가 표시되는 방식에는 영향을 미치지 않습니다. 대신, 장소의 공유 방식을 정의합니다.

메서드 문서

void copyFrom(Place original)

original 의 특정 위치에 있는 데이터를 이 위치로 복사합니다. 이 위치의 플러그인이 지원하는 데이터만 복사되며, 위치 식별자와 같은 플러그인 고유의 데이터는 복사되지 않습니다.

string errorString()

마지막 작업의 오류에 대한 설명을 문자열로 반환합니다. 마지막 작업이 성공적으로 완료된 경우, 이 문자열은 비어 있습니다.

void getDetails()

이 메서드는 장소 세부 정보를 가져오기 시작합니다.

조회가 진행 중인 동안 ` status ` 속성은 `Place.Fetching`으로 변경됩니다. 조회가 성공하면 객체의 속성이 업데이트되고, ` status `은 `Place.Ready`로, ` detailsFetched `은 true로 설정됩니다. 오류가 발생하면 ` status `은 `Place.Error`로 설정됩니다. ` errorString()` 메서드를 사용하여 오류에 대한 세부 정보를 확인할 수 있습니다.

void initializeFavorite(Plugin destinationPlugin)

대상 플러그인 destinationPlugin 에 저장할 위치에 대한 즐겨찾기 인스턴스를 생성합니다. favorite 속성이 null 가 아닌 경우, 이 메서드는 아무 작업도 수행하지 않습니다.

void remove()

이 메서드는 해당 위치에 대해 제거 작업을 수행합니다.

저장 작업이 진행되는 동안 ` status ` 속성은 `Place.Removing`으로 변경됩니다. 성공 시 ` status `는 `Place.Ready`로 설정됩니다. 오류 발생 시 ` status `는 `Place.Error`로 설정됩니다. 오류에 대한 자세한 내용을 확인하려면 ` errorString()` 메서드를 사용할 수 있습니다.

void save()

이 메서드는 장소에 대한 저장 작업을 수행합니다.

저장 작업이 진행 중일 때 ` status ` 속성은 `Place.Saving`으로 변경됩니다. 성공 시 ` status `은 `Place.Ready`로 설정됩니다. 오류 발생 시 ` status `은 `Place.Error`로 설정됩니다. ` errorString()` 메서드를 사용하여 오류 세부 정보를 확인할 수 있습니다.

placeId 속성이 이전에 비어 있었다면, 저장 작업이 성공적으로 완료되는 동안 자동으로 유효한 값이 할당됩니다.

PlaceSearchModel 는 업데이트가 감지된 모든 Place에 대해 Place::getDetails 를 호출한다는 점에 유의하십시오. 이로 인해 PlaceSearchModel 의 Place가 성공적으로 저장될 때마다 Place 세부 정보가 가져오게 되며, 이는 Saving, Ready, Fetching, Ready 의 상태 변화 순서를 초래합니다.