使用地理位置操作创建自适应卡片扩展

项目
04/08/2023

注意

本教程假设你已安装 SPFx v1.14。

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

搭建自适应卡片扩展项目

为项目创建新的项目目录，将当前文件夹更改为该目录。

通过从你创建的新目录中运行 Yeoman SharePoint 生成器来创建新项目：

yo @microsoft/sharepoint

出现提示时，请输入以下值(为下面省略的所有提示选择默认选项):

你的解决方案名称是什么？ geolocation-tutorial
要创建哪种类型的客户端组件? 自适应卡扩展
要使用哪个模板？ 主文本模板
自适应卡片扩展名是什么? 地理位置

此时，Yeoman 安装必需的依赖项，并为解决方案文件搭建基架。此过程可能需要几分钟时间。

更新项目的托管工作台 URL。

使用 gulp 任务服务时，默认情况下，它将启动具有项目中指定的专用托管工作台 URL 的浏览器。新项目中托管工作台的默认 URL 指向无效的 URL。

找到并打开项目中的文件./config/serve.json。

找到属性 initialPage ：

{
  "$schema": "https://developer.microsoft.com/json-schemas/core-build/serve.schema.json",
  "port": 4321,
  "https": true,
  "initialPage": "https://enter-your-SharePoint-site/ _layouts/workbench.aspx"
}

将 enter-your-SharePoint-site 域更改为要用于测试 SharePoint 租户和网站的 URL。例如：https://contoso.sharepoint.com/sites/devsite/_layouts/workbench.aspx。

此时，如果执行 gulp serve，则会看到卡 GeoLocation 卡片：

请参阅 Web 部件工具箱中的“地理位置”卡片图标

将地理位置添加到自适应卡片扩展

此时，我们已获取开箱即用的基架代码。现在，让我们尝试将地理位置操作添加到卡片视图和快速视图体验。

我们将创建一个包含卡片视图和快速视图的卡片。在卡片视图上，我们将提供一个按钮，它将显示用户的当前位置，单击卡片视图本身将打开快速视图。

在快速视图中，我们将提供三个按钮，这些按钮将执行以下操作：

获取用户的当前位置
让用户从地图中选择位置
在地图上显示特定位置

更新将显示在卡片上的标签

在开始添加操作之前，让我们先更新将在卡片上看到的字符串。

为此，请在项目中定位并打开以下文件：./src/adaptiveCardExtensions/geoLocation/loc/en-us.js

将此文件的内容替换为：

define([], function() {
  return {
    "PropertyPaneDescription": "Tutorial on geolocation action in ACE.",
    "TitleFieldLabel": "Geolocation",
    "Title": "GeoLocation",
    "SubTitle": "GeoLocation Actions",
    "PrimaryText": "Location Demo",
    "Description": "Demonstrating GeoLocation Capabilities",
    "ShowCurrentLocation": "My Location"
  }
});

接下来，请在项目中定位并打开以下文件：./src/adaptiveCardExtensions/geoLocation/loc/mystring.d.ts

将以下内容：

ShowCurrentLocation: string;

添加到 IGeoLocationAdaptiveCardExtensionStrings 接口。

在卡片视图上添加操作

如前所述，在卡片视图上，我们将提供一个按钮，它将显示用户的当前位置，单击卡片视图本身将显示快速视图体验。

我们首先将添加卡片视图上按钮的功能。为此，请在项目中定位并打开以下文件：./src/adaptiveCardExtensions/geoLocation/cardView/CardView.ts

在此处，将 cardButtons 函数的定义替换为以下内容：

public get cardButtons(): [ICardButton] | [ICardButton, ICardButton] | undefined {
  return [
    {
      title: strings.ShowCurrentLocation,
      action: {
        type: 'VivaAction.ShowLocation'
      }
    }
  ];
}

通过此更改，我们配置了一个带有标签 My Location 的按钮，单击操作为 VivaAction.ShowLocation，将显示用户的当前位置。

接下来，将 onCardSelection 函数的内容替换为以下内容：

public get onCardSelection(): IQuickViewCardAction | IExternalLinkCardAction | undefined {
  return {
      type: 'QuickView',
      parameters: {
        view: QUICK_VIEW_REGISTRY_ID
      }
  };
}

此更改意味着当用户单击卡片视图时，应为其打开快速视图。

通过到目前为止所做的更改，卡片视图将如下所示：

在卡片视图中引入字符串和更改后的卡片外观

在快速视图上添加操作

