リソースの提供

画像や文字列といったアプリケーション リソースは、常にコードの外部に置くようにすることで、独立して保持できるようになります。 さらに、特別に名前を設定したリソース ディレクトリにグループ化することで、特定の端末設定に代替リソースを提供する必要があります。 実行時には、現在の設定に基づいて、Android は適切なリソースを使用します。 たとえば、画面サイズに応じて異なる UI レイアウトを提供したり、言語設定に応じて異なる文字列を提供したりできます。

アプリケーション リソースを外部化すると、プロジェクトの R クラスで生成されるリソース ID を使用してそれらのリソースにアクセスできます。 アプリケーションでのリソースの使用方法については、リソースへのアクセスをご覧ください。 このドキュメントでは、Android プロジェクトでリソースをグループ化する方法と、特定の端末設定に代替リソースを提供する方法を説明します。

リソースタイプをグループ化する

それぞれのタイプのリソースを、プロジェクトの res/ ディレクトリの特定のサブディレクトリに格納する必要があります。 次は、単純なプロジェクトのファイル階層の例です。

MyProject/
    src/  
        MyActivity.java  
    res/
        drawable/  
            graphic.png  
        layout/  
            main.xml
            info.xml
        mipmap/  
            icon.png 
        values/  
            strings.xml  

この例を見てわかるように、res/ ディレクトリには、(サブディレクトリに入った)画像リソース、2 つのレイアウト リソース、ランチャー アイコンの mipmap/ ディレクトリ、文字列リソース ファイルといった、すべてのリソースが含まれます。 リソース ディレクトリ名は重要です。表 1 に説明があります。

注: Mipmap フォルダの使用方法については、プロジェクトの概要の管理をご覧ください。

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

ディレクトリ リソースタイプ
animator/プロパティ アニメーションを定義する XML ファイル。
anim/トゥイーン アニメーションを定義する XML ファイル。 (プロパティ アニメーションをこのディレクトリに保存することもできますが、2 つのタイプを区別するために、プロパティ アニメーションは animator/ ディレクトリに保存することをお勧めします)。
color/色の状態リストを定義する XML ファイル。 色状態リストのリソース をご覧ください。
drawable/

ビットマップ ファイル(.png.9.png.jpg.gif)または次のドローアブル リソース サブタイプにコンパイルされる XML ファイル:

  • ビットマップ ファイル
  • 9-patch(リサイズ可能なビットマップ)
  • 状態リスト
  • 形状
  • アニメーション ドローアブル
  • その他のドローアブル

ドローアブル リソースをご覧ください。

mipmap/さまざまなランチャー アイコン密度のドローアブル ファイル。 mipmap/ フォルダによるランチャー アイコンの管理方法については、プロジェクトの概要の管理をご覧ください。
layout/ユーザー インターフェースのレイアウトを定義する XML ファイル。 レイアウト リソースをご覧ください。
menu/オプション メニュー、コンテキスト メニュー、サブ メニューといった、アプリケーション メニューを定義する XML ファイル。 メニュー リソースをご覧ください。
raw/

未加工の形式で保存する任意のファイル。これらのリソースを未加工の InputStream で開くには、リソース ID(R.raw.filename)を指定して Resources.openRawResource() を呼び出します。

ただし、元のファイル名とファイル階層にアクセスする必要がある場合は、一部のリソースを assets/ ディレクトリ(res/raw/ の代わりに)に保存することを検討してください。 assets/ のファイルにはリソース ID が付与されていないため、読み取りには AssetManager が必要です。

values/

文字列、整数、色など、単純な値を含む XML ファイル。

その他の res/ サブディレクトリの XML リソース ファイルは XML ファイル名に基づいて 1 つのリソースを定義しますが、values/ ディレクトリのファイルは複数のリソースを表します。このディレクトリのファイルの場合、<resources> 要素の子がそれぞれ 1 つのリソースを定義します。 たとえば、<string> 要素は R.string リソースを生成し、<color> 要素は R.color リソースを生成します。

各リソースの定義には XML 要素を使用するため、ファイルには任意の名前を設定でき、1 つのファイル内にさまざまなリソースを配置できます。 ただし、わかりやすくするために、一意のリソースタイプをそれぞれのファイルに配置することもできます。 次は、このディレクトリで作成できるリソースのファイル名の変換例です。

文字列リソーススタイル リソースその他のリソース タイプをご覧ください。

xml/Resources.getXML() を呼び出すことによって、実行時に読み込むことができる任意の XML ファイル。 ここには、検索可能な設定など、各種の XML 設定ファイルが保存されます。

