ACE の基本: カードテンプレート、CardViews、プロパティ、および状態

9 分

顧客は、Viva ConnectionsとViva Home を複数の方法でカスタマイズして、顧客に合わせたエクスペリエンスを作成できます。

開発者は、SharePoint Framework (SPFx) を使用して作成された Web パーツでViva Connectionsをカスタマイズおよび拡張できます。その後、エディターは Web パーツをページのコンテンツ領域に配置し、ユーザー向けにカスタマイズされたエクスペリエンスを作成するように構成できます。

開発者は、ページのヘッダーとフッターに HTML と JavaScript を挿入できる SPFx 拡張機能の一種である SPFx アプリケーションカスタマイザーを作成することもできます。

開発者がViva ConnectionsとViva Home をカスタマイズするもう 1 つの方法は、アダプティブカード拡張機能 (ACE) を使用することです。 ACE は Web パーツに似ていますが、主にアダプティブカードを使用してユーザーエクスペリエンスを実装します。

このユニットでは、ACE とは何か、そのしくみ、Viva ConnectionsとViva Home 用のカスタム ACE を作成する方法について説明します。

アダプティブカード拡張機能 (ACEs)

Viva Home と Viva Connections ダッシュボードとモバイルエクスペリエンスは、ACE を使用して拡張およびカスタマイズできます。開発者は SPFx を使用してカスタム ACE を作成し、Viva Connections ダッシュボードとViva Connections モバイルアプリでカスタマイズされたエクスペリエンスを有効にします。

デスクトップ上Viva Connectionsダッシュボードのスクリーンショット。

ACE を使用すると、ユーザーは情報をすばやく一目で表示したり、焦点を絞ったモバイルフレンドリーなエクスペリエンスでカードと対話したりできます。

Viva Connectionsモバイルエクスペリエンスのスクリーンショット。

開発者は、SPFx を使用して新しい ACE を作成できます。 Microsoft は、2021 年後半にリリースされた SPFx v1.13 に ACE の作成のサポートを追加しました。これにより、Web パーツ、拡張機能、およびライブラリコンポーネントの既存のサポートに 4 番目のコンポーネントの種類が追加されました。

ACE は Web パーツに似ているので、Web パーツを作成する方法がわかっている場合は、ACE の作成に慣れているでしょう。 Web パーツと同様に、SharePoint Online サイトの SharePoint ホストワークベンチを使用して ACE を開発およびテストできます。

カードの種類

Viva Connectionsと SPFx では、いくつかの種類のカードビューがサポートされています。これには、基本的なカードビュー、イメージカードビュー、プライマリテキストカードビューが含まれます。これらの異なるカードの種類にはそれぞれ、CardView で設定できるプロパティに微妙な違いがあります。

基本カードテンプレート

Basic Card テンプレートでは、次の 2 つのプロパティがサポートされています。

ACE のtitle。通常、SharePoint Frameworkの Yeoman ジェネレーターを使用してプロジェクトを作成するときに設定されます。
カードに関するコンテキストをユーザーに提供するために使用される ACE のprimaryText。

ACE Basic カードテンプレートのスクリーンショット。

イメージカードビュー

イメージカードテンプレートでは、次の 3 つのプロパティがサポートされています。

ACE のtitle。通常、SharePoint Frameworkの Yeoman ジェネレーターを使用してプロジェクトを作成するときに設定されます。
カードに関するコンテキストをユーザーに提供するために使用される ACE のprimaryText。
カードに表示するイメージのimageUrl。

ACE イメージカードテンプレートのスクリーンショット。

カードサイズを大きく設定すると、カードの右側に画像が表示されます。中のカードに設定すると、イメージはカードのタイトルの上にレンダリングされます。

プライマリテキストカードビュー

プライマリテキストカードテンプレートでは、次の 3 つのプロパティがサポートされています。

ACE のtitle。通常、SharePoint Frameworkの Yeoman ジェネレーターを使用してプロジェクトを作成するときに設定されます。
カードに関するコンテキストをユーザーに提供するために使用される ACE のprimaryText。
ACE の description は、より多くのテキスト情報をユーザーに表示するために使用されます。

ACE プライマリテキストカードテンプレートのスクリーンショット。

ビューの種類

ACE は、次の 2 種類のビューに基づいています。

CardView

CardView は、レンダリング時の ACE の既定のビューです。 CardView は、中または大の 2 つのサイズのいずれかでレンダリングされます。

メディアビューには、一部のテキストと 1 つまたはまったくボタンを含めることができます。

既定の CardView ACE 中規模レンダリングのスクリーンショット。

CardView の大きなビューオプションには、最大 2 つのボタンと必要に応じて画像のテキストを含めることができます。

