アプリのリソースの概要

リソースとは、コードが使用する追加のファイルと静的コンテンツであり、ビットマップ、ユーザー インターフェース文字列、アニメーション命令などがあります。

画像や文字列などのアプリリソースは必ずコードとは別にします。それにより、コードとは独立して管理できるようになります。また、代替リソースは、異なる名前を付けたリソース ディレクトリに分類してデバイス構成ごとに指定します。実行時に、Android は現在の構成に基づいて適切なリソースを使用します。たとえば、言語設定ごとに異なる文字列を指定できます。

アプリリソースをコードとは別にした場合、そのリソースにアクセスするには、プロジェクトの R クラスで生成されたリソース ID を使用します。このドキュメントでは、Android プロジェクトでのリソースの分類方法と、デバイス構成ごとの代替リソースの指定方法、またそれらのリソースにアプリコードやその他の XML ファイルからアクセスする方法について説明します。

グループ リソースのタイプ

リソースはタイプごとにプロジェクトの res/ ディレクトリの対応するサブディレクトリに保存します。たとえば、単純なプロジェクトのファイル階層の例を次に示します。

MyProject/
    src/
        MyActivity.kt
    res/
        drawable/
            graphic.png
        mipmap/
            icon.png
        values/
            strings.xml

res/ ディレクトリのサブディレクトリにすべてのリソース（画像リソース、ランチャー アイコン用の mipmap/ ディレクトリ、文字列リソース ファイル）が保存されています。リソース ディレクトリ名は重要です。これについては表 1 で説明しています。

注: mipmap フォルダの使用方法については、アプリアイコンを mipmap ディレクトリに配置するをご覧ください。

表 1. プロジェクトの res/ ディレクトリ内でサポートされるリソース ディレクトリ

注意: リソース ファイルを res/ ディレクトリの中に直接保存しないでください。コンパイラ エラーが発生します。

表 1 で定義したサブディレクトリに保存するリソースは、デフォルトのリソースです。つまり、このリソースではアプリのデフォルトのデザインとコンテンツを定義します。しかし、Android 搭載デバイスの種類が異なれば、要求されるリソースタイプも異なる可能性があります。

たとえば、デバイスの言語設定に基づいて、ユーザー インターフェースのテキストを翻訳するさまざまな文字列リソースを使用できます。

注: Compose では、UI、アニメーション、状態駆動型の色が Kotlin で宣言されるため、layout/、menu/、anim/、animator/、color/ ディレクトリは最新のアプリでは廃止されています。詳細については、Compose のアニメーションと Compose のテーマの構造をご覧ください。

代替リソースの指定

ほとんどのアプリで、デバイスの構成ごとに代替リソースを用意する必要があります。たとえば、各種の画面密度に対応した代替のドローアブル リソースや、各種の言語に対応した代替の文字列リソースを追加します。実行時に、Android によって現在のデバイス構成が自動的に検出され、アプリに適したリソースが読み込まれます。

リソースセットに対応した構成固有の代替リソースを指定する手順は次のとおりです。

1. res/ の中に、<resources_name>-<qualifier> という形式の名前で新しいディレクトリを作成します。
   • <resources_name> は、対応するデフォルトのリソースのディレクトリ名です（表 1 で定義）。
   • <qualifier> は、そのリソースが使用される個々の構成を指定する名前です（表 2 で定義）。

   <qualifier> は複数追加できます。それらはダッシュ記号でつなぎます。

   注意: 複数の修飾子を追加する場合は、それらを表 2 の記載と同じ順序で配置する必要があります。修飾子の順序が間違っている場合、そのリソースは無視されます。

2. この新しいディレクトリに適切な代替リソースを保存します。リソース ファイルにはデフォルトのリソース ファイルと同じ名前を付ける必要があります。

デフォルトのリソースと代替リソースの例を次に示します。

res/
    drawable/
        icon.png
        background.png
    drawable-hdpi/
        icon.png
        background.png

