components.jsonファイルおよびフォーマットの理解

一般フォーマット

components.jsonファイルの一般フォーマットは、次のとおりです:

• コンポーネントのプロパティは、各コンポーネント内に指定されます。上位レベルの"components"または"apps"プロパティは、非推奨です。

• 各コンポーネントには、"type"プロパティがあります。コンポーネントには、特定の値のみを使用できます(使用可能な値はすべて、デフォルト・コンポーネントの表に示されています)。

• 各コンポーネントには"id"プロパティがあり、これは一意である必要があります。このプロパティを使用して、同じ"type"のコンポーネントを区別します。以前は、アプリケーションには"appName"プロパティがありました。"id"プロパティが使用可能でない場合、"appName"は依然として機能しますが、"appName"プロパティは非推奨です。

• 各コンポーネントには、ユーザー・インタフェース内の表示名である"name"プロパティがあります。フォールバック値が指定されていないときに、コンポーネントの場合、値は対応するデフォルト・コンポーネントの名前であり、リモート・コンポーネントの場合、値はIDです。

components.jsonファイルの例を次に示します:

[
    {
        "name": "COMP_CONFIG_TEXT_CATEGORY_NAME",
        "list": [
            {
                "type": "scs-title",
                "id": "my-headline",
                "name": "My Headline",
                ...
            },
            {
                ...
            },...
        ]
    },
    {
        "name": "My own category name",
        "list": [ ... ]
    }
]

一般構造は、カテゴリ・オブジェクトのJSON配列です。各カテゴリ・オブジェクトには、"name"プロパティおよび"list"プロパティがあります。"name"プロパティは、ローカライズされた文字列にマップするキーである場合があります。これらのデフォルトのカテゴリでは十分でない場合、ローカライズされない独自のカテゴリ名を指定できます。次の表は、使用可能なデフォルトのカテゴリおよび対応するキーを示しています。

各カテゴリ・オブジェクトの"list"プロパティには、コンポーネント・オブジェクトの配列が含まれます。各コンポーネントまたはオブジェクトには、"type"および"id"プロパティが必要です。その他のプロパティはオプションです。

• "type"プロパティは、デフォルト・コンポーネント内にあるタイプの1つと等しい必要があります。"type"がまだ存在しない場合、コンポーネントは表示されません。

• "id"プロパティは、コンポーネント全体にわたって一意である必要があります。"id"がすでに存在することが判明している場合、コンポーネントは表示されません。

• "name"プロパティは、ユーザー・インタフェース内のコンポーネントの表示名です。これにより、アプリケーション(現在はリモート・コンポーネント)の前の"appName"プロパティが置き換えられます。

• その他すべてのプロパティは、前のリリースの場合と同じように処理されます。

components.jsonへの新規コンポーネントの追加

デフォルト・コンポーネントを変更することはできません。ただし、既存のデフォルト・コンポーネントに基づいて新しいコンポーネントを作成できます。たとえば、"scs-title"コンポーネントに基づいて、デフォルト・テキストを設定する新しいコンポーネントを作成できます。新しいコンポーネントを追加する最小限の要件は、"type"および"id"プロパティを指定することです。

• "type"は、デフォルト・コンポーネント内にあるタイプの1つと等しい必要があります。"type"がまだ存在しない場合、コンポーネントは表示されません。

• "id"は、コンポーネント全体にわたって一意である必要があります。"id"がすでに存在することが判明している場合、コンポーネントは表示されません。

新しいタイトル・コンポーネントを追加するコードの例は、次のとおりです。このコンポーネントは、デフォルトのタイトル・コンポーネントとともに表示されます。

[
    {
        "name": "COMP_CONFIG_TEXT_CATEGORY_NAME",
        "list": [
            {
                "type": "scs-title",
                "id": "my-headline"
            }
        ]
    }
]

表示名とデフォルト・テキストを使用して新しいタイトル・コンポーネントを追加するコードの例は、次のとおりです。

[
    {
        "name": "COMP_CONFIG_TEXT_CATEGORY_NAME",
        "list": [
            {
                "type": "scs-title",
                "id": "my-headline",
                "name": "My Headline",
                "initialData": {
                    "userText": "This is a second title component"
                }
            }
        ]
    }
]

タイトル・コンポーネントはデフォルトのタイトル・コンポーネントのすべてのプロパティをベースとして使用し、その上部にテーマレベルの変更を適用して新しいコンポーネントを作成することに注意してください。

下位互換性

前のフォーマットのcomponents.jsonファイルを依然として読み取ることができます。

• 上位レベルの"components"または"apps"プロパティを持つファイル。

• ファイルに"apps"プロパティが含まれる場合、このプロパティの下位のユーザー定義済リモート・コンポーネントが依然としてロードされます。

• ファイルに上位レベルの"apps"プロパティが含まれる場合、その下位にリストされている任意のリモート・コンポーネントのタイプが"scs-app"であることを想定してください。

• "appName"プロパティが存在する場合、"id"を"appName"値に設定します。表示名は"name"と同じになるか(指定されている場合)、"id"値にフォールバックします。