既定の CardView ACE ラージサイズレンダリングのスクリーンショット。

新しい ACE を作成するときに、CardView で使用できるプロパティを定義する 3 つの使用可能なカードテンプレートのいずれかを選択します。

QuickView

ACE でサポートされるもう 1 つの種類のビューは QuickView です。 QuickView は、CardView との対話に基づいてレンダリングされます。ユーザーが CardView を選択したとき、またはいずれかのボタンが選択されたときに表示できます。

ユーザーが CardView のボタンを選択したときの QuickView のスクリーンショット。

CardView とは異なり、QuickView レンダリングはアダプティブカード JSON スキーマで実装されます。開発者は、プレースホルダーがテンプレートにバインドされたデータを別のオブジェクトとして参照できるアダプティブカードテンプレート機能を使用して、QuickView を動的にすることができます。

たとえば、 description プロパティを持つ JSON オブジェクトを QuickView にバインドできます。

{
  "description": "This is some description to display on the QuickView"
}

QuickView で使用されるアダプティブカードのプロパティを参照するには、次のように ${} 概念を使用します。

{
  "type": "TextBlock",
  "text": "${description}",
  "wrap": true
}

ACE の作成

開発者は、SPFx Web パーツ、拡張機能、およびライブラリコンポーネントの作成に使用されるのと同じ Yeoman Generator for SharePoint を使用してアダプティブカードを作成できます。

コア ACE クラスを調べる

ACE は 、*AdaptiveCardExtension.ts ファイルを使用して実装されます。このファイルは、ACE の実装に使用される 3 種類のメンバーをエクスポートします。

コンポーネントのパブリックプロパティと状態を定義するインターフェイス
ACE で使用される各 QuickView の一意の ID を定義する定数
ACE のハブとして機能するクラス

ACE クラスには、SPFx Web パーツに似たいくつかの既定のメソッドが含まれています。

onInit() メソッドは、状態の初期化、ビューの登録、データタスクの事前読み込みを処理するために使用されます。このメソッドとこれらの問題の一部については、モジュールの後半で再検討します。

public onInit(): Promise<void> {
  this.state = { };

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

  return Promise.resolve();
}

getPropertyPaneConfiguration() メソッドと loadPropertyPaneResources() メソッドは、構成可能なパブリックプロパティを持つ ACE のプロパティウィンドウを初期化、構成、および読み込む際に使用されます。

ACE モバイルエクスペリエンスをより適切にサポートするために、 loadPropertyPaneResources() メソッドは Webpack チャンク機能を使用して、プロパティウィンドウを実装するスクリプトファイルのビジネスロジックを分割し、プロパティウィンドウがアクティブ化されたときに読み込みます。この最適化により、ユーザーはプロパティウィンドウスクリプトを使用しない場合に読み込まれません。

protected loadPropertyPaneResources(): Promise<void> {
  return import(
    /* webpackChunkName: 'HelloWorld-property-pane'*/
    './HelloWorldPropertyPane'
  )
    .then(
      (component) => {
        this._deferredPropertyPane = new component.HelloWorldPropertyPane();
      }
    );
}

protected getPropertyPaneConfiguration(): IPropertyPaneConfiguration {
  return this._deferredPropertyPane?.getPropertyPaneConfiguration();
}

最後に、 renderCard() メソッドは Web パーツの render() メソッドに似ています。 ACE のレンダリングに使用する CardView の ID を返します。

protected renderCard(): string | undefined {
  return CARD_VIEW_REGISTRY_ID;
}

CardView クラスを調べる

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

cardButtons() メソッドは、CardView にレンダリングされるボタンを定義するICardButton型の 0、1、または 2 つのオブジェクトを返します。 CardView テンプレートによって、さまざまな要因に応じて表示できるボタンの数が制限されます。たとえば、プライマリテキストカードテンプレートでは、 サイズ が 大きいに設定されている場合にのみ 2 つのボタンを表示できます。

public get cardButtons(): [ICardButton] | [ICardButton, ICardButton] | undefined {
  return [
    {
      title: strings.QuickViewButton,
      action: {
        type: 'QuickView',
        parameters: {
          view: QUICK_VIEW_REGISTRY_ID
        }
      }
    }
  ];
}

data() メソッドは、アダプティブカードテンプレートを使用して CardView のテンプレートにバインドされているオブジェクトを返します。このオブジェクトのプロパティは、プロジェクトの作成時に選択されている現在の ACE カードテンプレートでサポートされているプロパティと一致する必要があります。たとえば、次の data() メソッドは Basic カードテンプレート用です。