hdpi 修飾子は、そのディレクトリにあるリソースが高密度画面を備えたデバイス用であることを示します。これらの drawable ディレクトリにある画像のサイズは画面密度ごとに調整されていますが、ファイル名は同じです。このように、icon.png や background.png の画像を参照する際に使用するリソース ID は常に同じです。Android では、デバイス構成情報をリソース ディレクトリ名の修飾子と比較することで、現在のデバイスに最も適したバージョンのリソースをそれぞれ選択します。

注意: 代替リソースを定義する場合は、必ずデフォルト構成でもリソースを定義してください。そうしないと、デバイスで構成が変更された場合にアプリでランタイム例外が発生する可能性があります。たとえば、文字列を values-en だけに追加して values には追加しないと、ユーザーがデフォルトのシステム言語を変更したときに、アプリで Resource Not Found 例外が発生することがあります。

表 2 では、構成修飾子の一覧を優先度の高い順に示します。複数の修飾子をダッシュ記号でつなぐことで 1 つのディレクトリ名に追加できます。リソース ディレクトリで複数の修飾子を使用する場合は、それらを表に記載されている順序でディレクトリ名に追加する必要があります。

表 2. 構成修飾子の名前。

注: Android のすべてのバージョンですべての修飾子がサポートされているわけではありません。新しい修飾子を使用すると、プラットフォーム バージョンの修飾子が暗黙的に追加され、古いバージョンのデバイスで無視できるようになっています。問題を避けるため、必ず、デフォルトのリソースセット（修飾子を付けないリソースのセット）を用意してください。詳しくは、リソースに関するデバイスの互換性を最適に保つをご覧ください。

Compose アプリでは、レイアウトとディメンションに関連する構成修飾子は必要ありません。これらのデバイスは、引き続き存在しますが、表 2 から除外されます。これらの修飾子には、レイアウトの方向、最小幅、利用可能な幅、利用可能な高さ、画面サイズ、画面のアスペクト比、丸い画面、画面の向きなどがあります。優先順位順に並べた構成修飾子の完全な表については、アプリリソースの概要（ビュー）をご覧ください。

修飾子の命名規則

構成修飾子の名前を使用する場合の規則は次のとおりです。

• 複数の修飾子をダッシュ記号でつないで 1 つのリソースセットとして指定できます。たとえば drawable-en-rUS-night は、言語が英語（米国）で夜間モードのデバイスに適用されます。
• 修飾子は表 2 に記載されている順序で指定する必要があります。
  • 不適切: drawable-hdpi-night/
  • 適切: drawable-night-hdpi/
• 代替リソース ディレクトリはネストできません。たとえば、res/drawable/drawable-en/ のようにはできません。
• 値は大文字と小文字が区別されません。大文字と小文字が区別されないファイル システムで問題が生じるのを避けるため、リソース コンパイラでは処理の前にディレクトリ名が小文字に変換されます。大文字を使用するのは単に名前を読みやすくする場合だけです。
• 修飾子の種類ごとに 1 つの値だけを指定できます。たとえば、スペインとフランスで同じドローアブル ファイルを使用する場合、drawable-es-fr/ というディレクトリは作成できません。その場合は、drawable-es/ と drawable-fr/ というように、それぞれのファイルを保存する 2 つのリソース ディレクトリが必要になります。

この修飾子で名前を付けたディレクトリに代替リソースを保存すると、現在のデバイス構成に基づいてアプリのリソースが自動的に適用されます。リソースが必要になるたびに、必要なリソース ファイルが保存されている代替リソース ディレクトリが調べられ、最適なリソースが見つけられます。

デバイス構成に一致する代替リソースがない場合は、対応するデフォルトのリソースが使用されます。デフォルトのリソースとは、特別なリソースタイプに用意された、構成修飾子が付かないリソースセットです。

エイリアス リソースの作成

あるリソースを複数のデバイス構成で使用したいが、デフォルトのリソースにはしたくない場合、その同じリソースを複数の代替リソース ディレクトリに保存する必要はありません。代わりに、デフォルトのリソース ディレクトリに保存したリソースのエイリアスとして機能する代替リソースを作成できます。

ドローアブル

