ACE QuickViews とビューナビゲーターの操作

10 分

アダプティブカード拡張機能 (ACE) のレンダリングは、CardViews と QuickViews の 2 種類のビューを使用して実装されます。

このユニットでは、QuickView、両方の種類のビューで使用されるナビゲーター、アダプティブカードの一般的な手法とシナリオについて詳しく説明します。

QuickView

ACE の QuickView は最初は表示されません。CardView は、デスクトップとモバイルViva Connections最初に表示されるものです。

QuickView は、CardView とのユーザー操作に基づいて表示されます。これは、マウスで ACE が選択されている場合、または CardView のボタンのいずれかが選択されている場合に発生します。

ACE の CardView は ./[..] に実装されていますが、/cardView/CardView.ts ファイル、クイックビューは ./[..] にあります。/quickView フォルダー。 Yeoman ジェネレーターによって作成された初期 QuickView.ts ファイルには、3 つのメソッドが含まれています。

QuickView.template()

template() メソッドは、QuickView のレンダリングを定義するアダプティブカードの JSON を返します。

public get template(): ISPFxAdaptiveCard {
  return require('./template/QuickViewTemplate.json');
}

既定のアダプティブカードテンプレートは ./[..] にあります。/quickView/template フォルダー。これは要件ではありません。メソッドは、QuickView のアダプティブカードを実装するために使用される JSON を返す必要があります。

QuickView.data()

CardView と同様に、 data() メソッドは、アダプティブカードテンプレートを使用して QuickView のテンプレートにバインドされているオブジェクトを返します。このオブジェクトのプロパティは、QuickView のアダプティブカード実装内で使用する必要があるプロパティと一致する必要があります。

たとえば、次の data() メソッド...

public get data(): IQuickViewData {
  return this.state.listItems[this.state.currentIndex]);
}

...は、 listItems 配列で現在選択されている項目のすべてのプロパティを含むオブジェクトを返します。これらのプロパティ (リストアイテムの ID、 Title、 Description プロパティなど) は、アダプティブカードで使用される ${} 表記からわかるように、関連付けられているアダプティブカードテンプレートで想定されます。

{
  "type": "Container",
  "items": [
    {
      "type": "TextBlock",
      "text": "(${ID}) ${Title}",
      "horizontalAlignment": "Center",
      "size": "Medium",
      "weight": "Bolder",
      "wrap": true
    },
    {
      "type": "TextBlock",
      "text": "${Description}",
      "horizontalAlignment": "Center",
      "size": "Default",
      "wrap": true
    }
  ]
}

QuickView.onAction()

最後に、アダプティブカードレンダリング内でアクションが発生すると、onAction() メソッドが SharePoint Framework (SPFx) によって呼び出されます。アクションには、送信アクション、または ACE が、Viva Connectionsでサポートされている地理的な場所またはメディアの選択機能を使用する場合が含まれます。

public onAction(action: IActionArguments): void {
  if (action.type !== 'Submit') { return ;}

  if (action.id === 'next') {
    let currentIndex = this.state.currentIndex;
    this.setState({ currentIndex: currentIndex + 1 });
  }
}

ACE ビューナビゲーター

ACE 開発者が理解している必要があるもう 1 つの点は、ビューナビゲーターです。ビューナビゲーターは、ACE が使用できるすべての CardView と QuickView を追跡するために ACE によって使用されます。

CardViews と QuickView の登録

2 種類のビューを使用するには、まずそれぞれのビューナビゲーターに登録する必要があります。登録には、ビューの ID とビューを実装するオブジェクトの設定が含まれます。

ACE を定義するクラスを含むメインファイル (*AdaptiveCardExtension.ts ファイル) には、すべてのビューの ID が含まれています。

CardViews の ID は、同じファイルで定義されているクラス内でのみ参照されるため、通常はモジュールによってエクスポートされません。

const CARD_VIEW_REGISTRY_ID: string = 'SharePointRest_CARD_VIEW';

ただし、QuickView の ID は CardView やその他のクイックビューで参照されているため、このモジュールからエクスポートされます。

export const QUICK_VIEW_REGISTRY_ID: string = 'SharePointRest_QUICK_VIEW';

すべてのビューの登録は、ACE の onInit() メソッドで行われます。次のコードが、ビューの ID とビューオブジェクトのインスタンスという 2 つのパラメーターを渡す方法に注目してください。

import { CardView } from './cardView/CardView';
import { QuickView } from './quickView/QuickView';

// .. omitted for brevity

export default class SharePointRestAdaptiveCardExtension extends BaseAdaptiveCardExtension<
  ISharePointRestAdaptiveCardExtensionProps, ISharePointRestAdaptiveCardExtensionState> {
  // .. omitted for brevity

  public async onInit(): Promise<void> {
    // .. omitted for brevity

    this.cardNavigator.register(CARD_VIEW_REGISTRY_ID, () => new CardView());
    this.quickViewNavigator.register(QUICK_VIEW_REGISTRY_ID, () => new QuickView());

    // .. omitted for brevity
  }

  // .. omitted for brevity
}

ビューナビゲーターの操作

