QML Places API

最新推荐文章于 2024-10-12 18:12:14 发布

꧁白杨树下꧂

最新推荐文章于 2024-10-12 18:12:14 发布

阅读量154

点赞数

分类专栏： qt6.9文档文章标签： qt

原文链接：https://doc-snapshots.qt.io/qt6-dev/location-places-qml.html

版权

qt6.9文档专栏收录该内容

93 篇文章 0 订阅

订阅专栏

QML Places API

Overview

概述

The Places API lets users discover places of interest and view details about them, such as address and contact information. Some places may have additional content associated with them, such as images and reviews. The Places API also lets you manage places and categories, allowing you to to save and remove them. Places may also include paths, roads, or forms of transport, enabling navigation optimization and assistance. For more information about navigation, see routes.

地点API允许用户发现感兴趣的地点并查看有关这些地点的详细信息，如地址和联系信息。有些地方可能有与之相关的其他内容，如图像和评论。地点API还允许管理地点和类别，允许保存和删除它们。地点还可以包括路径、道路或交通方式，从而实现导航优化和辅助。有关导航的更多信息，请参见路线。

Introductory Concepts

介绍性概念

Plugin

插件

A Plugin is an abstraction for a backend. One Plugin might access places from a REST server while another may access places from a local database. The following instantiates a Plugin object by providing a name of "osm". The Plugin name identifies which backend to choose from. Plugins may also be provided with a set of parameters, which essentially takes the form of a set of key-value pairs. The parameters that can be specified vary among the different Plugin backends. For documentation on the possible parameters and nuances of each Plugin, see the Plugin References.

插件是后端的抽象。一个插件可以从REST服务器访问位置，而另一个插件则可以从本地数据库访问位置。下面通过提供名称“osm”来实例化Plugin对象。插件名称标识了要从哪个后端进行选择。插件还可以提供一组参数，这些参数基本上采用一组键值对的形式。可以指定的参数因插件后端的不同而异。有关每个插件的可能参数和细微差别的文档，请参阅插件参考。

Plugin {
    id: myPlugin
    name: "osm"
    //specify plugin parameters as necessary
    //PluginParameter {...}
    //PluginParameter {...}
    //...
}

Models, Views and Delegates

模型、视图和委托

The QML Places API is built around the notion of models, views and delegates.

QML Places API是围绕模型、视图和委托的概念构建的。

Model

A model holds data items and maintains their structure. The model is also responsible for retrieving the items from a data source.

模型保存数据项并维护其结构。该模型还负责从数据源检索项目。

View

A view is a visual container that displays the data and manages how visual items are shown such as in a list or a grid. The view may also be responsible for navigating the data, for example, scrolling through the visual items during a flicking motion.

视图是一个可视化容器，用于显示数据并管理可视化项目的显示方式，例如在列表或网格中。视图还可以负责导航数据，例如在轻弹动作期间滚动浏览可视化项目。

Delegate

A delegate defines how individual data elements should appear as visual items in the view. The models expose a set of data roles and the delegate uses them to construct a visual item. The delegate may also define behaviour such as an operation to invoke when a visual item is clicked.

委托定义了单个数据元素在视图中作为可视项的显示方式。这些模型公开了一组数据角色，委托人使用它们来构建可视化项目。代理还可以定义行为，例如在单击视觉项目时调用的操作。

The Common Use Cases section below demonstrates concrete examples of how these concepts fit together.

下面的通用用例部分演示了这些概念如何结合在一起的具体示例。

Common Use Cases

常见用例

Searching for Places

搜索地点

Searching is accomplished via the PlaceSearchModel. The plugin property specifies which backend to perform search operations against. Search parameters may be provided through properties such as the searchTerm and searchArea. A search operation can then be started by invoking the update() method. For simplicity, the snippet below invokes update() once construction of the model as been completed, typically update() would be invoked in response to a user action such as a button click. While the search operation is underway the PlaceSearchModel::status property transitions into the Loading state and when successfully completed moves into the Ready state.

搜索是通过PlaceSearchModel完成的。插件属性指定对哪个后端执行搜索操作。搜索参数可以通过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()

}

Display Search Results using a ListView

使用ListView显示搜索结果

A ListView can be used to show the search results found by the model. It defines the visual region for where the results are shown, and in the case below fills the entirety of its parent. The ListView has built in behavior that enables the region to respond to flicking events and to scroll appropriately.

ListView可用于显示模型找到的搜索结果。它定义了显示结果的视觉区域，在下面的情况下，它填充了其父级的整个区域。ListView具有内置行为，使该区域能够响应轻弹事件并适当滚动。

In the snippet below, the search model has been assigned to the ListView's model property. When the model is updated with new results, the ListView is automatically updated to reflect the model's new data items.

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

A simple delegate has been bound to the ListView's delegate property. The PlaceSearchModel exposes a set of roles of which the title and place roles have been used below, these are of type string and Place respectively. Essentially for each data item that should be visible in the view, the view invokes the delegate to create a visual representation of the item.

一个简单的委托已绑定到ListView的委托属性。PlaceSearchModel公开了一组角色，其中title和place角色已在下面使用，分别为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 }
            }
        }
    }
}

Note: For simplicty's sake we have assumed that every search result is of type PlaceSearchResult and so always have access to the place role, other search result types may not have a place role.