たとえば、icon.png というアプリアイコンがあり、ロケールごとに固有のバージョンが必要だとします。しかし、English-Canadian と French-Canadian の 2 つのロケールについては同じバージョンを使用する必要があるとします。この場合、English-Canadian 用と French-Canadian 用の両方のリソース ディレクトリに同じ画像をコピーする必要はありません。代わりに、両方に使用する画像を icon.png 以外の任意の名前（icon_ca.png など）で保存し、デフォルトの res/drawable/ ディレクトリに置くことができます。次に、res/drawable-en-rCA/ と res/drawable-fr-rCA/ に、<bitmap> 要素を使用して icon_ca.png リソースを参照する icon.xml ファイルを作成します。

<?xml version="1.0" encoding="utf-8"?>
<bitmap xmlns:android="http://schemas.android.com/apk/res/android" android:src="@drawable/icon_ca" />

こうすることで、PNG ファイルの 1 つのバージョンと、それを参照する 2 つの小さな XML ファイルを保存するだけで済みます。その後、painterResource(R.drawable.icon) を使用すると、言語 / 地域が検出されたときに適切なファイルが選択されます。

文字列やその他の単純な値

既存の文字列のエイリアスを作成するには、必要な文字列のリソース ID を新しい文字列の値として使用します。

<?xml version="1.0" encoding="utf-8"?>
<resources>
    <string name="hello">Hello</string>
    <string name="hi">@string/hello</string>
</resources>

これで、R.string.hi リソースは R.string.hello のエイリアスになります。

色など、他の単純な値についても同様です。

<?xml version="1.0" encoding="utf-8"?>
<resources>
    <color name="red">#f00</color>
    <color name="highlight">@color/red</color>
</resources>

アプリのリソースにアクセスする

アプリでリソースを指定したら、そのリソース ID を参照して適用できます。すべてのリソース ID は、aapt ツールによって自動的に生成される、プロジェクトの R クラスで定義されます。

アプリがコンパイルされると、aapt が R クラスを生成します。このクラスには、res/ ディレクトリ内のすべてのリソースのリソース ID が含まれています。リソースのタイプごとに R サブクラスがあります。たとえば、R.drawable はすべてのドローアブル リソースに対応します。また、そのタイプのリソースごとに静的整数があります（たとえば R.drawable.icon）。この整数は、リソースの取得に使用できるリソース ID です。

R クラスはリソース ID を指定するために使用されますが、リソース ID を検出するためにこれを確認する必要はありません。リソース ID は常に次の要素で構成されます。

• リソースタイプ: 各リソースは string や drawable などの「タイプ」に分類されます。
• リソース名。拡張子を除いたファイル名です。

Compose でリソースにアクセスする

Jetpack Compose には、リソースに安全にアクセスするためのコンポーザブル対応の組み込み関数が用意されています。

• 文字列:

  stringResource(id = R.string.hello)

• Drawables:

  painterResource(id = R.drawable.my_icon)

UI 以外のコードでリソースにアクセスする

ViewModel、Repository、システム Service など、UI 階層外のリソースにアクセスする必要がある場合は、Context を使用して解決できます。

// Retrieve a localized string resource
val greeting = context.getString(R.string.hello_world)

Resources のメソッドを使用して個々のリソースを取得することもできます。このインスタンスは getResources メソッドで取得できます。

構文

コード内でリソースを参照する構文は次のとおりです。

[<package_name>.]R.<resource_type>.<resource_name>

• <package_name> は、リソースがあるパッケージの名前です（独自のパッケージからリソースを参照する場合は必要ありません）。
• <resource_type> はリソースタイプの R サブクラスです。
• <resource_name> は、拡張子のないリソース ファイル名、または XML 要素の android:name 属性値（単純な値の場合）です。

各リソースタイプの詳細と参照方法については、Compose のリソースをご覧ください。

元のファイルにアクセスする

場合によっては、元のファイルとディレクトリへのアクセスが必要になることがあります。その場合、res/ からリソースを読み取るにはリソース ID を使用するしかないため、res/ にファイルを保存するのは適切ではありません。代わりに、assets/ ディレクトリにリソースを保存します。

