Documentation

スタイルブックトークンの定義

対応可能:Liferay DXP/Portal 7.3以降

スタイルブックには、テーマごとに定義されたさまざまなカテゴリにグループ化されたオプションがあります。 各オプションは トークン で定義されます。 1つのテーマに対して定義されたすべてのトークンのコレクションが トークン定義 です。

サイトのページにテーマを割り当てると、そのテーマに含まれるトークン定義が、サイトのスタイルブックを作成する際に使用されます。

スタイルブックのトークン定義

トークン定義はテーマに関連付けられているため、トークン定義はテーマモジュールに含まれているCSS変数に対応している必要があります。 トークン定義自体は、テーマモジュールのsrc/WEB-INF/フォルダ内にある.jsonファイルに、 frontend-token-definition.jsonという名前で指定します。

トークンカテゴリ

スタイルブックを構成するためのオプションを定義するトークンは、カテゴリにグループ化されます。 スタイルブックを編集しているときに、各カテゴリがドロップダウンメニューのオプションの1つとして表示されます。

ドロップダウンメニューの各オプションは、スタイルブックのトークンの1つのカテゴリに対応しています。

src/WEB-INF/にあるテーマのfrontend-token-definition.jsonファイル内のfrontendTokenCategoriesフィールド内でこれらの各カテゴリを定義します。

{
    "frontendTokenCategories": [
        {
            "frontendTokenSets": [],
            "label": "buttons",
            "name": "buttons"
        }
    ]
}

トークンのカテゴリごとに、labelnameを定義します。 label値は言語キーとして解釈され、カテゴリのドロップダウンメニューのオプションとして表示されます。

トークンセット

各カテゴリはさらにトークンセットに整理されます。 トークンセットは、スタイルブックを編集しているときに表示される折りたたみ可能なオプションのグループに対応しています。

たとえば、デフォルトの標準テーマを使用すると、 ボタンプライマリ トークンセット(ボタン カテゴリ内)には、標準のボタンの色オプションのすべてのトークンが含まれています。

ボタンプライマリトークンセットには、標準テーマにおけるメインボタンのカスタマイズ可能な色がすべて含まれています。

カテゴリのfrontendTokenSetsフィールド内に各トークンセットを定義します。

{
    "frontendTokenCategories": [
        {
            "frontendTokenSets": [
                {
                    "frontendTokens": [],
                    "label": "primary-buttons",
                    "name": "primaryButtons"
                }
            ],
            "label": "buttons",
            "name": "buttons"
        }
    ]
}

各カテゴリと同様に、トークンセットごとにlabelnameを定義します。

トークンの定義

最後に、各トークンセットのすべてのトークンには、各オプションを構成するためのプロパティが含まれています。

各トークンセットのfrontendTokensフィールド内のすべてのトークンを定義します。 トークンに使用できるすべてのプロパティのリストは次のとおりです。

defaultValue:オプションに表示されるデフォルト値。 このフィールドは、CSSで使用されるデフォルト値と一致する必要があります。

editorType:フィールドにカラーピッカーエディターを使用する場合は、このフィールドを使用します。 サポートされている値は"ColorPicker"のみです。 値が設定されていない場合は、テキスト入力が使用されます。 選択入力が必要な場合は、代わりにvalidValuesプロパティを使用してください(2つのプロパティを一緒に使用することはできません)。

mappings:トークン定義名とそれに対応するCSS変数名とのマッピング(ネストされたフィールドとしてtypevalueを含む必要があります)。 "cssVariable"typeとして使用し、valueをCSS変数名として定義します。

label:スタイルブックを編集するときにオプションに表示される言語キー。

name:トークンの名前。

type:トークンが表示するデータのタイプ。 "Integer""Float"、または"String"を使用して、これらのタイプの値を保持するテキストフィールドを表示します。 チェックボックスを表示するには、"Boolean"を使用します。

validValues:UIでユーザーが使用できるオプションを一覧表示するオプションのプロパティ。 このフィールドには、labelvalueのペアのネストされたリストが含まれている必要があります(valueは、CSSでのフィールドの値です)。 このプロパティは、editorTypeと一緒に使用することはできません。 validValuesに値を定義すると、入力タイプが自動的に選択入力になります。

トークンセット内のトークンの一覧の例を次に示します。

"frontendTokens": [
    {
        "defaultValue": "#0B5FFF",
        "editorType": "ColorPicker",
        "label": "primary",
        "mappings": [
            {
                "type": "cssVariable",
                "value": "primary"
            }
        ],
        "name": "primaryColor",
        "type": "String"
    },
    {
        "defaultValue": "sans-serif",
        "label": "font-family",
        "mappings": [
            {
                "type": "cssVariable",
                "value": "fontFamily"
            }
        ],
        "name": "fontFamily",
        "type": "String",
        "validValues": [
            {
                "label": "sans-serif",
                "value": "sans-serif"
            },
            {
                "label": "monospace",
                "value": "Courier New"
            }
        ]
    }
]

CSS変数をスタイルブックトークンに一致させる

トークンの定義を含むfrontend-token-definition.jsonファイルは、テーマモジュールフォルダのsrc/WEB-INF/フォルダになければなりません。 トークン定義で定義されたすべてのトークンは、CSSでテーマのスタイル(色、間隔、フォントなど)を表している必要があります。

トークンが表すすべてのスタイルは、CSS変数としてコーディングする必要があります。 たとえば、次のトークンの定義(フォントを設定するオプションを提供)を見てみましょう。

{
    "defaultValue": "sans-serif",
    "label": "font-family-base",
    "mappings": [
        {
            "type": "cssVariable",
            "value": "font-family-base"
        }
    ],
    "name": "fontFamilyBase",
    "type": "String"
}

このトークンは、次のようにCSSでスタイルを表すことができます。

:root {
    --font-family-base: 'sans-serif'
}

body {
    font-family: var(--font-family-base);
}

トークン定義のmappingsfont-family-base)の値は、CSSの変数名と一致します。 CSS変数名の前に2つのハイフンを使用します(この例では、--font-family-base)。

重要

defaultValueの値がトークン定義に含まれている場合、これは一致するCSS変数定義で定義されているデフォルト値と一致する必要があります。

追加情報