このページは Cloud Translation API によって翻訳されました。

コンポーネントを既存のコードにマッピングする

デベロッパーは、生成されたコードの代わりに、UI パッケージと既存のコードコンポーネント間のマッピングを提供することで、コード生成プロセスをカスタマイズできます。これは、アニメーションや複雑な動作（プルダウンメニューなど）など、生成されたコードでは実現できない機能が既存の実装にある場合に便利です。

デベロッパーは、マッピングファイルを使用してコンポーネントをマッピングする方法を指定します。マッピングファイルは、少なくとも、適切なクライアントコードを作成できるように、ターゲットのコンポーズ可能な関数にアクセスする方法をコード生成ツールに指示します。

マッピングされたコンポーネントの概要図

次に例を示します。

Figma でデザイナーは、Play Bar コンポーネントのインスタンスを含む Card コンポーネントを作成し、両方のコンポーネントをパッケージ化して、デベロッパーに送信します。

デベロッパーが Figma から UI パッケージをインポートすると、ui-packages に card と play_bar の 2 つのディレクトリが作成されます。プロジェクトをビルドすると、Card と PlayBar の 2 つのコンポーズ可能な関数が作成されます。通常 Figma では、Card に Play Bar インスタンスが含まれているため、コードでは、コンポーズ可能な関数 Card に PlayBar コンポーザブルの呼び出しが含まれています。

しかし、デザイナーとデベロッパーは、Card で、Figma では説明しにくい機能を持つ既存のコンポーザブル MyExistingPlaybar を使用する必要があります。そのため、デベロッパーは play_bar UI パッケージを MyExistingPlaybar にマッピングする play_bar.json というマッピングファイルを追加します。

{
    "target": "MyExistingPlaybar",
    "package": "com.example.myApp"
}

これで、デベロッパーがプロジェクトをビルドすると、Card が PlayBar ではなく MyExistingPlaybar を呼び出すようになりました。MyExistingPlaybar のパラメータは PlayBar と同じにする必要があります（ただし、以下の追加のディレクティブで説明しているように、いくつかの違いがあります）。

マッピングファイル

Android Studio プロジェクトでは、ui-package-resources/mappings の下にある ui-packages フォルダの横にマッピングファイルが追加されます。Relay はビルド中にマッピングファイルを探します。

プロジェクトビューのマッピングファイル

マッピングファイルを生成する

Relay では、インポートした UI パッケージのマッピングファイルを生成できます。手順は次のとおりです。

パッケージフォルダまたは対象の ui-package フォルダ内のファイルを右クリックします。[マッピングファイルを生成] を選択します。
ダイアログで次のオプションを構成します。
- File location: 生成されるマッピングファイルの場所を設定します。
- ターゲットコンポーザブル: 生成されたコンポーザブルの代わりに使用されるカスタムコンポーザブルを設定します。既存のコンポーザブルを使用するか、ダイアログで新しいコンポーザブルを作成するかを選択できます。新しいコンポーザブルを作成すると、UI パッケージで定義されているものと同じパラメータを持つコンポーザブルが作成されます。
注: ターゲットコンポーザブルの先頭は大文字にする必要があります。
- 生成されたファイル: マッピングファイルの generateImplementation オプションと generatePreview オプションを設定します。詳しくは、以下のマッピングファイルの内容をご覧ください。
[マッピングファイルを生成] をクリックします。指定した構成で新しいマッピングファイルが ui-package-resources/mapping フォルダ内に作成されます。

次の手順で、Relay パッケージモジュール UI から [Generate mapping file] ダイアログを開くこともできます。

ターゲットの ui-package フォルダ内にある UI パッケージのファイルをクリックします。
[Relay] ツールウィンドウが自動的に開かない場合は、[Relay] アイコンをクリックしてウィンドウを開きます。
[Package Options] で [Generate mapping file] ボタンをクリックします。

注: 選択した UI パッケージのマッピングファイルが存在する場合は、そのファイルを開くためのリンクが表示されます。

マッピングファイル名

特定のマッピングファイルの名前は、置き換えるコンポーネントの UI パッケージフォルダの名前と一致する必要があります。そのため、play_bar.json は ui-packages/mappings フォルダの UI パッケージを既存のコードコンポーネントにマッピングします。

