テーマを拡張してモジュール拡張機能を追加する

[アーティクル]
05/28/2024

この記事では、Microsoft Dynamics 365 Commerce でのモジュール拡張子を追加するテーマを拡張する方法について説明します。

Dynamics 365 Commerce e-Commerce テーマには、オプションで、Commerce モジュールライブラリ内のモジュールセットまたはカスタムモジュールのいずれかに対する次のモジュール拡張を含めることができます。

モジュールに新しいレイアウトビューを提供するモジュールビュー拡張機能
モジュールの構成を変更する定義拡張
追加のデータアクションを呼び出すデータアクション拡張機能

テーマモジュールビューの拡張機能

テーマでは、カスタマイズされたモジュールビューの拡張機能を含めることができます。これは一般的に、選択したテーマ用にモジュールの既定のレイアウトを変更するために使用されます。これらのカスタマイズされたモジュールビュー拡張機能は、モジュールライブラリモジュールとカスタムモジュールの両方でサポートされます。たとえば、モジュールライブラリモジュールに新しいボタンを追加して、追加の機能をサポートする場合があります。ビュー拡張子を作成すると、clone コマンドラインインターフェイス (CLI) コマンドを使用してモジュールライブラリモジュールの完全コピーを作成する必要がなくなります。場合によっては、モジュール定義を拡張し、さらに構成プロパティ、スロット、またはリソースを追加することもできます。モジュールビュー拡張機能を作成する方法の詳細については、この記事のモジュールビューの拡張機能の作成セクションを参照してください。

表示拡張機能は、....\src\themes\THEME_NAME\views ディレクトリの下に格納され、モジュールビューの名前付けパターン (MODULE_NAME.view.tsx) のような名前付けパターンに従います。たとえば、ビュー拡張機能に product-feature.view.tsx という名前が付けられます。選択したテーマにビュー拡張機能が存在する場合、React コンポーネントは既定のビューファイルの代わりにそれを呼び出します。したがって、ビューの拡張機能は、モジュールに使用されるモジュールビューとまったく同じように記述できます。

一般に、モジュールライブラリモジュールの 1 つについて既存のビューファイルを調べてから、そのモジュールで新しいビューを作成することができます。また、既存のビューファイルに追加コードをコピーおよび貼り付けも必要になる場合があります。モジュールライブラリモジュールビューのソースコードを表示するには、...\node_modules\@msdyn365-commerce-modules のディレクトリを開いて、必要なモジュールを探します。相対パスのインポートでファイルパスの参照を固定する必要がある場合があります。

モジュールビュー拡張機能の作成

オンラインソフトウェア開発キット (SDK) は add-view-extension CLI コマンドが用意されています。 Commerce で新しいモジュールビュー拡張子を作成するには、yarn msdyn365 add-view-extension THEME_NAME MODULE_NAME を実行します。THEME_NAME はビュー拡張機能を追加するテーマの名前に、MODULE_NAME を拡張するモジュールの名前に置き換えてください。

たとえば、次のコマンドを実行して、product-feature.view.ts という名前の新しいファイルを spring-theme テーマのビューディレクトリに追加します。

yarn msdyn365 add-view-extension spring product-feature

次の例は、前述のコマンドを使用して作成されたビューファイル拡張機能を示しています。

import * as React from 'react';
import { ISampleModuleViewProps } from '../../../modules/product-feature/./product-feature';

export default (props: IProductFeatureViewProps) => {
    return (
        <div className='row'>
            <h2>Config Value: {props.config.showText}</h2>
            <h2>Resource Value: {props.resources.resourceKey}</h2>
        </div>
    );
};

テーマ定義拡張機能

モジュール定義の config、slots、dataActions、またはresources セクションを拡張し、モジュールビュー拡張機能からこれらのセクションにアクセスする必要があるシナリオがある場合があります。新しいコンフィギュレーション、ス施設、およびリソースを追加することができますが、既存のコンフィギュレーションは変更できます。ただし、disableConfigProperties セクションを使用すると、一部の構成の継承を無効にすることができます。

定義拡張機能は、definition-extensions フォルダーの下に格納されます。これらは命名パターン MODULE_NAME.definition.ext.json に従います。MODULE_NAME は拡張するモジュールの名前です。

モジュール定義拡張機能の作成

新しい定義の拡張子を作成するには、/src/themes/THEME_NAME/definition-extensions フォルダの下に、拡張するモジュールにマッチした新しいファイルを作成します。例えば、定義拡張機能のパスは src/themes/spring-theme/definition-extensions/product-feature.definition.ext.json のようになります。

次の例は、新しいデータアクションに加えて、いくつかの構成、スロット、およびリソースが追加されたテーマ定義拡張ファイルを示しています。 $type プロパティは "definitionExtension" に設定する必要があることに注意してください。定義ファイルでは、この例に示すように、dataActions、config、slot、resources の各ノードの下に新しいプロパティを宣言することができます。