ビューナビゲーター、 cardViewNavigator 、 quickViewNavigator はどちらも、基本的にスタックまたはビューを含む配列です。スタックの最上位の項目は、特定のビューが指定されていない限り、SPFx ACE レンダリングエンジンによってレンダリングされます。

一部の QuickView 実装を使用してビューナビゲーターと対話する方法を見てみましょう。次のような状況で問題が発生します。

ユーザーから情報を収集するフォームを含む QuickView を表示する場合。これは CardView のボタンによってトリガーできます。 CardView.cardButtons() メソッドは、action.typeが QuickView に設定されているボタンを返すことができます。 view パラメーターは、表示するクイックビューを SPFx に指示します。 SPFx では、ID を使用して QuickView を検索して表示します。

public get cardButtons(): [ICardButton] | [ICardButton, ICardButton] | undefined {
  return [{
    title: 'Book a Trip',
    action: {
      type: 'QuickView',
      parameters: { view: QUICK_VIEW_START_TRIP_REGISTRY_ID }
    }
  }];
}

CardView からの QuickView アクティブ化のスクリーンショット。

QuickView には、いくつかのボタンが含まれています。最初の 2 つのボタンは、他の QuickView を起動してユーザーから追加情報を収集するアクションです。

export class StartTrip extends BaseAdaptiveCardView<
  ICampusShuttleAdaptiveCardExtensionProps,
  ICampusShuttleAdaptiveCardExtensionState,
  IStartTripData
> {
  // .. omitted for brevity

  public onAction(action: IActionArguments): void {
    if (action.type === 'Submit') {
      if (action.id === 'originLocation') {
        this.quickViewNavigator.push(QUICK_VIEW_SET_ORIGIN_REGISTRY_ID);
      } else if (action.id === 'destinationLocation') {
        this.quickViewNavigator.push(QUICK_VIEW_SET_DESTINATION_REGISTRY_ID);
      } else if (action.id === 'save') {
        (async () => {
          await upsertListItem(this.context, this.properties.listId, this.state.currentTrip);
          this.quickViewNavigator.push(QUICK_VIEW_SAVE_TRIP_REGISTRY_ID);
        })();
      }
    }
  }
}

たとえば、ユーザーが [旅行先の選択/設定 ] ボタンを選択した場合、 this.quickViewNavigator.push() メソッドを呼び出して、変換先セレクター QuickView を起動します。これにより、ACE レンダリングエンジンは、異なる QuickView を使用して QuickView の内容を置き換えます。

QuickView 変換先セレクターのスクリーンショット。

フォームを完了すると、ユーザーが [保存先の場所を保存 ] ボタンを選択すると、その QuickView の onAction() ハンドラーが最初にコンポーネントの状態を更新し、ナビゲーターから現在の QuickView を ポップ して、最初のフォーム QuickView が先頭に表示され、再レンダリングされます。

public onAction(action: IActionArguments | IGetLocationActionArguments): void {
  const currentTrip = this.state.currentTrip;

  // logic to handle updating the trip destination object
  //    based on the selection in the form

  this.setState({ currentTrip: currentTrip });
  this.quickViewNavigator.pop();
}

ユーザーが最初のフォームで [旅行の保存 ] ボタンを選択すると、保存確認を表示する QuickView が QUICK_VIEW_SAVE_TRIP_REGISTRY_ID ID を使用して表示されます。

クイックビューの保存の旅行の確認のスクリーンショット。

最後に、ユーザーが最後の [閉じる ] ボタンを選択すると、ナビゲーターの close() メソッドを使用して QuickView 全体が閉じられます。

{
  "schema": "http://adaptivecards.io/schemas/adaptive-card.json",
  "type": "AdaptiveCard",
  "version": "1.2",
  "body": [{
    "type": "TextBlock", "text": "${title}"
  }],
  "actions": [{
    "type": "Action.Submit",
    "id": "close", "title": "Close"
  }]
}

public onAction(action: IActionArguments): void {
  if (action.id === 'close') {
    this.quickViewNavigator.close();
  }
}

QuickView の読み込みを延期する

開発者は、高度な操作のために複数の QuickView を使用して複雑な ACE を作成できます。ほとんどのユーザーがすべての QuickView を使用していない場合は、必要な場合にのみ読み込む方が適しています。これにより、ダウンロードサイズが縮小され、ページの読み込みが高速化されます。

これを実装するには、通常 ACE のコンポーネントファイルの先頭にある QuickView の import ステートメントを削除します。

import { QuickView } from './quickView/QuickView';

次に、メソッド呼び出しを次のコードで更新して、SPFx ACE ランタイムで必要な場合にのみコンポーネントを読み込みます。

// this.quickViewNavigator.register(QUICK_VIEW_REGISTRY_ID, () => new QuickView());
this.quickViewNavigator.register(
  QUICK_VIEW_REGISTRY_ID,
  () => import('./quickView/QuickView').then((c) => new c.QuickView())
);

概要

このユニットでは、QuickViews、両方の種類のビューで使用されるナビゲーター、アダプティブカードで使用できる一般的な手法とシナリオについて学習しました。

ACE QuickViews とビュー ナビゲーターの操作