位置QML类型

位置类型表示一个感兴趣的位置。 更多信息...

• 所有成员列表，包括继承成员

属性

• attribution : 字符串
• categories : 分类列表
• contactDetails : 联系详细信息
• detailsFetched : 布尔值
• editorialModel : 编辑模型
• extendedAttributes : 扩展属性
• favorite : 位置
• icon : 图标
• imageModel : 图片模型
• location : QtPositioning::位置
• name : 字符串
• placeId : 字符串
• plugin : 插件
• primaryEmail : 字符串
• primaryFax : 字符串
• primaryPhone : 字符串
• primaryWebsite : 字符串
• ratings : 评分
• reviewModel : 评论模型
• status : 枚举类型
• supplier : 供应商
• visibility : 枚举类型

方法

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

详细描述

地点类型表示一个带有额外元数据的物理位置，描述该位置。与描述位置所在地的 位置、地址 和 坐标 类型相对比，地点的基本属性是其 名称 和 位置。

地点对象通常来源于搜索模型，通常只会设置其基本属性。可以使用 detailsFetched 属性来测试是否需要从 插件 获取更多的属性值。可以通过调用 getDetails() 方法来实现。可以通过 status 属性监视获取操作的进度，当详细信息正在获取时，该属性将被设置为 Place.Fetching。

地点类型有许多属性，包含有关位置的信息。如何联系地点的详细信息可以通过 contactDetails 属性获得。还有方便的属性来获取主要 电话、传真、电子邮件 和 网站。

每个地点都被分配了零个或多个 类别。类别通常在搜索特定类型的地点时使用，比如餐厅或酒店。一些地点有一个 评分 对象，对地点的质量给出了指示。

地点元数据由一个 供应商 提供，该供应商可能要求在查看地点详细信息时向用户显示 归属 消息。

地点有一个相关的 图标，可以用来在地图上表示地点或用于装饰视图中的委托。

地点可能附加有额外的丰富内容。当前支持的丰富内容包含编辑说明、评论和图片。这些以一组模型的形式暴露，用于检索内容。地点的编辑说明可以通过 editorialModel 属性获得。地点的评论可以通过 reviewModel 属性获得。地点图片的画廊可以通过 imageModel 属性访问。

地点可能有未在正式 API 中涵盖的附加属性。《a href="qml-qtlocation-place.html#extendedAttributes-prop" translate="no">extendedAttributes 属性提供了对这些属性的访问。可用的扩展属性类型适用于每个 插件。

地点几乎总是与一个 插件 相关联。必须在调用 save()、remove() 或 getDetails() 之前设置 plugin 属性。只有当设置 plugin 属性时，reviewModel、imageModel 和 editorialModel 才是有效的。

保存地点

如果 插件 支持它，可以使用地点类型来保存地点。首先创建一个新的地点并设置其属性

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();

属性状态将在保存成功时变为Place.Saving，然后变为Place.Ready；如果在保存过程中发生错误，将变为Place.Error。

如果设置placeId属性，后端将更新现有位置，否则将创建一个新位置。如果保存成功，则placeId属性将更新为新保存位置的唯一标识符。

注意事项

当前的地点API只设计为保存核心细节。保存像图像和评论这样的丰富内容或像供应商和评分这样的细节不是受支持的用例。通常，在保存时，管理员通常会忽略这些字段，如果这些字段被填充，可能会显示警告消息。

地点API仅支持保存以下核心细节

• 名称
• 地点ID
• 位置
• 联系信息
• 图标
• 类别（用于描述地点的类似标签的名称）
• 可见范围

可能的情况是，提供商可能只支持这些细节的一个子集。有关更多详细信息，请参阅插件文档。

地点API明确不支持保存诸如评分、扩展属性、图像、评论、编辑和供应商之类的属性。

插件间的保存

在插件间保存地点时，有一些需要注意的事项。地点的一些字段，如ID、类别和图标是特定于插件实体。例如，一个管理员的类别可能不会被另一个管理者识别。因此，直接从一个插件保存到另一个插件是不可能的。

通常建议将插件间的保存处理为保存收藏，如“收藏”部分中所述。但是，还有另一种方法，即创建一个新的地点，设置其（目标）插件，然后使用copyFrom()方法来复制原始地点的细节。使用copyFrom()方法仅复制目标插件支持的文件，插件特定的数据（如地点标识符）不会复制。一旦复制完成，该地点就处于适合保存的状态。

以下代码片段提供了使用copyFrom方法将地点保存到不同插件示例

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

删除地点

要删除地点，请确保存在一个具有有效placeId属性的地点对象，并调用其remove()方法。如果保存成功，状态状态将变为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》具有一个收藏插件属性。如果设置了该属性，在搜索过程中找到的任何地点都会与收藏插件进行比较，以查看是否存在对应的收藏地点。如果是，则设置地点的收藏属性，否则收藏属性保持为null。

另请参阅 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;
}

方法文档