{
    "$type": "definitionExtension",
    "dataActions": {
        "products": {
            "path": "@msdyn365-commerce-modules/retail-actions/dist/lib/get-simple-products",
            "runOn": "server"
        },
        "cartNameExtension": {
            "path": "../../../actions/cart-extension.action",
            "runOn": "server"
        }
    },
    "config": {
        "subTitle": {
            "type": "string",
            "friendlyName": "Sub Title",
            "description": "Sub Title for additional information"
        },
        "favoriteIcon": {
            "type": "image",
            "friendlyName": "Favorite icon",
            "description": "Favorite icon"
        },
        "favoriteIconSettings": {
            "friendlyName": "Favorite icon Settings",
            "description": "Image settings for the favorite icon property",
            "type": "imageSettings"
        }
    },
    "slots": {
        "content":
        {
            "friendlyName": "Content Slot",
            "description": "This is the content slot",
            "allowedCategories": ["container"],
            "max": 10,
            "min": 0
        }
    },
    "resources": {
        "recommendedLocations": {
            "value": "Recommended Locations"
        }
    },
    "disableConfigProperties": ["subTitle", "imageAlignment"]
}

disableConfigProperties セクションを使用すると、無効にする設定フィールドを定義することができます。無効化された構成項目は、テーマ設定時に選択されたモジュールの Commerce サイトビルダーで設定可能なオプションとして表示されません。

yarn startコマンドを実行すると、新しい props ファイルが自動的に生成され、定義拡張機能ディレクトリに表示されます。このファイルには、定義拡張機能ファイルに定義されたプロパティとルールに基づいて、親モジュールと拡張モジュールのマージが含まれています。

定義拡張機能をモジュールビュー拡張機能と一緒に使用している場合、新しい定義の変更を利用するために、ビューファイルで新しい自動生成ファイルへの参照を追加する必要があります。

次の例では、新しい自動生成ファイルを追加しています。この例では、モジュールデータファイルが必要な場合はそれもインポートしています。

import * as React from 'react';
import { IProductFeatureViewProps } from '../../../modules/product-feature/./product-feature';
import { IProductFeatureProps } from '../definition-extensions/product-feature.ext.props.autogenerated';

export default (props: IProductFeatureViewProps & IProductFeatureProps<{}>) ) => {
    return (
        <div className='row'>
            <h2>Config Value: {props.config.showText}</h2>
            <h2>New Config SubTitle Value: {props.config.subTitle}</h2>
            <h2>Resource Value: {props.resources.resourceKey}</h2>
        </div>
    );
};

データアクション拡張機能

テーマが選択された後、モジュールテーマ定義拡張機能ファイルに追加されたデータアクションは、そのモジュールを使用するページがロードされたときにトリガーされます。モジュールテーマ拡張機能に追加されたデータアクションは、オリジナルモジュールに定義されたデータアクションの前に呼び出されます。

データアクション呼び出しからの戻りデータは、テーマの /views ディレクトリの下にある THEME_NAME.data.ts ファイルで宣言する必要があります。次の例は、cart-extension.action という名前のデータアクションを呼び出すテーマのファイル構造を示しています。新しいデータアクションは actions フォルダーに含まれていることに注意してください。先に示した定義拡張ファイルの例には、追加のデータアクションである cart-extension が含まれており、これは *.definition.ext.json ファイル内から相対パスを使用して呼び出されます。

src
|__actions
__|__cart-extension.action.ts
|__modules
|__themes
|__|__spring
|__|__|__|__definition-extensions
__|__|__|__|__product-feature.definition.ext.json
|__|__|__|__styles
|__|__|__|__view
__|__|__|__|__product-feature.data.ts
__|__|__|__|__product-feature.view.tsx

データアクションから返されるデータは、views ディレクトリの MODULE_NAME.data.ts ファイルで宣言された変数に代入する必要があります。変数名は、モジュール定義拡張機能ファイルの dataAction セクションで提供される名前と一致する必要があります。次の例では、変数名 cartNameExtension が、先に示した定義拡張機能ファイルの例で提供される変数名と一致していることに注意してください。

import { AsyncResult } from '@msdyn365-commerce/retail-proxy';

export interface ICartExtensionData {
    cartNameExtension: AsyncResult<string>;
    products: AsyncResult<SimpleProduct>[];
}

新しいデータアクションから返されるデータを消費するために、次の product-feature.view.tsx の例に示すように、モジュールビューファイルは、新しいインターフェイスをインポートすることができます。

import * as React from 'react';
import { ICartExtensionData } from './product-feature.data';
import { IProductFeatureViewProps } from '../../../modules/product-feature/./product-feature';
import { IProductFeatureProps } from '../definition-extensions/product-feature.ext.props.autogenerated';

export default (props: IProductFeatureViewProps & IProductFeatureProps<{ICartExtensionData}>) ) => {
    return (
        <div className='row'>
            <h2>Config Value: {props.config.showText}</h2>
            <h2>New Config SubTitle Value: {props.config.subTitle}</h2>
            <h2>Resource Value: {props.resources.resourceKey}</h2>
            <h2>Cart Extension Value: {props.data.cartName}</h2>
        </div>
    );
};