位置情報アクションを使用してアダプティブカード拡張機能を作成する

[アーティクル]
04/08/2023

注:

このチュートリアルは、SPFx v1.14 がインストールされていることを前提としています。

SPFx v1.14 のインストールの詳細については、「SharePoint Framework v1.14 のリリースノート」を参照してください。

アダプティブカード拡張機能プロジェクトをスキャフォールディングする

プロジェクトの新しいプロジェクトディレクトリを作成し、現在のフォルダーをそのディレクトリに変更します。

作成した新しいディレクトリから Yeoman の SharePoint ジェネレーターを実行して、新しいプロジェクトを作成します。

yo @microsoft/sharepoint

プロンプトが表示されたら、以下の値を入力します (以下で省略されたすべてのプロンプトに対して既定のオプションを選択します):

ソリューション名は何ですか? 地理位置情報チュートリアル
どの種類のクライアント側コンポーネントを作成しますか? アダプティブカードエディター
どのテンプレートを使用しますか? プライマリテキストテンプレート
アダプティブカード拡張機能の名前は何ですか? 位置情報

この時点で、Yeoman は必須の依存関係をインストールし、ソリューションファイルをスキャフォールディングします。このプロセスには数分かかる場合があります。

プロジェクトのホストされたワークベンチの URL を更新します。

gulp タスク serve を使用すると、既定ではブラウザーを起動し、プロジェクトで指定された、ホストされたワークベンチ 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 パーツツールボックスの位置情報カードアイコンを参照する

アダプティブカード拡張機能に位置情報アクションを追加する

この時点で、すぐにスキャフォールディングされたコードを取得しました。ここで、カードビューとクイックビューエクスペリエンスに位置情報アクションを追加してみましょう。

カードビューとクイックビューを含むカードを作成します。カードビューにボタンが表示され、ユーザーの現在の場所が表示され、カードビュー自体をクリックするとクイックビューが開きます。

クイックビューでは、次の操作を実行する 3 つのボタンを提供します。

ユーザーの現在の場所を取得する
ユーザーがマップから場所を選択できるようにする
マップ上の特定の場所を表示する

カードに表示されるラベルを更新する

アクションの追加を開始する前に、まずカードに表示される文字列を更新します。

このためには、プロジェクトで次のファイルを見つけて開きます。./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 を表示するための 2 つのテキストブロックがあります。これは、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 を示す 2 つのテキストブロックを提供しています。これらに加えて、3 つの位置情報アクションについて説明しました。

これらのアクションを追加すると、クイックビューは次のようになります。

クイックビューの変更を導入した後のカードの外観

アダプティブカード拡張機能の状態を設定する

ここまでは、カードビューとクイックビューを作成しました。この時点で gulp serve を実行すると、上記のアクションを実行できます。

しかし、ここで、さらに高いレベルにしましょう。

ここでは、ユーザーの現在位置またはユーザーが選択した位置の座標を、それぞれのアクションが実行されたときにクイックビューに表示します。

ここでは、QuickViewTemplate.json ファイルで前に導入した 2 つのテキストブロックを活用します。

これを行うために、まず新しい状態を導入します。まず、プロジェクトで次のファイルを見つけて開きます。./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 getter の返されたオブジェクトに次の 2 行を追加します。

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 を再度実行し、これまでに行ったすべての変更がどのように一緒に行われたかを確認できます。

そうなんです。位置情報アクションを使用してアダプティブカード拡張機能を正常に作成できました。

次の方法で共有

位置情報アクションを使用してアダプティブカード拡張機能を作成する

アダプティブカード拡張機能プロジェクトをスキャフォールディングする

プロジェクトのホストされたワークベンチの URL を更新します。

アダプティブカード拡張機能に位置情報アクションを追加する

カードに表示されるラベルを更新する

カードビューにアクションを追加する

クイックビューにアクションを追加する

アダプティブカード拡張機能の状態を設定する

onAction 関数を実装する

その他のリソース

次の方法で共有

位置情報アクションを使用してアダプティブ カード拡張機能を作成する

アダプティブ カード拡張機能プロジェクトをスキャフォールディングする

プロジェクトのホストされたワークベンチの URL を更新します。

アダプティブ カード拡張機能に位置情報アクションを追加する

カードに表示されるラベルを更新する

カード ビューにアクションを追加する

クイック ビューにアクションを追加する

アダプティブ カード拡張機能の状態を設定する

onAction 関数を実装する

その他のリソース

位置情報アクションを使用してアダプティブカード拡張機能を作成する

アダプティブカード拡張機能プロジェクトをスキャフォールディングする

アダプティブカード拡張機能に位置情報アクションを追加する

カードビューにアクションを追加する

クイックビューにアクションを追加する

アダプティブカード拡張機能の状態を設定する