警告: リソース ファイルを res/ ディレクトリに直接保存しないでください。コンパイラー エラーの原因になります。

リソースの特定のタイプの詳細は、リソース タイプのドキュメントをご覧ください。

表 1 で定義したサブディレクトリに保存するリソースは、「デフォルト」のリソースとなります。 つまり、これらのリソースはアプリケーションのデフォルトのデザインとコンテンツを定義します。ただし、Android が搭載された端末では別のタイプのリソースが呼び出されることがあります。たとえば、端末の画面サイズが通常のものよりも大きな場合、追加の画面スペースを利用する別のレイアウト リソースを提供する必要があります。 また、端末の言語設定が異なる場合、使用するユーザー インターフェースのテキストを翻訳する、別の文字列リソースを提供します。 さまざまな端末設定にこれらの異なるリソースを提供するには、デフォルトのリソースに加えて、代替リソースを提供する必要があります。

代替リソースを提供する

図 1. 別のレイアウト リソースを使用する、2 つの異なる端末。

ほぼすべてのアプリケーションが、特定の端末設定をサポートするための代替リソースを提供します。 たとえば、画面密度が異なる場合は代替ドローアブル リソースを含め、言語が異ならう場合は代替文字列リソースを含めます。 実行時には、Android が現在の端末設定を検出し、アプリケーションに合ったリソースを読み込みます。

一連のリソースに設定固有の代替リソースを指定するには:

  1. res/ 配下に、<resources_name>-<config_qualifier> の形式で名前を付けた新しいディレクトリを作成します。
    • <resources_name> は、対応するデフォルト リソースのディレクトリ名です(表 1 で定義)。
    • <qualifier> は、使用するリソースの各構成を指定する名前です(表 2 で定義)。

    1 つ以上の <qualifier> を末尾に追加できます。それぞれの修飾子はダッシュを使用して区切ります。

    警告: 複数の修飾子を末尾に追加する場合は、表 2 に記載されているのと同じ順番で配置する必要があります。修飾子の順番に誤りがあると、リソースが認識されません。

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

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

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

hdpi 修飾子は、ディレクトリ内のリソースが高密度画面を持つ端末用であることを表します。 これらのドローアブル ディレクトリの画像は特定の画面密度に合わせたサイズになっていますが、ファイル名は完全に同じになります。 このように、icon.pngbackground.png 画像を参照するのに使用するリソース ID は常に同じになりますが、Android はリソース ディレクトリ名の修飾子により端末設定情報を比較して、各リソースの現在の端末に最適なバージョンを選択します。

Android では複数の設定修飾子をサポートしており、それぞれの修飾子をダッシュで区切ることで、1 つのディレクトリ名に複数の修飾子を追加できます。 表 2 には、有効な設定修飾子が優先度順に記載されています。—参照ディレクトリに複数の修飾子を使用する場合、表に記載されている順番にディレクトリ名に追加する必要があります。

表 2. 設定修飾子の名前。

設定 修飾子の値 説明
MCC と MNC例:
mcc310
mcc310-mnc004
mcc208-mnc00
など

モバイル カントリーコード(MCC)です。端末の SIM カードにあるモバイル ネットワーク コード(MNC)が続くことがあります。 たとえば、mcc310 は米国の任意の携帯通信会社、mcc310-mnc004 は米国の Verizon、mcc208-mnc00 はフランスの Orange となります。

端末が無線通信接続(GSM 電話)を使用する場合、MCC と MNC の値は SIM カードの値となります。

さらに、MCC のみを使用することもできます(たとえば、アプリケーションに国固有の法に関するリソースを含める場合)。 言語のみに基づいて指定する場合は、代わりに言語と地域の修飾子(次のセクションで解説)を使用します。 MCC と MNC 修飾子を使用する場合は、慎重に設定し、予測のとおりに機能することをテストします。

さらに、設定フィールド mccmnc もご覧ください。これらは、それぞれ、現在のモバイル カントリーコードとモバイル ネットワーク コードを表します。

言語と地域例:
en
fr
en-rUS
fr-rFR
fr-rCA
など

言語は 2 文字の ISO 639-1 言語コードで定義し、オプションで、2 文字の ISO 3166-1-alpha-2 地域コードを後ろに追加します(前に小文字の「r」を付けます)。

コードでは大文字と小文字が区別されません。地域を区別するには、r 接頭辞を使用します。 地域のみは指定できません。