マッピングファイルの内容

マッピングファイルには次のプロパティが含まれています。

target: （必須）コンポーズ可能なカスタム関数の名前。デフォルトでは、生成されたコードによって作成された関数の名前です。
```
"target" : "CustomComposableName"
```
package:（必須）カスタムコンポーザブルが配置されているパッケージの名前。デフォルトでは、生成されたコードによって作成された関数のパッケージです。
```
"package" : "com.example.podcastapp.ui.components"
```
generateImplementation: （省略可）true または false。true の場合、この UI パッケージの実装は、生成されたコードファイルに引き続き作成されます。false の場合、実装は作成されません。デフォルトは true です。
```
"generateImplementation" : true
```
generatePreviews: （省略可）true または false。true の場合、マッピングされたカスタムコンポーネントのプレビューが、生成されたコードファイルに作成されます。false の場合、プレビューは作成されません。デフォルトは true です。
```
"generatePreviews" : true
```

マッピングされたバリアント

Figma コンポーネントにバリアントがある場合、生成されるコンポーザブルには、バリアントをエンコードする列挙型パラメータが含まれます（デザインバリアントの処理のチュートリアルを参照）。バリアントを含む Figma コンポーネントを既存のコードにマッピングする場合は、生成されたコンポーザブルと同じパラメータを受け取るコンポーザブルにマッピングする必要があります。たとえば、プロパティが ChipType のバリアントを持つ Chip という Figma コンポーネントの場合、Chip が生成するコンポーザブル署名は次のようになります。

@Composable
fun Chip(
    modifier: Modifier = Modifier,
    chipType: ChipType = ChipType.Red,
    chipText: String
) { ... }

Chip Figma コンポーネントを既存の MyChip コンポーザブルにマッピングする場合、MyChip の署名は、生成されたコンポーザブルと同じ署名である必要があります（追加のディレクティブが指定されていない場合）。概念的には、これは既存のコードコンポーネントが Figma コンポーネントと同じデザインバリアントに対応できることを示しています。

その他のディレクティブ

たとえば、ターゲットとするコンポーズ可能な関数に次のシグネチャがあるとします。

@Composable
fun MyChip(
    modifier: Modifier = Modifier,
    chipType: ChipType = ChipType.Red,
    description: String  // instead of chipText
) { ... }

パラメータのマッピング方法に影響を与える fieldMappings ブロックをマッピングファイルに追加できます。この場合、Chip の chipText パラメータから MyChip の description パラメータへのマッピングが含まれています。

{
    "target": "MyChip",
    "package": "com.example.myApp",
    "fieldMappings": [
        {
            "type": "parameter",
            "source": "chipText",
            "target": "description"
        }
    ]
}

fieldMappings ブロックのタイプは次のとおりです。

parameter: UI パッケージフィールドをコードパラメータにマッピングします。
- source: UI パッケージで指定されたパラメータの名前。
- target: ターゲットコードコンポーネントで指定されたパラメータの名前。
lambda: UI Package フィールドをコンテンツラムダにマッピングします。
- source: UI パッケージで指定されたパラメータの名前。
- target: ターゲットコードコンポーネントで指定されたパラメータの名前。
modifier: UI パッケージフィールドを修飾子メソッドにマッピングします。

注: このマッピングタイプは現在開発中です（特にレシーバースコープの処理）。
- source: UI パッケージで指定されたパラメータの名前。
- method: 生成されたコードで呼び出す必要がある Modifier オブジェクトのメソッド。
- parameter: 指定された Modifier メソッド内のパラメータの名前。
- library: Modifier メソッドにアクセスするためにインポートする修飾パッケージ名。
- scope: Modifier の範囲を示す 2 つの値のいずれか。
- any: 修飾子は、任意のレシーバスコープで使用できます。
- relay: 修飾子は、Relay の RelayContainer オブジェクトのレシーバスコープで使用する必要があります。

あなたへのおすすめ

注: JavaScript がオフになっている場合はリンクテキストが表示されます * アダプティブレイアウトを作成する * ネストされたパッケージインスタンス * リリース