自适应卡片扩展中的位置功能

项目
03/30/2023

注意

自适应卡片扩展中的地理位置功能将在 SPFx v1.15 中提供。

因此，请确保已安装它，然后再继续。

有关安装 SPFx v1.15 的详细信息，请参阅 SharePoint 框架 v1.15 发行说明。

本教程还假定你已生成了一个 SharePoint 自适应卡扩展。

若要了解如何创建第一个 SharePoint 自适应卡片扩展，请尝试本教程。

适用于地理位置的新操作类型

有 2 个位置操作：

获取位置
显示位置

获取位置：

提供用户的当前设备位置或打开位置选取器并返回用户选择的位置。在浏览器中，它使用必应地图作为映射接口。

获取位置的 ACE 操作是：VivaAction.GetLocation。

它采用可选的布尔参数：ChooseLocationOnMap。

如果属性 ChooseLocationOnMap 设置为 true，则操作将打开地图，用户可以选择地图上的位置，否则它将提取用户的当前设备位置。

显示位置：

通过此操作，可以在屏幕上显示地图，你可以在地图上显示用户的当前位置，也可以在地图上显示指定的坐标。

显示位置的 ACE 操作是：VivaAction.ShowLocation。

它采用可选的位置参数：locationCoordinates。

若要显示特定位置，应通过 locationCoordinates 参数传递位置坐标（纬度和经度）。

locationCoordinates 对象由以下几个属性组成：

{
  /**
   * Latitude of the location.
   */
  latitude: number;

  /**
   * Longitude of the location.
   */
  longitude: number;

  /**
   * Timestamp (optional).
   */
  timestamp?: number;

  /**
   * Accuracy of the location (optional).
   */
  accuracy?: number;
}

教程和示例

可以查看本教程，它详细介绍了使用地理位置操作创建卡片的步骤。

以下示例介绍了地理位置操作及其用途。

获取用户的当前位置

在模板 JSON 中，介绍以下操作：
```
"actions": [{
  type: 'VivaAction.GetLocation',
  id: 'Get Location'
}]
```
调用此操作时，将提取用户的当前地理位置，并通过 onAction 回调传递给第三方开发人员。

注意

在这种情况下，映射不会显示。
从地图中选择位置

在模板 JSON 中，介绍以下操作：
```
"actions": [{
  type: 'VivaAction.GetLocation',
  id: 'Get Location',
  parameters: {chooseLocationOnMap: true}
}]
```
调用此操作时，将打开指向用户当前位置的地图，用户可以自行选择并共享位置。所选位置的坐标通过 onAction 回调传递给第三方开发人员。
显示用户的当前位置

在模板 JSON 中，介绍以下操作：
```
"actions": [{
  type: 'VivaAction.ShowLocation',
  id: 'Show Location'
}]
```
调用此操作时，将打开一个地图，并在其上显示用户的当前位置坐标。

显示指定位置

在模板 JSON 中，介绍以下操作：

"actions": [{
  type: 'VivaAction.ShowLocation',
  id: 'Show Location',
  parameters: {
    locationCoordinates: {
      latitude: 28.6132039578389,
      longitude: 77.229488240066
    }
  }
}]

调用此操作时，将打开一个地图，并显示操作中指定的位置坐标。

通过卡片设计器卡的属性窗格访问地理位置操作

如果不想编写代码，但仍希望了解地理位置操作的工作原理，则可以浏览本教程，了解如何通过属性窗格创建具有地理位置操作的卡片。

注意

这些地理位置操作可以添加到卡片视图或卡视图的按钮或快速视图内。

权限和错误代码

若要使位置 API 正常工作，用户必须授予访问设备位置的权限。

错误代码	Error Description
PermissionDenied	用户已拒绝访问位置的权限
InternalError	调用位置 API 时发生意外错误
HostNotSupported	位置操作正在不受支持的环境中使用

卡片开发人员的回调

调用操作 VivaAction.GetLocation 时，我们将通过 onAction 回调传递提取的位置坐标。

注意

对于 VivaAction.ShowLocation，不调用 onAction 回调。

对于操作 VivaAction.GetLocation 和 VivaAction.ShowLocation，如果用户进入错误状态，则将调用 onError 回调，我们将向其传递操作名称和错误代码。

地理位置操作的可用性

注意

这些新操作当前在浏览器中可用。稍后将启用Viva Connections桌面和Viva Connections移动支持。正式发布后，操作的支持矩阵将如下所示：

操作	Viva Connection Desktop	Viva Connections Mobile	浏览器
获取位置	不支持	支持	支持
显示位置	不支持	支持	支持

通过