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

9 分

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

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

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

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

このユニットでは、ユーザーのViva Connectionsと Viva Home エクスペリエンスを拡張するためのカスタム ACE の作成の 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 パーツと同様に、ACE は、既存の SharePoint Online サイトの SharePoint ホスト型ワークベンチを使用して開発およびテストできます。

カードの種類

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 を動的にすることができます。

たとえば、プロパティを持つ JSON オブジェクトを description 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 のチャンク機能を使用して、プロパティウィンドウを実装するスクリプトファイルのビジネスロジックを分割し、プロパティウィンドウがアクティブ化されたときに読み込みます。この最適化により、ACE を使用しているすべてのユーザーが、使用しないプロパティウィンドウスクリプトを常に読み込むとは限りません。

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() の方法があります。

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)