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 的便捷属性。

每个地点都会被分配零个或多个categories 。类别通常用于搜索特定类型的地点，例如餐厅或酒店。某些地点拥有ratings 对象，该对象可反映该地点的质量。

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

地点关联有一个icon ，可用于在地图上显示该地点，或在视图中装饰一个委托对象。

地点可能关联有额外的富媒体内容。当前支持的富媒体内容包括编辑描述、评论和图片。这些内容以一组模型的形式提供，用于检索相关内容。地点的编辑描述可通过editorialModel 属性获取；地点的评论可通过reviewModel 属性获取；地点的图片图库可通过imageModel 属性访问。

地点可能具有正式 API 未涵盖的其他属性。可通过extendedAttributes 属性访问这些属性。可用的扩展属性类型因各个Plugin 而异。

一个“地点”（Place）几乎总是与一个“位置”（plugin ）相关联。必须先设置plugin 属性，才能调用save()、remove() 或getDetails() 方法。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 都有一个“收藏”属性，用于存储来自目标插件的对应地点（该地点本身源自源插件）。由于原始地点和收藏实例均可使用，开发者可以选择向用户显示哪些属性。例如，收藏项可能有一个修改后的名称，应显示该名称而非原始名称。

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 的 favorites 属性设置为该值；否则，favorites 属性保持为 null。

另请参阅 PlaceSearchModel 。

属性文档

attribution : string

该属性包含该地点的富文本署名字符串。某些服务提供商可能要求在显示地点时向用户展示该署名。如果该属性不为空，则应向用户显示其内容。

categories : list<Category> [read-only]

该属性存储了该地点所属的分类列表。可分配给某个地点的分类因plugin 而异。

contactDetails : ContactDetails [read-only]

该属性存储了该地点的联系信息，例如电话号码或网站网址。该属性是一个由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]

该属性存储该地点的主要网站网址。如果该地点未定义“网站”联系信息，则该属性将为空字符串。这相当于

    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 中。如果“收藏”属性不是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::getDetails 。由此产生的结果是：每当PlaceSearchModel 中的某个位置成功保存后，系统都会随之获取该位置的详细信息，从而导致Saving 、Ready 、Fetching 、Ready 的状态依次发生变化。