ユーザーがシステム設定で言語を変更すると、アプリケーションの実行中にこの値が変更されます。 実行時のアプリケーションに与える影響については、実行時の変更の処理をご覧ください。

アプリケーションを他の言語にローカライズするための詳細なガイドは、ローカライズをご覧ください。

さらに、locale 設定フィールドもご覧ください。これは、現在のロケールを表します。

レイアウトの方向ldrtl
ldltr

アプリケーションのレイアウトの方向です。ldrtl は、「レイアウト方向は右から左」という意味になります。ldltr は、「レイアウト方向は左から右」という意味で、こちらの設定が暗黙的にデフォルト値になります。

この設定は、レイアウト、ドローアブル、値など、任意のリソースに適用できます。

たとえば、アラビア語に何らかの特定なレイアウトを提供し、その他の「右から左」の言語(ペルシャ語やヘブライ語)に汎用的なレイアウトを提供する場合、次のように設定します。

res/
    layout/   
        main.xml  (Default layout)
    layout-ar/  
        main.xml  (Specific layout for Arabic)
    layout-ldrtl/  
        main.xml  (Any "right-to-left" language, except
                  for Arabic, because the "ar" language qualifier
                  has a higher precedence.)

注: アプリで右から左のレイアウト機能を有効にするには、supportsRtl"true" に設定し、targetSdkVersion を 17 以上に設定します。

API レベル 17 で追加。

smallestWidthsw<N>dp

例:
sw320dp
sw600dp
sw720dp
など

使用可能な画面領域の最小寸法で指定する、画面の基本サイズ。 具体的には、端末の smallestWidth は画面に使用できる高さと幅の最小サイズとなります(画面の「使用できる最小幅」と考えることもできます)。 画面の現在の向きに関係なく、この修飾子を使用することで、アプリケーションの UI に少なくとも <N> dps の幅を使用できます。

たとえば、画面領域のレイアウトの最小寸法を常に 600 dp とする必要がある場合、この修飾子を使用してレイアウト リソース res/layout-sw600dp/ を作成できます。 システムは、600dp の側が縦になるか横になるか関係なく、使用可能な画面の最小寸法が 600dp 以上の場合にのみこれらのリソースを使用します。 smallestWidth は端末の固定された画面サイズ特性です。画面の向きが変わっても、端末の smallestWidth は変更されません。

端末の smallestWidth では画面の装飾とシステム UI が考慮されます。たとえば、端末の画面に smallestWidth の軸に沿ったスペースを考慮した固定 UI 要素がある場合、これらの画面ピクセルは UI に使用できないため、システムは実際の画面サイズよりも小さな smallestWidth を宣言します。 つまり、使用する値は、レイアウトが必要とする実際の最小寸法にする必要があります(通常は、この値は、画面の現在の向きに関係なく、レイアウトがサポートする「最小幅」になります)。

次に、一般的な画面サイズに使用する値を示します。

  • 320。次のような画面設定を持つ端末。
    • 240x320 ldpi(QVGA ハンドセット)
    • 320x480 mdpi(ハンドセット)
    • 480x800 hdpi(高密度ハンドセット)
  • 480。480x800 mdpi(タブレットやハンドセット)などの画面。
  • 600。600x1024 mdpi(7 インチタブレット)などの画面。
  • 720。720x1280 mdpi(10 インチタブレット)などの画面。

アプリケーションで smallestWidth 修飾子の値が異なる複数のリソース ディレクトリを提供する場合、システムは端末の smallestWidth に最も近い(かつ超過しない)ものを使用します。

API レベル 13 で追加。

さらに、android:requiresSmallestWidthDp 属性もご覧ください。これは、アプリケーションが互換性を持つ最小の smallestWidth と、端末の smallestWidth 値を保持する smallestScreenWidthDp 設定フィールドを宣言します。

さまざまな画面の設計とこの修飾子の使用方法についての詳細は、複数画面をサポートするのデベロッパー ガイドをご覧ください。

使用可能な幅w<N>dp

例:
w720dp
w1024dp
など

リソースに使用する、使用可能な最小の画面幅を dp 単位で指定します。<N> の値で定義します。 画面の向きの縦と横を変更すると、現在の実際の幅に合わせて、この設定値が変更されます。

アプリケーションでこの設定が異なる複数のリソース ディレクトリを提供する場合、システムは端末の現在の画面の幅に最も近い(かつ超過しない)ものを使用します。 この値は画面の装飾を考慮します。つまり、端末のディスプレイの左や右に何らかの固定 UI 要素がある場合、これらの UI 要素を考慮し、アプリケーションの使用可能なスペースを減らして、実際の画面サイズよりも小さな幅を使用します。