注意：为了简单起见，我们假设每个搜索结果都是PlaceSearchResult类型，因此始终可以访问位置角色，其他搜索结果类型可能没有位置角色。

See the Places List example for full source code.

请参阅位置列表示例以获取完整的源代码。

Display Search Results using a MapItemView

使用MapItemView显示搜索结果

Instead of a ListView, the PlaceSearchModel can be used in conjunction with a MapItemView to display markers on a map. Firstly a Map is used to define the visual region occupied by the map, in this case it fills the entirety of its parent. Other properties are specified such as the plugin providing the maps, and the map's center and zoomLevel.

代替ListView，PlaceSearchModel可以与MapItemView结合使用，在地图上显示标记。首先，地图用于定义地图所占据的视觉区域，在这种情况下，它填充了其父地图的整个区域。指定了其他属性，例如提供地图的插件以及地图的中心和缩放级别。

Inside the Map, a MapItemView is declared, where the model property has been set to the search model and a delegate consisting of a MapQuickItem is used to display a marker image. A marker is shown for every place that was found by the search model. The delegate uses the place role to position the marker.

在Map内部，声明了一个MapItemView，其中模型属性已设置为搜索模型，由MapQuickItem组成的委托用于显示标记图像。搜索模型找到的每个地方都会显示一个标记。代理人使用位置角色来定位标记。

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

Note: For simplicty's sake we have assumed that every search result is of type PlaceSearchResult and so always have access to the place role, other search result types may not have a place role.

注意：为了简单起见，我们假设每个搜索结果都是PlaceSearchResult类型，因此始终可以访问place角色，其他搜索结果类型可能没有place角色。

See the Places Map example for full source code.

请参阅Places Map示例以获取完整的源代码。

Fetching Place Details

获取地点详细信息

In order to save bandwidth, sometimes a backend will only return places which are partially populated with details. This can be checked with the Place::detailsFetched property which indicates whether all availalable details have been fetched or not. If not, the Place::getDetails() method can be invoked to fetch the remaining details.

为了节省带宽，有时后端只会返回部分填充了详细信息的地方。这可以通过Place::detailsFetched属性进行检查，该属性指示是否已获取所有可用的详细信息。如果没有，可以调用Place::getDetails（）方法来获取剩余的详细信息。

if (!place.detailsFetched)
    place.getDetails();

Saving and Removing Places

保存和删除位置

Some backends may support saving and removing places. This can be done by calling the Place::save() and Place::remove() methods respectively. Note that in order to save a Place, a Plugin must be assigned to specify which backend we are saving to. The status property will transition into the Saving state while the save operation is happening and on successful completion will move to the Ready state. The following snippet shows how to save and remove a place using javascript.

一些后端可能支持保存和删除位置。这可以通过分别调用Place::save（）和Place::remove（）方法来实现。请注意，为了保存一个位置，必须分配一个插件来指定我们要保存到哪个后端。保存操作发生时，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();

Learn More

了解更多

The above snippets only exhibit a small subset of Places functionality. Refer to the Places Types shown below for richer content such as images, reviews etc, as well as more indepth descriptions and explanations.

上述代码片段仅展示了Places功能的一小部分。请参阅下面显示的地点类型，以获取更丰富的内容，如图像、评论等，以及更深入的描述和解释。

See also the Places (QML) example for a more comprehensive demonstration on how to use the API.

有关如何使用API的更全面演示，请参阅位置（QML）示例。

Places Types

地点类型

Data Types

数据类型

Category	Type represents a category that a Place can be associated with 类型表示一个地点可以关联的类别
ContactDetails	Type holds contact details for a Place 类型保存地点的联系方式
ExtendedAttributes	Type holds additional data about a Place 类型包含有关地点的其他数据
Place	Type represents a location that is a position of interest 类型表示感兴趣的位置
contactDetail	Type holds a contact detail such as a phone number or a website address 类型包含联系人详细信息，如电话号码或网址
icon	Type represents the icon of a place 类型代表一个地方的图标
placeAttribute	Type holds generic place attribute information 类型包含通用位置属性信息
ratings	Type holds place rating information 类型保存位置评级信息
supplier	Holds data regarding the supplier of a place, a place's image, review, or editorial 保存有关某个地方的供应商、地方形象、评论或社论的数据
user	Type identifies a user who contributed a particular Place content item 类型标识了贡献特定地点内容项的用户

Models

模型

CategoryModel	Type provides a model of the categories supported by a Plugin 类型提供插件支持的类别模型
EditorialModel	Type provides a model of place editorials Type提供了一个地方社论的模型
ImageModel	Type provides a model of place images Type提供地点图像的模型
PlaceSearchModel	Provides access to place search results 提供放置搜索结果的访问权限
PlaceSearchSuggestionModel	Provides access to search term suggestions 提供对搜索词建议的访问
ReviewModel	Type provides a model of place reviews Type提供了一个地点评论模型

Places (C++)Places Backend

© 2024 The Qt Company Ltd. Documentation contributions included herein are the copyrights of their respective owners. The documentation provided herein is licensed under the terms of the GNU Free Documentation License version 1.3 as published by the Free Software Foundation. Qt and respective logos are trademarks of The Qt Company Ltd. in Finland and/or other countries worldwide. All other trademarks are property of their respective owners.