アプリでのマルチプラットフォームリソースの使用
プロジェクトのリソースをセットアップしたら、プロジェクトをビルドして、リソースへのアクセスを提供する特別な Res クラスを生成します。 Res クラスとすべてのリソースアクセサを再生成するには、プロジェクトを再度ビルドするか、IDEでプロジェクトを再インポートします。
その後、生成されたクラスを使用して、コード内や外部ライブラリから設定されたマルチプラットフォームリソースにアクセスできるようになります。
以下のトピックについての詳細は、読み進めて確認してください。
- 生成された
Resクラスとアクセサのインポート - アクセサクラス生成のカスタマイズ: publicにする方法、パッケージの割り当て、無条件での生成など。
- 特定のリソースタイプの操作:
- 単純な画像、ラスタライズ画像、XMLベクターなどのDrawableリソース。
- Material SymbolsライブラリのベクターAndroid XMLアイコン。
- 単純な文字列、テンプレート、配列、複数形を含む文字列。
- カスタムフォントの保存と読み込み。
- Rawファイルおよびバイト配列の画像への変換。
- 文字列IDにマッピングされたリソースへのアクセス。
- マルチプラットフォームリソースをAndroidアセットとして使用。
- Web固有のリソースの処理:
- ブラウザ機能とpreload APIを使用したリソースの事前読み込み(プリロード)。
- 欠落している文字に対する自動フォントフォールバック。
- Webリソースのキャッシュ。
- 外部リソースの操作: 外部ライブラリから、 リモートファイル、およびJavaリソース。
生成されたクラスのインポート
準備したリソースを使用するには、生成されたクラスをインポートします。例:
import project.shared.generated.resources.Res
import project.shared.generated.resources.example_imageここで:
projectはプロジェクトの名前ですsharedはリソースディレクトリを配置したモジュールですResは生成されたクラスのデフォルト名ですexample_imageはcomposeResources/drawableディレクトリ内の画像ファイルの名前です(例:example_image.png)。
アクセサクラス生成のカスタマイズ
Gradle設定を使用して、ニーズに合わせて生成される Res クラスをカスタマイズできます。
build.gradle.kts ファイルの compose.resources {} ブロック内で、プロジェクトに対する Res クラスの生成方法に影響を与えるいくつかの設定を指定できます。 設定例は以下のようになります。
compose.resources {
publicResClass = false
packageOfResClass = "me.sample.library.resources"
generateResClass = auto
}publicResClassをtrueに設定すると、生成されるResクラスがpublicになります。デフォルトでは、生成されるクラスは internal です。packageOfResClassを使用すると、生成されるResクラスを特定のパッケージに割り当てることができます(コード内からのアクセスのため、また最終成果物内での分離のため)。デフォルトでは、Compose Multiplatform はクラスに{group name}.{module name}.generated.resourcesパッケージを割り当てます。generateResClassをalwaysに設定すると、プロジェクトで無条件にResクラスが生成されるようになります。これは、リソースライブラリが推移的(transitively)にしか利用できない場合に役立ちます。デフォルトでは、Compose Multiplatform はauto値を使用し、現在のプロジェクトがリソースライブラリに対して明示的なimplementationまたはapi依存関係を持っている場合にのみResクラスを生成します。
リソースの使用
画像
単純な画像、ラスタライズ画像、またはXMLベクターとしてDrawableリソースにアクセスできます。 SVG画像は、Androidを除くすべてのプラットフォームでサポートされています。
Drawableリソースに
Painter画像としてアクセスするには、painterResource()関数を使用します。kotlin@Composable fun painterResource(resource: DrawableResource): Painter {...}painterResource()関数はリソースパスを受け取り、Painter値を返します。この関数はWebを除くすべてのターゲットで同期的に動作します。Webターゲットの場合、最初の再コンポジション(recomposition)では空のPainterを返し、その後の再コンポジションで読み込まれた画像に置き換わります。painterResource()は、.png、.jpg、.bmp、.webpなどのラスタライズ画像形式にはBitmapPainterを、Android XMLベクタードローアブル形式にはVectorPainterを読み込みます。- XMLベクタードローアブルは Android と同じ形式ですが、Androidリソースへの外部参照はサポートされていません。
Drawableリソースに
ImageBitmapラスタライズ画像としてアクセスするには、imageResource()関数を使用します。kotlin@Composable fun imageResource(resource: DrawableResource): ImageBitmap {...}Drawableリソースに
ImageVectorXMLベクターとしてアクセスするには、vectorResource()関数を使用します。kotlin@Composable fun vectorResource(resource: DrawableResource): ImageVector {...}
Compose Multiplatformコードで画像にアクセスする方法の例を以下に示します。
Image(
painter = painterResource(Res.drawable.my_image),
contentDescription = null
)Canvas上への画像の描画
リソース画像を Image() コンポーザブルで表示する代わりに独自に描画したい場合は、ImageBitmap または ImageVector として読み込み、DrawScope 内で使用します。
ImageBitmapを描画するには、DrawScope.drawImage()を使用します。ImageVectorを描画するには、rememberVectorPainter()でPainterを作成し、Painter.draw()を使用します。
DrawScope 内でのオフセットとサイズはピクセル単位で指定します。
val myImageRaster = imageResource(Res.drawable.my_image_raster)
val myImageVectorPainter = rememberVectorPainter(vectorResource(Res.drawable.my_image_vector))
Canvas(modifier = Modifier.fillMaxSize()) {
// ラムダの内部では、`this` は `DrawScope` のインスタンスであり、`drawImage()` と `translate()` を提供します
drawImage(image = myImageRaster, topLeft = Offset(20f, 20f))
translate(left = 20f, top = myImageRaster.height + 40f) {
// `Painter.draw()` 関数は、`DrawScope` と `Painter` の両方をレシーバーとして使用します
with(myImageVectorPainter) {
draw(Size(200f, 200f))
}
}
}アイコン
Material SymbolsライブラリのベクターAndroid XMLアイコンを使用できます。
Google Fonts Icons ギャラリーを開き、アイコンを選択してAndroidタブに移動し、Download をクリックします。
ダウンロードしたXMLアイコンファイルを、マルチプラットフォームリソースの
drawableディレクトリに追加します。XMLアイコンファイルを開き、
android:fillColorを#000000に設定します。android:tintなど、色調整用の他のAndroid固有の属性を削除します。変更前:
xml<vector xmlns:android="http://schemas.android.com/apk/res/android" android:width="24dp" android:height="24dp" android:viewportWidth="960" android:viewportHeight="960" android:tint="?attr/colorControlNormal"> <path android:fillColor="@android:color/white" android:pathData="..."/> </vector>変更後:
xml<vector xmlns:android="http://schemas.android.com/apk/res/android" android:width="24dp" android:height="24dp" android:viewportWidth="960" android:viewportHeight="960"> <path android:fillColor="#000000" android:pathData="..."/> </vector>プロジェクトをビルドしてリソースアクセサを生成するか、Kotlin Multiplatform IDEプラグインに自動的に処理させます。
以下は、Compose Multiplatformコードでアイコンにアクセスし、colorFilter パラメータを使用して色を調整する方法の例です。
Image(
painter = painterResource(Res.drawable.ic_sample_icon),
contentDescription = "Sample icon",
modifier = Modifier.size(24.dp),
colorFilter = ColorFilter.tint(Color.Blue)
)文字列
すべての文字列リソースは composeResources/values ディレクトリ内のXMLファイルに保存します。 各ファイル内の各アイテムに対して静的アクセサが生成されます。
Kotlin Multiplatform IDEプラグインは、XMLファイル内で文字列リソース、文字列配列、複数形を直接追加するためのEmmet風の省略記法構文をサポートしています。 たとえば、strings.xml で test{Example} または s.test{Example} と入力して Tab キーを押すと、自動的に <string name="test">Example</string> に展開されます。
異なるロケール向けに文字列をローカライズする方法については、文字列のローカライズに関するガイドを参照してください。
単純な文字列
単純な文字列を保存するには、XMLに <string> 要素を追加します。
<resources>
<string name="app_name">My awesome app</string>
<string name="title">Some title</string>
</resources>文字列リソースを String として取得するには、以下のコードを使用します。
@Composable
fun stringResource(resource: StringResource): String {...}
@Composable
fun stringResource(resource: StringResource, vararg formatArgs: Any): String {...}例:
Text(stringResource(Res.string.app_name))suspend fun getString(resource: StringResource): String
suspend fun getString(resource: StringResource, vararg formatArgs: Any): String例:
coroutineScope.launch {
val appName = getString(Res.string.app_name)
}文字列リソースでは特殊記号を使用できます。
\n– 改行\t– タブ記号\uXXXX– 特定のUnicode文字
Androidの文字列の場合とは異なり、"@" や "?" などの特殊なXML文字をエスケープする必要はありません。
Kotlin MultiplatformプラグインがインストールされたIDEでは、Tab キーを押してEmmet風の略語を文字列タグに展開できます。
test→<string name="test"></string>test{Example}→<string name="test">Example</string>
文字列テンプレート
現在、引数には文字列リソースの基本的なサポートが用意されています。 テンプレートを作成する場合、文字列内に引数を配置するには %<number> 形式を使用し、単純なテキストではなく変数のプレースホルダーであることを示すために $d または $s のサフィックスを含めます。 例:
<resources>
<string name="str_template">Hello, %2$s! You have %1$d new messages.</string>
</resources>文字列テンプレートリソースを作成してインポートした後は、正しい順序でプレースホルダーの引数を渡しながら参照できます。
Text(stringResource(Res.string.str_template, 100, "User_name"))$s と $d のサフィックスに違いはなく、他のサフィックスはサポートされていません。 リソース文字列に %1$s プレースホルダーを配置し、それを使用して小数値を表示することも可能です。例:
Text(stringResource(Res.string.str_template, "User_name", 100.1f))Kotlin MultiplatformプラグインがインストールされたIDEでは、プレースホルダー用に %1$s や %2$d を手動で入力する代わりに、インラインの数値ショートカットを使用できます。 たとえば、文字列値の中で 1 または 1s と入力すると、%1$s に展開されます。 同様に、2d と入力すると %2$d に展開されます。
文字列配列
関連する文字列を配列にグループ化し、自動的に List<String> オブジェクトとしてアクセスできます。
<resources>
<string name="app_name">My awesome app</string>
<string name="title">Some title</string>
<string-array name="str_arr">
<item>item \u2605</item>
<item>item \u2318</item>
<item>item \u00BD</item>
</string-array>
</resources>対応するリストを取得するには、以下のコードを使用します。
@Composable
fun stringArrayResource(resource: StringArrayResource): List<String> {...}例:
val arr = stringArrayResource(Res.array.str_arr)
if (arr.isNotEmpty()) Text(arr[0])suspend fun getStringArray(resource: StringArrayResource): List<String>例:
coroutineScope.launch {
val appName = getStringArray(Res.array.str_arr)
}Kotlin MultiplatformプラグインがインストールされたIDEでは、Emmet風の構文を使用して文字列配列をすばやく定義できます。 空の配列テンプレートを生成するには、string-array、sa、または > 演算子を使用します。 事前定義されたアイテム数と開始テキストを持つ名前付き配列を作成するには、test>2{Hello} と入力して Tab キーを押します。
<string-array name="test">
<item>Hello</item>
<item>Hello</item>
</string-array>複数形(Plurals)
UIが何らかの数量を表示する場合、プログラム的に無関係な文字列をいくつも作成することなく、同じものの異なる数量に対して文法的な一致(1冊の book、多数の books など)をサポートしたい場合があります。
Compose Multiplatformにおける概念と基本的な実装は、Androidの数量文字列(quantity strings)と同じです。 プロジェクトで複数形を使用する際のベストプラクティスとニュアンスの詳細については、Androidのドキュメントを参照してください。
- サポートされているバリアントは
zero、one、two、few、many、およびotherです。すべての言語でこれらすべてのバリアントが考慮されるわけではないことに注意してください。たとえば、英語ではzeroは1以外の他の複数形と同じであるため無視されます。言語が実際にどのような区別を要求しているかについては、言語の専門家に確認してください。 - ユーザーエクスペリエンスを損なわないのであれば、「Books: 1」のような数量に依存しない表現を使用することで、数量文字列を回避できることもよくあります。
複数形を定義するには、composeResources/values ディレクトリ内の任意の .xml ファイルに <plurals> 要素を追加します。 plurals コレクションは、name属性(XMLファイルの名前ではありません)を使用して参照される単純なリソースです。 そのため、1つの <resources> 要素の下で、同じXMLファイル内の他の単純なリソースと plurals リソースを組み合わせることができます。
<resources>
<string name="app_name">My awesome app</string>
<string name="title">Some title</string>
<plurals name="new_message">
<item quantity="one">%1$d new message</item>
<item quantity="other">%1$d new messages</item>
</plurals>
</resources>複数形に String としてアクセスするには、以下のコードを使用します。
@Composable
fun pluralStringResource(resource: PluralStringResource, quantity: Int): String {...}
@Composable
fun pluralStringResource(resource: PluralStringResource, quantity: Int, vararg formatArgs: Any): String {...}例:
Text(pluralStringResource(Res.plurals.new_message, 1, 1))suspend fun getPluralString(resource: PluralStringResource, quantity: Int): String
suspend fun getPluralString(resource: PluralStringResource, quantity: Int, vararg formatArgs: Any): String例:
coroutineScope.launch {
val appName = getPluralString(Res.plurals.new_message, 1, 1)
}Kotlin MultiplatformプラグインがインストールされたIDEでは、Emmet風の構文を使用して複数形リソースを生成できます。 たとえば、plurals、p、または : を使用して、デフォルトの空の文字列テンプレートを生成します。 values-en/strings.xml で作業している場合、IDEはロケール、必要な数量、および英語には one と other のみが必要であることを自動的に検出します。 p.test または plurals.test と入力して Tab キーを押すと、略語が plurals ブロックに展開されます。
<plurals name="test">
<item quantity="one"></item>
<item quantity="other"></item>
</plurals>フォント
カスタムフォントは composeResources/font ディレクトリに保存します。 Compose Multiplatformは、すべてのプラットフォームでTTF、OTF、TTC、およびバリアブルフォント形式をサポートしています。 WOFFおよびWOFF2は、WebとmacOSでのみ利用可能です。
フォントを Font 型として読み込むには、Font() コンポーザブル関数を使用します。
@Composable
fun Font(
resource: FontResource,
weight: FontWeight = FontWeight.Normal,
style: FontStyle = FontStyle.Normal
): Font例:
@Composable private fun InterTypography(): Typography { val interFont = FontFamily( {...}
@Composable
private fun InterTypography(): Typography {
val interFont = FontFamily(
Font(Res.font.Inter_24pt_Regular, FontWeight.Normal),
Font(Res.font.Inter_24pt_SemiBold, FontWeight.Bold),
)
return with(MaterialTheme.typography) {
copy(
displayLarge = displayLarge.copy(fontFamily = interFont, fontWeight = FontWeight.Bold),
displayMedium = displayMedium.copy(fontFamily = interFont, fontWeight = FontWeight.Bold),
displaySmall = displaySmall.copy(fontFamily = interFont, fontWeight = FontWeight.Bold),
headlineLarge = headlineLarge.copy(fontFamily = interFont, fontWeight = FontWeight.Bold),
headlineMedium = headlineMedium.copy(fontFamily = interFont, fontWeight = FontWeight.Bold),
headlineSmall = headlineSmall.copy(fontFamily = interFont, fontWeight = FontWeight.Bold),
titleLarge = titleLarge.copy(fontFamily = interFont, fontWeight = FontWeight.Bold),
titleMedium = titleMedium.copy(fontFamily = interFont, fontWeight = FontWeight.Bold),
titleSmall = titleSmall.copy(fontFamily = interFont, fontWeight = FontWeight.Bold),
labelLarge = labelLarge.copy(fontFamily = interFont, fontWeight = FontWeight.Normal),
labelMedium = labelMedium.copy(fontFamily = interFont, fontWeight = FontWeight.Normal),
labelSmall = labelSmall.copy(fontFamily = interFont, fontWeight = FontWeight.Normal),
bodyLarge = bodyLarge.copy(fontFamily = interFont, fontWeight = FontWeight.Normal),
bodyMedium = bodyMedium.copy(fontFamily = interFont, fontWeight = FontWeight.Normal),
bodySmall = bodySmall.copy(fontFamily = interFont, fontWeight = FontWeight.Normal),
)
}
}Font がコンポーザブルである場合、それに依存するコンポーネント(TextStyle や Typography など)もコンポーザブルであることを確認してください。
絵文字やアラビア文字などの特殊文字は、要求に応じて必要なNotoフォントをダウンロードする自動フォントフォールバックを通じて、Webターゲットで自動的にサポートされます。
使用するフォントを完全に制御する必要がある場合は、特定のフォントをバンドルし、preload API を使用して手動で登録してください。
Rawファイル
任意のRaw(未加工の)ファイルをバイト配列として読み込むには、Res.readBytes(path) 関数を使用します。
suspend fun readBytes(path: String): ByteArrayRawファイルは composeResources/files ディレクトリに配置でき、その中に任意の階層を作成できます。
たとえば、Rawファイルにアクセスするには以下のコードを使用します。
var bytes by remember {
mutableStateOf(ByteArray(0))
}
LaunchedEffect(Unit) {
bytes = Res.readBytes("files/myDir/someFile.bin")
}
Text(bytes.decodeToString())coroutineScope.launch {
val bytes = Res.readBytes("files/myDir/someFile.bin")
}バイト配列から画像への変換
読み込んでいるファイルがビットマップ(JPEG、PNG、BMP、WEBP)またはXMLベクター画像である場合、以下の関数を使用して、Image() コンポーザブルに適した ImageBitmap または ImageVector オブジェクトに変換できます。
Rawファイル セクションで示したようにRawファイルにアクセスし、その結果をコンポーザブルに渡します。
// bytes = Res.readBytes("files/example.png")
Image(bytes.decodeToImageBitmap(), null)
// bytes = Res.readBytes("files/example.xml")
Image(bytes.decodeToImageVector(LocalDensity.current), null)Androidを除くすべてのプラットフォームでは、SVGファイルを Painter オブジェクトに変換することもできます。
// bytes = Res.readBytes("files/example.svg")
Image(bytes.decodeToSvgPainter(LocalDensity.current), null)リソースと文字列ID用に生成されたマップ
アクセスを容易にするため、Compose Multiplatformは文字列IDを使用してリソースをマッピングすることも行います。ファイル名をキーとして使用してアクセスできます。
val Res.allDrawableResources: Map<String, DrawableResource>
val Res.allStringResources: Map<String, StringResource>
val Res.allStringArrayResources: Map<String, StringArrayResource>
val Res.allPluralStringResources: Map<String, PluralStringResource>
val Res.allFontResources: Map<String, FontResource>マッピングされたリソースをコンポーザブルに渡す例:
Image(painterResource(Res.allDrawableResources["compose_multiplatform"]!!), null)AndroidアセットとしてのCompose Multiplatformリソース
Compose Multiplatform 1.7.0以降、すべてのマルチプラットフォームリソースはAndroidアセットにパックされます。 これにより、Android StudioでAndroidソースセット内のCompose Multiplatformコンポーザブルのプレビューを生成できるようになります。
Android Studioのプレビューは、Androidソースセット内のコンポーザブルに対してのみ利用可能です。 また、最新バージョンのAGP(8.5.2、8.6.0-rc01、または8.7.0-alpha04のいずれか)が必要です。
マルチプラットフォームリソースをAndroidアセットとして使用することで、リソースに単純なパス(例: Res.getUri("files/index.html"))でアクセスできるため、Android上のWebViewやメディアプレーヤーコンポーネントからの直接アクセスも可能になります。
リソース画像へのリンクを含むリソースHTMLページを表示するAndroidコンポーザブルの例:
AndroidView(factory = { WebView(it).apply {...}
// androidMain/kotlin/com/example/webview/App.kt
@OptIn(ExperimentalResourceApi::class)
@Composable
@Preview
fun App() {
MaterialTheme {
val uri = Res.getUri("files/webview/index.html")
// Adding a WebView inside AndroidView with layout as full screen.
AndroidView(factory = {
WebView(it).apply {
layoutParams = ViewGroup.LayoutParams(
ViewGroup.LayoutParams.MATCH_PARENT,
ViewGroup.LayoutParams.MATCH_PARENT
)
}
}, update = {
it.loadUrl(uri)
})
}
}この例は、次のシンプルなHTMLファイルで動作します。
<title>Cat Resource</title> {...}
<html>
<header>
<title>
Cat Resource
</title>
</header>
<body>
<img src="cat.jpg">
</body>
</html>この例の両方のリソースファイルは、commonMain ソースセットに配置されています。

他のライブラリやリソースとの連携
外部ライブラリからのマルチプラットフォームリソースへのアクセス
プロジェクトに含まれる他のライブラリを使用してマルチプラットフォームリソースを処理したい場合は、プラットフォーム固有のファイルパスをそれらの他のAPIに渡すことができます。 プラットフォーム固有のパスを取得するには、リソースへのプロジェクトパスを指定して Res.getUri() 関数を呼び出します。
val uri = Res.getUri("files/my_video.mp4")これで uri 変数にファイルへの絶対パスが格納されたため、外部ライブラリはそのパスを使用して、適切な方法でファイルにアクセスできます。
Android固有の用途では、マルチプラットフォームリソースはAndroidアセットとしてもパックされます。
リモートファイル
リソースライブラリのコンテキストでは、アプリケーションの一部であるファイルのみがリソースとみなされます。
URLを使用してインターネットからリモートファイルを読み込むには、専用のライブラリを使用できます。
画像を手動でダウンロードしたりそのバイトを読み込んだりした場合は、リソースライブラリのデコード関数を使用して変換します。デスクトップアプリでネットワーク画像を読み込む例については、デスクトップ向けCompose Multiplatformでの画像の使用を参照してください。
画像のバイトを自身でダウンロードまたは読み込んだ場合は、リソースライブラリのデコード関数を使用して画像に変換してください。 デスクトップアプリケーションでネットワークから画像を読み込む例については、デスクトップ向けCompose Multiplatformでの画像の使用 のチュートリアルを参照してください。
Javaリソースの使用
Compose MultiplatformでJavaリソースを使用することは可能ですが、フレームワークが提供する拡張機能(生成されたアクセサ、マルチモジュールサポート、ローカライズなど)の恩恵を受けることはできません。 その潜在的な機能を活用するために、マルチプラットフォームリソースライブラリへの完全な移行を検討してください。
Compose Multiplatform 1.7.0では、compose.ui パッケージで利用可能だったリソースAPIは非推奨(deprecated)になりました。 引き続きJavaリソースを使用する必要がある場合は、Compose Multiplatform 1.7.0以降にアップグレードした後もコードが動作するように、以下の実装をプロジェクトにコピーしてください。
internal fun painterResource(resourcePath: String): Painter {...}
@Composable
internal fun painterResource(
resourcePath: String
): Painter = when (resourcePath.substringAfterLast(".")) {
"svg" -> rememberSvgResource(resourcePath)
"xml" -> rememberVectorXmlResource(resourcePath)
else -> rememberBitmapResource(resourcePath)
}
@Composable
internal fun rememberBitmapResource(path: String): Painter {
return remember(path) { BitmapPainter(readResourceBytes(path).decodeToImageBitmap()) }
}
@Composable
internal fun rememberVectorXmlResource(path: String): Painter {
val density = LocalDensity.current
val imageVector = remember(density, path) { readResourceBytes(path).decodeToImageVector(density) }
return rememberVectorPainter(imageVector)
}
@Composable
internal fun rememberSvgResource(path: String): Painter {
val density = LocalDensity.current
return remember(density, path) { readResourceBytes(path).decodeToSvgPainter(density) }
}
private object ResourceLoader
private fun readResourceBytes(resourcePath: String) =
ResourceLoader.javaClass.classLoader.getResourceAsStream(resourcePath).readAllBytes()