assets/ ディレクトリに保存されているファイルにはリソース ID が割り当てられないため、R クラスや XML リソースから参照することはできません。代わりに、通常のファイル システムと同様に assets/ ディレクトリ内のファイルをクエリし、AssetManager を使用して元データを読み取ることができます。

ただし、元データ（動画や音声ファイルなど）を読み取るだけでよい場合は、res/raw/ ディレクトリにファイルを保存し、openRawResource を使用してバイト ストリームとして読み取ります。

プラットフォーム リソースにアクセスする

Android には、システム スタイルやテーマなど、さまざまな標準リソースが含まれています。これらにアクセスするには、リソース参照を android パッケージ クラスで修飾します。（例: painterResource(android.R.drawable.ic_menu_info_details)）。

リソースに関するデバイスの互換性を最適に保つ

アプリで複数のデバイス構成をサポートするには、アプリが使用するリソースのタイプごとにデフォルトのリソースを準備しておくことが重要です。

たとえば、アプリで複数の言語をサポートする場合は、必ず、言語と地域の修飾子を付けない values/ ディレクトリを用意しておきます（このディレクトリに文字列を保存します）。このようにせず、言語と地域の修飾子を付けたディレクトリにすべての文字列ファイルを保存した場合、文字列が対応していない言語に設定されたデバイス上でアプリが実行されたとき、アプリはクラッシュします。

デフォルトの values/ リソースを用意しておけば、ユーザーがその言語を理解しないとしても、アプリは適切に実行されます。クラッシュするよりはるかによいでしょう。

デフォルトのリソースを準備しておくことが重要なのは、アプリが予期しない構成で実行される場合があるだけでなく、Android の新しいバージョンには、古いバージョンでサポートしていない構成修飾子が追加されることがあるためです。新しいリソース修飾子を使用し、古いバージョンの Android とのコード互換性も保つ場合、デフォルトのリソースを用意しておかないと、古いバージョンの Android でアプリが実行されたとき、アプリは新しい修飾子が名前に付いたリソースを使用できないため、クラッシュします。

たとえば、minSdkVersion を 4 に設定し、夜間モード（API レベル 8 で追加された night または notnight）を使用してすべてのドローアブル リソースを修飾するとします。その場合、API レベル 4 のデバイスはドローアブル リソースにアクセスできず、クラッシュします。これに対処するには、notnight をデフォルトのリソースにして、問題の修飾子は使用せず、ドローアブル リソースを drawable/ と drawable-night/ に用意します。

簡単に言えば、デバイスの互換性を適切に保つには、アプリを正しく実行するために必要なリソースについて、必ずデフォルトのリソースを用意しておきます。そのうえで、構成修飾子を使って個々のデバイス構成用に代替リソースを作成します。

このルールには 1 つだけ例外があります。アプリの minSdkVersion が 4 以上で、画面密度の修飾子を付けた代替ドローアブル リソースを用意した場合は、デフォルトのドローアブル リソースは必要ありません。デフォルトのドローアブル リソースがなくても、Android は代替の画面密度から最適な密度を見つけて、必要に応じてビットマップを拡大縮小できます。ただし、すべての種類のデバイスで最良のエクスペリエンスを提供するには、3 種類の密度のすべてについて代替のドローアブル リソースを用意してください。

Android が最適なリソースを見つける仕組み

Android では、代替リソースが提供されているリソースがシステムで必要になると、現在のデバイス構成に応じて、どの代替リソースを使用するのかが実行時に選択されます。Android による代替リソースの選択の仕組みを理解するため、次の各ドローアブル ディレクトリに、同じ画像の異なるバージョンが保存されている場合を考えてみましょう。

drawable/
drawable-en/
drawable-fr-rCA/
drawable-en-night/
drawable-en-notouch-12key/
drawable-night-ldpi/
drawable-night-notouch-12key/

デバイス構成は次のようになっているとします。

ロケール = en-GB
夜間モード = night
画面のピクセル密度 = hdpi
タッチスクリーンのタイプ = notouch
メインのテキスト入力方法 = 12key

