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 和coordinate 类型不同，它们用于描述位置的位置。地点的基本属性是name 和location 。

地点对象通常是从搜索模型中获取的，一般只设置了基本属性。detailsFetched 属性可用于测试是否需要从Plugin 获取更多属性值。这可通过调用getDetails() 方法来实现。获取操作的进度可通过status 属性进行监控，当获取详细信息时，该属性将设置为 Place.Fetching。

地点类型有许多属性，其中包含有关地点的信息。有关如何联系该地点的详细信息可通过contactDetails 属性获取。此外，还有用于获取主要phone,fax,email 和website 的便捷属性。

每个地点都分配有零个或多个categories 。分类通常用于搜索特定类型的地点，如餐厅或酒店。有些地方有一个ratings 对象，用于显示该地方的质量。

地点元数据由supplier 提供，后者可能要求在用户查看地点详细信息时向其显示attribution 消息。

地点有一个相关的icon ，可用于在地图上表示地点或在视图中装饰代表。

地点可以有与之相关的附加丰富内容。目前支持的丰富内容包括编辑描述、评论和图片。这些内容作为一组用于检索内容的模型公开。地点的编辑描述可通过editorialModel 属性获取。有关该地方的评论可通过reviewModel 属性获取。可通过imageModel 属性访问该地点的图片库。

地方可能还有一些正式 API 未涵盖的附加属性。通过extendedAttributes 属性可以访问这些属性。每个Plugin 都有特定的扩展属性类型。

位置几乎总是与plugin 绑定。在调用save() 、remove() 或getDetails() 之前，必须先设置plugin 属性。只有设置了plugin 属性，reviewModel 、imageModel 和editorialModel 才有效。

保存位置

如果Plugin 支持，则可以使用 "地点 "类型来保存地点。首先创建一个新地点并设置其属性：

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 属性将更新为新保存地点的标识符。

注意事项

地点 API 目前仅用于保存core 的详细信息。不支持保存图片和评论等丰富内容，也不支持保存供应商和评级等详细信息。通常情况下，管理器在保存时会忽略这些字段，如果填充了这些字段，可能会产生警告信息。

地点 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 属性的地点对象，并调用其remove() 方法。status 属性将变为 Place.Removing，如果保存成功，则变为 Place.Ready，如果出现错误，则变为 Place.Error。

收藏夹

位置 API 支持收藏夹的概念。收藏夹一般通过使用两个插件来实现，第一个插件通常是只读的地点来源（起源插件），第二个读/写插件（目的地插件）用于将起源的地点存储为收藏夹。

每个 "地点 "都有一个 "收藏夹 "属性，该属性旨在包含来自目的地插件的相应地点（地点本身来自起源插件）。由于原始地点和收藏夹实例都可用，开发人员可以选择向用户显示哪些属性。例如，收藏夹可能有一个修改过的名称，应显示该名称而不是原始名称。

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 检查在搜索过程中发现的任何位置，看是否有相应的收藏夹。如果有，则设置该地点的收藏夹属性，否则收藏夹属性保持为空。

另请参阅 PlaceSearchModel 。

属性文档

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

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

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

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

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

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

方法文档