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 具有内置行为，使该区域能够响应轻扫事件并进行相应的滚动。

在下面的代码片段中，搜索模型已被赋值给ListView 的model 属性。当模型更新为新结果时，ListView 会自动更新以反映模型中的新数据项。

一个简单的委托已被绑定到ListView 的delegate 属性上。PlaceSearchModel 公开了一组roles ，其中标题和 地点角色在下文中被使用，它们的类型分别是string和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 内部，声明了一个MapItemView ，其中model 属性已设置为搜索模型，并使用由MapQuickItem 组成的delegate 来显示标记图像。搜索模型找到的每个地点都会显示一个标记。该委托使用place角色来定位标记。

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 ` 状态。以下代码片段演示了如何使用 JavaScript 保存和删除地点。

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

了解更多

上述代码片段仅展示了 Places 功能的一小部分。请参考下方的Places 类型，以获取更丰富的内容（如images 、reviews 等），以及更深入的描述和说明。

另请参阅“地点（QML）”示例，了解有关如何使用该 API 的更全面演示。

地点类型

数据类型

模型