在快速视图中，我们将介绍 3 个操作的按钮：

获取用户的当前位置
让用户从地图中选择位置
在地图上显示特定位置（例如，我们将展示珠穆朗玛峰）

除了这些，我们将有显示 Latitude 和 Longitude 的两个文本块，将在执行 VivaAction.GetLocation 操作（稍后将详细介绍）时显示各自的坐标。

我们将首先定义快速视图的模板。为此，请在项目中定位并打开以下文件：./src/adaptiveCardExtensions/geoLocation/quickView/template/QuickViewTemplate.json

将此文件的内容替换为以下内容：

{
  "schema": "http://adaptivecards.io/schemas/adaptive-card.json",
  "type": "AdaptiveCard",
  "version": "1.2",
  "body": [
    {
      "type": "TextBlock",
      "text": "${latitude}"
    },
    {
      "type": "TextBlock",
      "text": "${longitude}"
    }
  ],
  "actions": [
    {
      "title": "Choose location on map",
      "type": "VivaAction.GetLocation",
      "parameters": {
        "chooseLocationOnMap": true
      }
    },
    {
      "title": "Get my location",
      "type": "VivaAction.GetLocation"
    },
    {
      "title": "Show custom location",
      "type": "VivaAction.ShowLocation",
      "parameters": {
        "locationCoordinates": {
          "latitude": 27.98884062493244,
          "longitude": 86.9249751
        }
      }
    }
  ]
}

为此，我们提供了两个文本块来显示我们通过 VivaAction.GetLocation 获取的位置的 Latitude 和 Longitude。除此之外，我们还介绍了三个地理位置操作。

添加这些操作后，快速视图如下所示：

在快速视图中引入更改后的卡片外观

设置自适应卡片扩展的状态

到目前为止，我们已创建卡片视图和快速视图。如果此时执行 gulp serve，则可以执行上述操作。

但现在，让我们把它提高一个档次。

现在，我们希望在执行相应的操作时，在快速视图上显示用户的当前位置或用户所选位置的坐标。

为此，我们将利用前面在 QuickViewTemplate.json 文件中介绍的两个文本块

为此，我们将首先引入新状态。首先在项目中定位并打开以下文件：./src/adaptiveCardExtensions/geoLocation/GeoLocationAdaptiveCardExtension.ts

在此处，将下列 states 添加到 IGeoLocationAdaptiveCardExtensionState 接口：

latitude: string;
longitude: string;

接下来，在 onInit 函数中，将 this.state={} 改为

this.state = {
  latitude: 'TBD',
  longitude: 'TBD'
};

我们现在也会在快速视图中进行类似的更改。

在项目中定位并打开以下文件：./src/adaptiveCardExtensions/geoLocation/quickView/QuickView.ts

将下列属性添加到 IQuickViewData 接口：

latitude: string;
longitude: string;

然后在 data 获取程序的返回对象中添加以下两行：

latitude: "Latitude: " + this.state.latitude,
longitude: "Longitude: " + this.state.longitude

实施 onAction 函数

到目前为止，我们已创建并定义我们的地理位置操作，并在我们的州/省内努力操作。现在，我们终于可以实施 onAction 函数，这使第三方开发人员能够决定他们希望如何处理用户与其共享的位置坐标。

为此，打开 QuickView.ts 文件 (./src/adaptiveCardExtensions/geoLocation/quickView/QuickView.ts) 并导入 IGetLocationActionArguments 接口，如下所示：

import {IGetLocationActionArguments} from '@microsoft/sp-adaptive-card-extension-base';

最后，在 QuickView 类中引入以下 onAction 函数：

public onAction(action: IGetLocationActionArguments): void {
  if (action.type === 'VivaAction.GetLocation') {
    this.setState({
      latitude: action.location.latitude.toString(),
      longitude: action.location.longitude.toString()
    });
  }
}

因此，现在，每当从快速视图触发 VivaAction.GetLocation 操作时，根据传递的参数，自适应卡片扩展框架会将用户的当前坐标或用户选择的坐标传递给 onAction 回调。在上面共享的实施中，我们检查 action 类型是否为类型 VivaAction.GetLocation，如果是，则通过执行 setState 更新 latitude 和 longitude 文本块重新呈现快速视图。

此时，可以再次运行 gulp serve，并查看到目前为止所做的所有更改是如何汇集在一起的。

就是这样！祝贺你使用地理位置操作成功创建自适应卡片扩展。

通过