API レベル 13 で追加。

さらに、screenWidthDp 設定フィールドもご覧ください。これは現在の画面の幅を保持します。

さまざまな画面の設計とこの修飾子の使用方法についての詳細は、複数画面をサポートするのデベロッパー ガイドをご覧ください。

使用可能な高さh<N>dp

例:
h720dp
h1024dp
など

リソースを使用する、使用可能な最小の画面幅を「dp」単位で指定します。—<N> の値で定義します。 画面の向きの縦と横を変更すると、現在の実際の高さに合わせて、この設定値が変更されます。

アプリケーションでこの設定が異なる複数のリソース ディレクトリを提供する場合、システムは端末の現在の画面の高さに最も近い(かつ超過しない)ものを使用します。 この値は画面の装飾を考慮します。つまり、端末のディスプレイの上や下に何らかの固定 UI 要素がある場合、これらの UI 要素を考慮し、アプリケーションの使用可能なスペースを減らして、実際の画面サイズよりも小さな高さを使用します。 固定されていない画面の装飾(全画面にした場合に非表示になる携帯電話のステータスバーなど)や、タイトルバーやアクションバーなどのウィンドウの装飾は、ここでは考慮されません。そのため、アプリケーションでは指定したスペースよりもやや小さなサイズに対処できるように準備をし置く必要があります。

API レベル 13 で追加。

さらに、screenHeightDp 設定フィールドもご覧ください。これは現在の画面の幅を保持します。

さまざまな画面の設計とこの修飾子の使用方法についての詳細は、複数画面をサポートするのデベロッパー ガイドをご覧ください。

画面サイズsmall
normal
large
xlarge
  • small:低密度 QVGA 画面と同等のサイズを持つ画面です。 小さい画面の最小レイアウト サイズは約 320x426 dp 単位です。 たとえば、QVGA 低密度や VGA 高密度です。
  • normal:中密度 HVGA 画面と同等のサイズを持つ画面です。 通常の画面の最小レイアウト サイズは約 320x470 dp 単位です。 たとえば、WQVGA 低密度、HVGA 中密度、WVGA 高密度といった画面になります。
  • large:中密度 VGA 画面と同等のサイズを持つ画面です。 大きな画面の最小レイアウト サイズは約 480x640 dp 単位です。 たとえば、VGA や WVGA の中密度といった画面です。
  • xlarge:従来の中密度 HVGA 画面よりもはるかに大きなサイズの画面です。 特大の画面の最小レイアウト サイズは約 720x960 dp 単位です。 ほとんどの場合、特大の画面を持つ端末はポケットに入れて持ち運ぶことができないほど大きく、タブレット スタイルの端末になります。 API レベル 9 で追加。

注: サイズ識別子を持つ場合でも、リソースがそのサイズの画面以外には対応しないということではありません。 現在の端末に最適な識別子を持つ代替リソースを提供していない場合でも、システムによって最適なリソースが使用されることがあります。

警告: すべてのリソースが現在の画面よりも大きなサイズ識別子を使用している場合、システムはそれらのリソースを使用せず、アプリケーションは実行時にクラッシュしてしまいます(たとえば、すべてのリソースに xlarge 識別子のタグが付いているが、端末は通常サイズの画面である場合)。

API レベル 4 で追加。

詳細については、複数画面をサポートするをご覧ください。

さらに、screenLayout 設定フィールドもご覧ください。これは、画面のサイズが小、中、大のいずれかであるかを表します。

画面アスペクトlong
notlong
  • long:WQVGA、WVGA、FWVGA のような長い画面
  • notlong:QVGA、HVGA、VGA のように長くない画面

API レベル 4 で追加。

これは純粋に画面のアスペクト比を基準とします(「長い」画面は幅広の画面になります)。これは画面の向きには関係ありません。

さらに、screenLayout 設定フィールドもご覧ください。これは、画面のサイズが長いかどうかを表します。

円形の画面round
notround
  • round:ウェアラブル端末のような円形の画面
  • notround:スマートフォンやタブレットのような長方形の画面

API レベル 23 で追加。

さらに、isScreenRound() 設定メソッドで、画面の形状が円形かどうかを確認します。

画面の向きport
land
  • port:端末は縦向き(垂直)になっています
  • land:端末は横向き(水平)になっています

ユーザーが画面を回転すると、アプリケーションの実行中にこの値が変更されます。 実行時のアプリケーションに与える影響については、実行時の変更の処理をご覧ください。