Android によってデバイス構成と使用可能な代替リソースとが比較され、drawable-en-night のドローアブルが選択されます。

システムは次のようなロジックで、使用するリソースを決定します。

図 2. Android が最適なリソースをどのように見つけるかを示すフローチャート

1. デバイス構成と一致しないリソース ファイルが除外されます。

   drawable-fr-rCA/ ディレクトリは、en-GB ロケールと矛盾するため除外されます。

   drawable/
   drawable-en/
   drawable-fr-rCA/
   drawable-en-night/
   drawable-en-notouch-12key/
   drawable-night-ldpi/
   drawable-night-notouch-12key/
   

   例外: 画面のピクセル密度を表す修飾子は、不一致が原因で除外されることはありません。デバイスの画面密度は hdpi ですが、この時点ではすべての画面密度が一致しているものと見なされるので、drawable-night-ldpi/ は除外されません。詳しくは、画面の互換性の概要をご覧ください。

2. 一覧（表 2）で、次に優先度の高い修飾子を見つけます。（MCC から始めます）
3. この修飾子が含まれているリソース ディレクトリがあるかどうかが調べられます。
   • ない場合は、ステップ 2 に戻って次の修飾子を調べます。（この例では、言語修飾子に達するまで答えは「ない」です）。
   • ある場合は、ステップ 4 に進みます。
4. この修飾子が含まれていないリソース ディレクトリが除外されます。この例では、次に、言語修飾子が含まれていないディレクトリがすべて除外されます。

   drawable/
   drawable-en/
   drawable-en-night/
   drawable-en-notouch-12key/
   drawable-night-ldpi/
   drawable-night-notouch-12key/
   

   例外: 対象の修飾子が画面のピクセル密度の場合、Android はデバイスの画面密度に最も近い設定を選択します。通常は、小さい方の元画像を拡大するよりも、大きい方の元画像を縮小する方が優先されます。詳しくは、画面の互換性の概要をご覧ください。

5. ただ 1 つのディレクトリが残るまでステップ 2、3、4 を繰り返します。この例では、比較の対象となる次の修飾子はナイトモードです。そのため、夜間モードが指定されていないリソースは除外されます。

   drawable-en/
   drawable-en-night/
   drawable-en-notouch-12key/
   

   残りのディレクトリは drawable-en-night です。

上記の手順は必要なリソースごとに実行されますが、一部の処理はシステムによって最適化されます。たとえば、デバイス構成が判明した時点で、まったく一致しない代替リソースが除外される場合があります。たとえば、構成の言語が英語の場合には、英語以外に設定された言語修飾子を持つリソース ディレクトリはすべて、チェック対象のリソースプールから除外されます（ただし、言語修飾子を「持たない」リソース ディレクトリはまだ残されます）。

画面サイズの修飾子に基づいてリソースを選択する場合、最適なリソースがない場合は、現在の画面よりも小さい画面向けに設計されたリソースが使用されます。たとえば、「large」サイズの画面では、必要に応じて「normal」サイズの画面のリソースを使用します。

ただし、使用できるリソースがそのときの画面よりも大きい画面のものしかない場合、システムはその大きい画面向けのリソースを使用せず、他にデバイスの構成に一致するリソースがなければアプリはクラッシュしてしまいます。このような状況は、たとえば、レイアウト リソースすべてに修飾子 xlarge が付いているが、デバイスの画面サイズは「normal」である場合に起こります。

注: デバイスと正確に一致する修飾子がいくつあるのかよりも、表 2 に示す修飾子の優先度の方が重要視されます。上記の例のステップ 4 で、一覧の最後の選択肢にはデバイスと正確に一致する修飾子が 3 つ含まれていますが（ナイトモード、タッチスクリーンのタイプ、入力方法）、drawable-en には一致する 1 つのパラメータ（言語）しかありません。しかし、言語の方が他の修飾子よりも優先度が高いので、drawable-night-notouch-12key は除外されます。

参考情報

アプリ リソースの詳細については、以下のリソースをご覧ください。

ドキュメント

• Compose のリソース

コンテンツの閲覧

• アプリ リソースの概要（ビュー）