public get data(): IBasicCardParameters {
  return {
    primaryText: strings.PrimaryText,
    title: this.properties.title
  };
}

最後に、 onCardSelection() メソッドを使用して、CardView が選択された場合の動作を制御します。たとえば、次の実装では、CardView が選択されている場合、新しいブラウザータブにリンクが開きます。

public get onCardSelection(): IQuickViewCardAction | IExternalLinkCardAction | undefined {
  return {
    type: 'ExternalLink',
    parameters: {
      target: 'https://www.bing.com'
    }
  };
}

ACE を使用して構成可能なプロパティ

SPFx Web パーツと同様に、ACE では構成可能なプロパティがサポートされ、エディターは ACE の各インスタンスをカスタマイズできます。プロパティはコンポーネントと同じファイルで定義されているため、実装は Web パーツに似ています。

たとえば、ACE が SharePoint リストのデータを表示する場合、プロパティインターフェイスが次のように表示されるように、リストの ID への参照を格納する必要があります。

export interface ISharePointRestAdaptiveCardExtensionProps {
  title: string;
  listId: string;
}

Web パーツと同様に、既定値はコンポーネントの *.manifest.json ファイルの preconfiguredEntries.properties オブジェクトで設定できます。

Web パーツとの違いの 1 つは、ACE がモバイル優先のアプローチを中心に設計されていることです。プロパティウィンドウの場合、プロパティウィンドウのレンダリングを定義するためのコードは、コンポーネントの残りの部分から分離されます。ジェネレーターによって ACE 用に作成された最初のコードは、プロパティウィンドウ定義を別のファイルに配置します。

export class SharePointRestPropertyPane {
  public getPropertyPaneConfiguration(): IPropertyPaneConfiguration {
    return {
      pages: [
        {
          header: { description: strings.PropertyPaneDescription },
          groups: [
            {
              groupFields: [
                PropertyPaneTextField('title', {
                  label: strings.TitleFieldLabel
                }),
                PropertyPaneTextField('listId', {
                  label: 'List ID (GUID)'
                })
              ]
            }
          ]
        }
      ]
    };
  }
}

データバインド ACE QuickView のスクリーンショット。

ACE コンポーネントの状態

Reactを使用して SPFx Web パーツを構築した場合は、コンポーネントの状態の概念をよく理解している可能性があります。 ACE は、状態が変わると ACE が再レンダリングされるようにトリガーするという点で同じ概念を実装します。

コンポーネントの状態は、ACE 自体だけでなく、すべてのビューでアクセスできます。これには、CardView と ACE で使用されるすべてのクイックビューの両方が含まれます。

コンポーネントの状態は、パブリックプロパティと同様に、コンポーネントと同じファイル内のインターフェイスで定義されます。

SharePoint リストからデータを表示する ACE のシナリオ例を続けて、SharePoint リストから取得したすべてのアイテムのコピーを保持することが必要な場合があります。

export interface ISharePointRestAdaptiveCardExtensionState {
  listTitle: string;
  listItems: IListItem[];
}

コンポーネントで状態を使用する場合は、コンポーネントの onInit() メソッドで初期状態を正しく設定してください。

public async onInit(): Promise<void> {
  this.state = {
    listTitle: '',
    listItems: []
  };

  // .. omitted for brevity
}

その後、 onInit() メソッドを使用してリストの項目を取得したり、他のイベントで同じプロセスをトリガーしたりできます。たとえば、プロパティウィンドウのフィールドが更新されたときに呼び出される onPropertyPaneFieldChanged() メソッドを実装して、同じことを行うことができます。

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

  if (this.properties.listId) {
    Promise.all([
      this.setState({ listTitle: await fetchListTitle(this.context, this.properties.listId) }),
      this.setState({ listItems: await fetchListItems(this.context, this.properties.listId) })
    ]);
  }

  return Promise.resolve();
}

protected onPropertyPaneFieldChanged(propertyPath: string,
                                     oldValue: any,
                                     newValue: any): void {
  if (propertyPath === 'listId' && newValue !== oldValue) {
    if (newValue) {
      (async () => {
        this.setState({ listTitle: await fetchListTitle(this.context, newValue) });
        this.setState({ listItems: await fetchListItems(this.context, newValue) });
      })();
    } else {
      this.setState({ listTitle: '' });
      this.setState({ listItems: [] });
    }
  }
}

概要

このユニットでは、ユーザーのViva Connections エクスペリエンスを拡張するためのカスタム ACE の作成について、ACE とは何か、そのしくみ、および基本について学習しました。

ACE の基本: カード テンプレート、CardViews、プロパティ、および状態

アダプティブ カード拡張機能 (ACEs)