さらに、orientation 設定フィールドもご覧ください。これは、現在の端末の画面の向きを表します。

UI モードcar
desk
television
appliance watch
  • car:端末は車載ドックで表示されています
  • desk:端末はデスクドックで表示されています
  • television:端末はテレビで表示されており、「10 フィート」離れた位置からの操作が可能です。UI はユーザーから離れた場所にある大きな画面に表示され、主に十字キーやポインタ以外のやり取りで操作します。
  • appliance:端末をアプライアンスとして使用します。ディスプレイはありません
  • watch:端末にはディスプレイがあり、手首に装着して使用します

API レベル 8 で追加。television は API 13 で追加。watch は API 20 で追加。

端末をホルダーに装着したり、取り外したりしたときのアプリの反応については、装着状態とホルダータイプを特定および監視するをご覧ください。

ユーザーが端末をドックに装着すると、アプリケーションの実行中にこの値が変更されます。 UiModeManager を使用すると、これらのモードの一部を有効または無効にできます。実行時のアプリケーションに与える影響については、実行時の変更の処理をご覧ください。

ナイトモードnight
notnight
  • night: 夜間
  • notnight: 昼間

API レベル 8 で追加。

ナイトモードを自動モード(デフォルト)のままにしておくと、時間を基準にしてモードが変更された場合に、アプリケーションの実行中にこの値が変更されます。 UiModeManager を使用すると、このモードを有効または無効にできます。 実行時のアプリケーションに与える影響については、実行時の変更の処理をご覧ください。

画面ピクセル密度(dpi)ldpi
mdpi
hdpi
xhdpi
xxhdpi
xxxhdpi
nodpi
tvdpi
anydpi
  • ldpi:低密度の画面。約 120dpi です。
  • mdpi:中密度(従来の HVGA)の画面。約 160dpi です。
  • hdpi:高密度の画面。約 240dpi です。
  • xhdpi:超高密度の画面。約 320dpi です。API レベル 8 で追加。
  • xxhdpi:超超高密度の画面。約 480dpi です。API レベル 16 で追加。
  • xxxhdpi:超超高密度が使用(ランチャー アイコンのみ。「Supporting Multiple Screens」のをご覧ください)。約 640dpi です。 API レベル 18 で追加。
  • nodpi:端末の密度に合わせてサイズを変更しないビットマップ リソースに使用します。
  • tvdpi:密度が mdpi と hdpi の間の画面。約 213dpi です。これは「プライマリ」の密度グループとしては認識されません。 ほとんどの場合、テレビ向けのものであり、大部分のアプリは必要としません。—通常、アプリの場合は mdpi と hdpi リソースを提供すれば十分であり、システムが必要に応じてサイズを変更します。 API レベル 13 で追加。
  • anydpi:この修飾子はどんな画面密度にも適しており、ほかの修飾子よりも優先されます。 これはベクター型ドローアブルの場合に便利です。API レベル 21で追加。

6 つのプライマリ密度のサイズの比率は 3:4:6:8:12:16 です(tvdpi 密度を除く)。 そのため、ldpi では 9x9 のビットマップ、mdpi では 12x12 のビットマップ、hdpi では 18x18 のビットマップ、xhdpi では 24x24 のビットマップとなります。

画像リソースがテレビや他の特定の端末で正常に表示されず、tvdpi リソースを試す場合、拡張係数は 1.33*mdpi になります。 たとえば、画面向けの 100px x 100px 画像は、tvdpi 向けにすると 133px x 133px となります。

注: 密度識別子を持つ場合でも、リソースがその密度の画面以外には対応しないということではありません。 現在の端末に最適な識別子を持つ代替リソースを提供していない場合でも、システムによって最適なリソースが使用されることがあります。

異なる画面密度を処理する方法や、Android が現在の密度に合わせてビットマップのサイズを変更する方法については、複数画面をサポートするをご覧ください。

タッチスクリーン タイプnotouch
finger
  • notouch:端末にはタッチスクリーンが搭載されていません。
  • finger:端末には、ユーザーの指先による指示操作で使用するためのタッチスクリーンが搭載されています。

touchscreen 設定フィールドもご覧ください。これは、端末上のタッチスクリーンのタイプを表します。

