フロントエンドトークンの定義
Liferay DXP/ポータル 7.3 以上
スタイル ブックの視覚的なルールは、カテゴリにグループ化されたオプションで構成されます。 たとえば、「ボタン」カテゴリには、「背景色」というオプションがあります。
スタイルブック 内の各オプションはトークンで定義されます。 テーマに定義されたすべてのトークンのコレクションは、 フロントエンド トークン定義です。 フロントエンド トークンの定義は、テーマ CSS クライアント拡張機能によって提供される JSON ファイル、または以前のリリースのテーマ経由で提供される JSON ファイルです。
Liferay DXP 2024.Q2/Portal GA120 以降では、 テーマCSSクライアント拡張 でフロントエンドトークン定義を提供して、 サイトのすべてのページに適用することができます。 以前のリリースではテーマ モジュールが必要でした。
スタイルブックのトークン定義
フロントエンド トークンの定義はテーマ CSS クライアント拡張機能 (またはテーマ) に関連付けられているため、各フロントエンド トークンは提供された CSS の CSS 変数に対応している必要があります。 frontend-token-definition.json ファイルでフロントエンドトークンを指定します。
-
テーマ CSS クライアント拡張: フロントエンド トークン定義をクライアント拡張プロジェクトに配置し、
client-extension.yamlでパスを定義します。 例えば、frontendTokenDefinitionJSON: src/frontend-token-definition.json -
テーマ: フロントエンド トークン定義ファイルをテーマ モジュールの
src/WEB-INF/フォルダーに配置し、名前をfrontend-token-definition.jsonにします。
フロントエンドトークンのカテゴリー
スタイル ブックを構成するためのオプションを定義するフロントエンド トークンは、カテゴリにグループ化されています。 スタイル ブックを編集するときに、各カテゴリがドロップダウン メニューに表示されます。
テーマのsrc/WEB-INF/frontend-token-definition.jsonファイルに、frontendTokenCategoriesフィールドを使用して、これらの各カテゴリを定義します：
{
"frontendTokenCategories": [
{
"frontendTokenSets": [],
"label": "buttons",
"name": "buttons"
}
]
}
フロントエンド トークン カテゴリごとに、 ラベル と 名前 を定義します。 label値は言語キーとして解釈され、カテゴリのドロップダウンメニューのオプションとして表示されます。
フロントエンドトークンセット
各カテゴリはさらに フロントエンド トークン セット に分類され、スタイル ブックの編集時に表示される折りたたみ可能なオプション グループに対応します。
たとえば、デフォルトのクラシック テーマを使用すると、Button Primary フロントエンド トークン セット (Buttons カテゴリ内) には、標準のボタンの色オプションのすべてのフロントエンド トークンが含まれます。
カテゴリの frontendTokenSets フィールド内に各フロントエンド トークン セットを定義します。
{
"frontendTokenCategories": [
{
"frontendTokenSets": [
{
"frontendTokens": [],
"label": "primary-buttons",
"name": "primaryButtons"
}
],
"label": "buttons",
"name": "buttons"
}
]
}
各カテゴリと同様に、各フロントエンド トークン セットに対して ラベル と 名前 を定義します。
フロントエンドトークンの定義
各トークン セットの frontendTokens フィールド内でフロントエンド トークンを定義します。 フロントエンド トークンに使用できるすべてのプロパティのリストは次のとおりです。
| プロパティ | Description |
|---|---|
defaultValue | オプションに表示されるデフォルト値。 このフィールドは、CSSで使用されるデフォルト値と一致する必要があります。 |
editorType | フィールドにカラーピッカー エディターを使用する場合は、このフィールドを使用します。 サポートされている値は ColorPickerのみです。 値が設定されていない場合は、テキスト入力が使用されます。 選択入力が必要な場合は、代わりに validValues プロパティを使用します (これら 2 つのプロパティは一緒に使用できません)。 |
mappings | フロントエンド トークン定義名と対応する CSS 変数名間のマッピング (ネストされたフィールドとして タイプ と 値 を含める必要があります)。 cssVariable を 型 として使用し、 値 を CSS 変数名として定義します。 |
label | スタイル ブックを編集するときにオプションに表示される言語キー。 |
name | フロントエンドトークンの名前。 |
type | フロントエンド トークンが表示するデータの種類。 整数、 浮動小数点数、または 文字列 を使用して、これらのタイプの値を保持するテキスト フィールドを表示します。 チェックボックスを表示するには、 ブール値 を使用します。 カスタマイズ可能な測定単位（ピクセル、em、パーセンテージなど）を指定するには、 長さ を使用します。 |
validValues | UI でユーザーが利用できるオプションを一覧表示するオプションのプロパティ。 このフィールドには、labelとvalueのペアのネストされたリストが含まれている必要があります（valueは、CSSでのフィールドの値です）。 このプロパティは、editorTypeと一緒に使用することはできません。 validValuesに値を定義すると、入力タイプが自動的に選択入力になります。 |
フロントエンド トークン定義の JSON スキーマは、 Liferay のリポジトリで公開されています。
以下は、フロントエンド トークン セット内のフロントエンド トークンのリストの例です。
"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変数をスタイルブックトークンに一致させる
フロントエンド トークン定義で定義されたすべてのフロントエンド トークンは、テーマ CSS クライアント拡張機能またはテーマの CSS 内のスタイル (色、間隔、フォントなど) を表す必要があります。
フロントエンド トークンが表すスタイルは、CSS 変数としてコード化されます。 フロントエンド トークン定義が適用されている任意のページで、対応する CSS 変数を参照できます。
たとえば、次のトークンはフォントを構成するオプションを提供します。
{
"defaultValue": "sans-serif",
"label": "font-family-base",
"mappings": [
{
"type": "cssVariable",
"value": "font-family-base"
}
],
"name": "fontFamilyBase",
"type": "String"
}
このトークンには CSS 内でアクセスでき、CSS 変数として参照できます ( var(--token-name) 構文を使用)。
body {
font-family: var(--font-family-base);
}
フロントエンド トークン定義の マッピング (font-family-base) の値は、CSS の変数名と一致します。 CSS変数名の前に2つのハイフンを使用します（この例では、--font-family-base）。