キーボードの使用可能状況keysexposed
keyshidden
keyssoft
  • keysexposed:端末ではキーボードを使用できます。端末でソフトウェア キーボードが有効な(と想定される)場合、端末にハードウェア キーボードが接続されておらず、ハードウェア キーボードがユーザーに提示されていない場合でも、この値が使用されることがあります。 ソフトウェア キーボードが提供されていない、または無効になっている場合は、ハードウェア キーボードが認識された場合にのみ使用されます。
  • keyshidden:端末には使用可能なハードウェア キーボードがありますが非表示になっています。また、端末ではソフトウェア キーボードが有効になっていません。
  • keyssoft:表示されているかどうかに関係なく、端末ではソフトウェア キーボードが有効になっています。

keysexposed リソースを提供するが、keyssoft リソースを提供しない場合、システムのソフトウェア キーボードが有効になっている場合は、キーボードが表示されているかに関係なく、システムは keysexposed リソースを使用します。

ユーザーがハードウェア キーボードを開くと、アプリケーションの実行中にこの値が変更されます。 実行時のアプリケーションに与える影響については、実行時の変更の処理をご覧ください。

さらに、設定フィールド hardKeyboardHiddenkeyboardHidden もご覧ください。それぞれ、ハードウェア キーボードと、任意のキーボード(ソフトウェアを含む)の可視性を表します。

主なテキスト入力方法nokeys
qwerty
12key
  • nokeys:端末にはテキスト入力用のハードウェア キーはありません。
  • qwerty:ユーザーに表示されているかどうかに関係なく、端末にはハードウェア クワーティ キーボードが搭載されています。
  • 12key:ユーザーに表示されているかどうかに関係なく、端末にはハードウェア 12key キーボードが搭載されています。

さらに、keyboard 設定フィールドもご覧ください。これは、使用可能な主なテキストの入力方法を表します。

プラットフォーム バージョン(API レベル)例:
v3
v4
v7
など

端末がサポートする API レベル。たとえば、v1 は API レベル 1(Android 1.0 以降の端末)、v4 は API レベル 4(Android 1.6 以降の端末)となります。 これらの値の詳細については、Android API levels のドキュメントをご覧ください。

注: Android 1.0 以降、いくつかの設定識別子が追加されているため、すべてのバージョンの Android がすべての識別子をサポートしているわけではありません。 新しい識別子を使用すると、旧式の端末がその識別子を無視できるように、プラットフォーム バージョンの識別子が暗黙的に追加されます。 たとえば、available-width の識別子は API レベル 13 で新たに追加されたため、w600dp 識別子を使用すると、自動的に v13 識別子が追加されます。 問題を回避するために、常に一連のデフォルト リソースを含めるようにします(識別子のない一連のリソース)。 詳細は、リソースとの最適な端末の互換性を提供するセクションをご覧ください。

修飾子の名前のルール

ここでは、設定修飾子の名前の使用方法に関するルールを説明します。

  • リソースの 1 つのセットに複数の修飾子を指定できます。その場合は、ダッシュで区切ります。たとえば、drawable-en-rUS-land は画面が横向きの米国英語の端末に適用されます。
  • 識別子は、次のように表 2 の順番で使用します。
    • 誤: drawable-hdpi-port/
    • 正: drawable-port-hdpi/
  • 代替リソースのディレクトリはネストできません。res/drawable/drawable-en/ などは使用できません。
  • 値は大文字と小文字を区別します。大文字と小文字を区別するファイル システムの問題を回避するために、処理前にリソース コンパイラーがディレクトリ名を小文字に変換します。 読みやすくする場合にのみ、名前に大文字を使用します。
  • それぞれの修飾子タイプに使用できる値は 1 つだけです。たとえば、スペインとフランスの両方に同じドローアブル ファイルを使用する場合も、ディレクトリ名を drawable-rES-rFR/ とすることはできません。 その代わりに、該当するファイルを含む drawable-rES/drawable-rFR/ という名前の 2 つのリソース ディレクトリが必要になります。ただし、実際のところ、両方の場所で同じファイルを重複させる必要はありません。 代わりに、リソースのエイリアスを作成できます。 後述のエイリアス リソースを作成するをご覧ください。

これらの修飾子を名前に持つディレクトリに代替リソースを保存すると、現在の端末設定に基づいて、Android がアプリケーションにリソースを自動的に適用します。 リソースが要求されるたびに、Android は要求されたリソース ファイルを持つ代替リソース ディレクトリを探し、最適なリソースを見つけます(後述)。 特定の端末設定に合う代替リソースがない場合、Android は対応するデフォルト リソース(設定識別子を含まない特定のリソースタイプ用の一連のリソース)を使用します。

エイリアス リソースを作成する

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

注: すべてのリソースに、別のリソースへのエイリアスを作成できるメカニズムが備わっているわけではありません。 特に、アニメーション、メニュー、未加工リソース、その他 xml/ ディレクトリにある未指定のリソースは、この機能に対応していません。

例として、アプリケーション アイコン icon.png について、ロケールごとに一意のバージョンが必要な状況を考えてみましょう。 ただし、英語カナダとフランス語カナダの 2 つのロケールでは同じバージョンを使用する必要があります。 英語カナダとフランス語カナダの両方のリソース ディレクトリに同じ画像をコピーする必要は実際にはありません。 代わりに、両方に使用する画像を icon_ca.png という名前(icon.png 以外の名前)で保存し、デフォルトの res/drawable/ ディレクトリに格納します。 次に <bitmap> 要素を使用して icon_ca.png リソースを参照する icon.xml ファイルを res/drawable-en-rCA/res/drawable-fr-rCA/ に作成します。 これにより、PNG ファイルを 1 つだけ作成し、それを指す小さな XML ファイルを 2 つ作成するだけで済みます (次に、XML ファイルの例を示します)。

ドローアブル

既存のドローアブルのエイリアスを作成するには、<bitmap> 要素を使用します。次に例を示します。

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

このファイルを icon.xml として(res/drawable-en-rCA/ などの代替リソース ディレクトリに)保存すると、R.drawable.icon として参照可能なリソースにコンパイルされますが、実際のところ、これは(res/drawable/ に保存されている) R.drawable.icon_ca リソースのエイリアスです。

レイアウト

既存のレイアウトのエイリアスを作成するには、<merge> にラップされる <include> 要素を使用します。 次に例を示します。

<?xml version="1.0" encoding="utf-8"?>
<merge>
    <include layout="@layout/main_ltr"/>
</merge>

このファイルを main.xml として保存すると、R.layout.main として参照可能なリソースにコンパイルされますが、実際のところ、これは R.layout.main_ltr リソースのエイリアスです。

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

既存の文字列のエイリアスを作成するには、単に、目的の文字列のリソース 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>

リソースとの最適な端末の互換性を提供する

アプリケーションで複数の端末設定をサポートするには、アプリケーションが使用するそれぞれのタイプのリソースに常にデフォルト リソースを提供することが重要です。

たとえば、アプリケーションが複数の言語をサポートする場合は、言語と地域の修飾子を持たない values/ ディレクトリ(文字列の保存先)を常に用意します。すべての文字列ファイルをすべて言語と地域の修飾子を持つディレクトリに配置してしまうと、自分の文字列がサポートしていない言語に設定された端末でアプリケーションを実行すると、アプリケーションがクラッシュしてしまいます。 一方、デフォルトの values/ リソースを提供しておけば、アプリケーションは適切に実行されます(ユーザーがその言語を理解できないとしても、クラッシュは避けられます)。

同様に、画面の向きに基づいた異なるレイアウト リソースを提供する場合も、いずれかの方向をデフォルトに設定する必要があります。 たとえば、横向き用のレイアウトリソースは layout-land/ に、縦向き用は layout-port/ に格納する代わりに、横向き用を layout/、縦向き用を layout-port/ のように、片方をデフォルトにしておきます。

予測しなかった設定でアプリケーションが実行されるだけでなく、新しいバージョンの Android では古いバージョンではサポートされない設定修飾子が追加されることもあるため、デフォルト リソースの提供が重要になります。 新しいリソース修飾子を使用するが、古いバージョンの Android とのコードの互換性を保持する場合、古いバージョンの Android でアプリケーションを実行するときにデフォルト リソースが提供されていないと、古いバージョンの Android では新しい修飾子の付いたリソースを使用できないために、アプリケーションがクラッシュします。 たとえば、minSdkVersion が 4 に設定されている場合に、ナイトモード(API レベル 8 で追加された nightnotnight)を使用してすべてのドローアブル リソースの修飾子を設定すると、API レベル 4 の端末はドローアブル リソースにアクセスできず、クラッシュします。 この場合、notnight をデフォルト リソースにしたいのであれば、この修飾子を除外します。よって、ドローアブル リソースは drawable/ または drawable-night/ に格納します。

そこで、端末の最適な互換性を提供するには、アプリケーションを適切に実行するのに必要なリソースに常にデフォルト リソースを提供するようにします。 次に、設定修飾子を使用して、特定の端末設定向けの代替リソースを作成します。

このルールには次の例外があります。アプリケーションの minSdkVersion が 4 以上の場合、画像密度修飾子で代替のドローアブル リソースを提供するときには、デフォルトのドローアブル リソースを提供する必要はありません。 デフォルトのドローアブル リソースがない場合でも、Android は代替の画面密度のなかで最適なものを見つけて、必要に応じてビットマップのサイズを変更できます。 ただし、すべてのタイプに最適な操作性を提供するには、密度の 3 つのタイプすべてに代替ドローアブルを提供する必要があります。

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

代替を提供するリソースを要求すると、現在の端末設定に応じて Android が実行時に使用する代替リソースを選択します。 Android が代替リソースを選択する方法説明するために、次のドローアブル ディレクトリを想定します。それぞれに同じ画像の異なるバージョンが入っています。

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

さらに、次のような端末設定を想定します。

ロケール = en-GB
画面の向き = port
画面ピクセル密度 = hdpi
タッチスクリーン タイプ = notouch
主なテキストの入力方法 = 12key

端末設定と使用可能な代替リソースを比較して、Android は drawable-en-port からドローアブルを選択します。

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

図 2. Android が最適なリソースを見つける仕組みを示したフローチャート。

  1. 端末設定に矛盾するリソース ファイルを排除します。

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

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

    例外: 画面ピクセル密度は、矛盾により排除されない修飾子の 1 つです。 それぞれの画面密度はその時点で最適であると判断されたものであるため、端末の画面密度が hdpi の場合でも、drawable-port-ldpi/ は排除されません。 詳細は、複数画面をサポートするのドキュメントをご覧ください。

  2. リスト(表 2)にある(次に)優先される修飾子を選択します(MCC から順に下がっていきます)。
  3. この修飾子を含むリソース ディレクトリがあるかどうかを確認します。
    • ない場合は、ステップ 2 に戻り、次の修飾子を調べます(この例では、言語識別子になるまですべて「いいえ」になります)。
    • 「はい」の場合は、ステップ 4 に進みます。
  4. この修飾子を持たないリソース ディレクトリを排除します。この例では、システムによって言語修飾子を含まないすべてのディレクトリが排除されます。
  5. drawable/
    drawable-en/
    drawable-en-port/
    drawable-en-notouch-12key/
    drawable-port-ldpi/
    drawable-port-notouch-12key/
    

    例外: 対象となる修飾子が画面ピクセル密度の場合、Android は端末の画像密度に最も近いオプションを選択します。一般的に、Android では小さな元画像を拡大するよりも、大きな元画像を縮小する方法が使用されます。 複数画面をサポートするをご覧ください。

  6. 残るディレクトリが 1 つになるまで、元に戻ってステップ 2、3、4 を繰り返します。このレイでは、次にマッチングするのが画面の向きの修飾子です。そのため、画面の向きを指定しないリソースは排除されます。
    drawable-en/
    drawable-en-port/
    drawable-en-notouch-12key/
    

    drawable-en-port ディレクトリが残ります。

この手順は要求した各リソースに対して実行されますが、システムはさらにいくつかの最適化を行います。 たとえば、端末の設定が判明すると、マッチングしない代替リソースが排除されたりします。 たとえば、設定言語が英語(「en」)の場合、言語修飾子が英語以外に設定されているリソース ディレクトリはチェック対象のリソースのプールに入ることはありません(言語修飾子のないリソース ディレクトリはそのままプールに入ります)。

画面サイズ修飾子に基づいてリソースを選択する場合、最適なリソースがない場合、システムは現在の画面よりも小さな画面向けのリソースを使用します(たとえば、必要に応じて大きなサイズの画面が通常サイズの画面のリソースを使用します)。 ただし、現在の画面よりも大きなサイズのリソースしか利用できない場合は、システムはそれらのリソースを使用しません。端末構成に合うリソースが他にない場合(すべてのリソースに xlarge 識別子のタグが付いているが、端末は通常サイズの画面である場合など)は、アプリケーションがクラッシュします

注: 表 2 の)上位にある修飾子の方が、端末に正確に一致する修飾子の数よりも重要になります。 たとえば、上のステップ 4 では、drawable-en には一致するパラメータが 1 つしかありませんが(言語)、リストの最後の選択肢には、端末に正確に一致する修飾子が 3 つあります(画面の向き、タッチスクリーン タイプ、入力方法)。 ただし、言語はこれらの他の修飾子よりも優先されるため、drawable-port-notouch-12key は排除されます。

アプリケーションでのリソースの使用方法については、リソースへのアクセスをご覧ください。