Перевод документации [1], в которой рассказывается о размещении различных ресурсов в программе Android. Все незнакомые сокращения и термины ищите в Словарике [5].

Вы всегда должны содержать ресурсы приложения (такие как изображения и строки) отдельно от Вашего кода - чтобы ресурсы можно было поддерживать независимо. Вы также должны предоставить альтернативные ресурсы для специальных конфигураций устройств Android, группируя их с помощью специальным образом именованных директорий ресурсов. Во время выполнения Android использует подходящие ресурсы, основываясь на текущей конфигурации. Например, Вы можете захотеть предоставить различную планировку интерфейса пользователя (UI layout) в зависимости от размера экрана или различные строки в зависимости от установок языка.

Как только Вы разместили ресурсы Вашего приложения, Вы можете получить к ним доступ с использованием идентификаторов ресурса (resource ID), которые автоматически генерируются в классе R проекта. Как использовать ресурсы в программе, рассказывается в [3]. Этот документ показывает, как группировать Ваши ресурсы в проекте Android, и предоставить альтернативные ресурсы для специфических конфигураций устройств.

[Группировка ресурсов по их типам]

Вы должны разместить каждый тип ресурса в отдельной поддиректории в директории res/ Вашего проекта. Например, вот такая конфигурация может быть для простого проекта:

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

Как Вы можете увидеть увидеть в этом примере, каталог res/ содержит все ресурсы (распределенные по поддиректориям): ресурс картинки, два ресурса layout, и файл строковых ресурсов. Имена директорий ресурсов имеют особое значение, и эти имена перечислены в таблице 1.

Таблица 1. Подкаталоги ресурсов, находящихся в директории res/ проекта.

Внимание: никогда не сохраняйте файлы ресурсов напрямую в директории res/ (без разделения по её дочерним директориям) - это приведет к ошибке компиляции. Не используйте для имен файлов ресурсов заглавных, русских букв, пробелов и спецсимволов - это также приведет к ошибке. Кроме того, имена файлов ресурсов всегда должны начинаться с буквы.

Для дополнительной информации по основным типам ресурсов см. [2].

Ресурсы, которые Вы сохраняете в подкаталогах, определенных в таблице 1, являются Вашими ресурсами "по умолчанию" (default resources). Т. е. эти ресурсы определяют оформление внешнего вида по умолчанию для приложения и его содержание. Однако различные типы устройств на базе OS Android могут применять разные типы ресурсов. Например, если устройство имеет экран, который больше обычного, то Вы должны предоставить различные layout-ресурсы, чтобы правильно задействовать дополнительное пространство на экране. Или, если устройство имеет другой установленный язык, то Вы должны предоставить отдельные строковые ресурсы, чтобы перевести на этот язык текст, отображаемый в интерфейсе. Для предоставления этих различных ресурсов для различных конфигураций устройств Вам нужно предоставить альтернативные ресурсы в дополнение к ресурсам по умолчанию.

[Предоставление альтернативных ресурсов]

Почти каждое приложение должно предоставить альтернативные ресурсы для поддержки специфических конфигураций устройств. Например, Вы должны подключить альтернативные рисуемые ресурсы (drawable resources) для различных плотностей точек экрана и альтернативные строковые ресурсы для разных языков. Во время выполнения Android автоматически определит текущую конфигурацию устройства и загрузит в приложение подходящие ресурсы.

Рис. 1. Два различных устройства, каждое использует разные layout-ресурсы.

Чтобы определить зависящий от конфигурации альтернативный набор ресурсов нужно сделать следующее:

1. Создайте новую директорию в папке res/, которая будет именоваться по шаблону < resources_name >-< config_qualifier >.

• < resources_name > является именем директории соответствующего ресурса по умолчанию (это одно из имен в таблице 1).
• < qualifier > это имя, которое указывает отдельную конфигурацию, для которой будут использоваться эти ресурсы (одно из имен в таблице 2).

Вы можете добавить больше чем один < qualifier >. Отделяйте каждый друг от друга через дефис.

Внимание: когда добавляете несколько квалификаторов, Вы должны их разместить в том же порядке, в каком они перечислены в таблице 2. Если квалификаторы будут размещены в неправильном порядке, то ресурсы будут игнорироваться.

2. Сохраните соответствующие альтернативные ресурсы в этой новой директории. Файлы ресурсов должны быть поименованы абсолютно так же, как и файлы ресурсов по умолчанию.

Например, имеется ресурсы по умолчанию и альтернативные:

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

Квалификатор hdpi показывает, что ресурсы в этой директории предназначены для устройств с экранами высокой плотности (high-density). Картинки в каждой из этих drawable-директорий имеют размер для своей специфической плотности экрана, но имена файлов полностью одинаковые. При таком методе доступа resource ID, которые Вы используете для ссылки на icon.png или background.png, останутся всегда одинаковыми для разных конфигураций, однако Android выберет версию каждого ресурса, которая лучше подходит для текущего устройства путем сравнения информации конфигурации устройства с квалификаторами в имени директории ресурсов.

Android поддерживает несколько квалификаторов конфигурации, и Вы можете добавить несколько квалификаторов в имя одной директории, но отделить каждое устройство черточкой в имени. В таблице 2 перечислены допустимые квалификаторы конфигурации в порядке приоритета — если Вы используете несколько квалификаторов для одной директории ресурса, то Вы должны добавить эти квалификаторы в имя директории в том же порядке, как они перечислены в таблице 2.

Таблица 2. Имена квалификаторов конфигурации.

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.)

Примечание: некоторые квалификаторы конфигурации были добавлены после выхода Android 1.0, так что не все версии могут поддерживать все квалификаторы. Использование нового идентификатора неявно добавляет квалификатор версии платформы, так что старые устройства могут игнорировать его. Например, использование квалификатора w600dp автоматически подключит квалификатор v13, поскольку доступный квалификатор ширины был новым в API level 13. Чтобы избежать любых проблем, всегда подключайте набор ресурсов по умолчанию (т. е. набор ресурсов без квалификаторов). Дополнительную информацию см. далее в разделе "Предоставление наилучшей совместимости устройств с помощью ресурсов".

[Правила имен квалификаторов]

Здесь приведены некоторые правила по использованию имен квалификаторов конфигурации:

• Вы можете указать несколько квалификаторов для одного набора ресурсов. При этом в имени подкаталога эти квалификаторы должны отделяться друг от друга дефисами. Например, drawable-en-rUS-land будут применены для англоязычных (US-English) устройств в горизонтальной (landscape) ориентации экрана.

• Квалификаторы должны быть указаны в том же самом порядке, в каком они появляются в таблице 2. Например, здесь квалификаторы указаны неправильно: drawable-hdpi-port/,
а здесь правильно: drawable-port-hdpi/

• Директории альтернативных ресурсов не могут вкладываться друг в друга. Например, Вы не можете иметь такую систему подкаталогов ресурсов: res/drawable/drawable-en/.

• Значения чувствительны к регистру символов (case-insensitive). Компилятор ресурсов перед обработкой конвертирует имена директорий в нижний регистр (lower case, маленькие буквы), чтобы избежать проблем на файловых системах, которые нечувствительны к регистру символов (case-insensitive file system; к примеру, такими системами являются FAT и NTFS). Любые заглавные имена в именах только улучшают читаемость.

• Для каждого типа идентификатора поддерживается только одно значение. Например, если Вы хотите использовать одинаковые drawable-файлы для Испании (Spain) и для Франции (France), то Вы не можете иметь каталоги, именованные drawable-rES-rFR/. Вместо этого нужны две директории ресурсов, такие как drawable-rES/ и drawable-rFR/, в каждой из которых содержаться подходящие файлы. Однако не требуется дублировать те же самые файлы в обоих подкаталогах. Вместо этого Вы можете создать псевдоним (alias) ресурса. См. далее раздел "Создание псевдонимов ресурсов".

После того, как Вы сохранили альтернативные ресурсы в директориях, именованных с этими квалификаторами, Android автоматически применит эти ресурсы в Вашем приложении, основываясь на текущей конфигурации устройства. Каждый раз, когда запрашивается ресурс, Android проверяет директории альтернативных ресурсов, которые содержат запрашиваемый файл ресурса, затем находит наиболее подходящий ресурс (этот процесс рассмотрен ниже). Если не найдены альтернативные ресурсы, которые подходят к частной текущей конфигурации устройства, то Android использует соответствующие ресурсы по умолчанию (это набор ресурсов, для которых отдельные типы ресурсов не содержат квалификаторов в именах своих подкаталогов).

[Создание псевдонимов ресурсов (resource alias)]

Когда у Вас есть ресурс, который Вы хотите использовать не только в одной конфигурации, а нескольких (но не хотите этот ресурс использовать в качестве ресурса по умолчанию), то Вам не нужно делать его копии и помещать эти копии в директории для альтернативных ресурсов. Вместо этого Вы можете (в некоторых случаях) создать альтернативный ресурс, который будет работать как псевдоним (alias) для ресурса, сохраненного в Вашей директории ресурсов по умолчанию.

Внимание: не все ресурсы имеют механизм для создания алиасов на другой ресурс. В частности animation, menu, raw и другие не указанные ресурсы (unspecified resources) в директории xml/ не предоставляют такую возможность.

Представим себе, что Вы имеете иконку приложения icon.png, и Вам нужна её уникальная версия для разных языков (установок локали). Однако две локали English-Canadian и French-Canadian должны использовать одну и ту же версию иконки. Вы можете решить сделать копию той же самой картинки как в директорию ресурсов для English-Canadian, так и в директорию для French-Canadian, но это будет неправильным (хотя бы с точки зрения экономия места на диске). Вместо копирования Вы можете сохранить картинку, которая используется в обоих случаях, в виде файла наподобие icon_ca.png (можно использовать любое имя кроме icon.png), поместить этот файл в директорию по умолчанию res/drawable/. Затем создайте файл icon.xml в каталоге res/drawable-en-rCA/ и в каталоге res/drawable-fr-rCA/, и сделайте в них ссылку на ресурс icon_ca.png, используя элемент < bitmap >. Это позволяет Вам сохранить только одну версию файла PNG, и два маленьких текстовых файла XML, которые указывают на него. Ниже приведен пример такого файла XML.

Ресурс Drawable

Для создания алиаса на существующий drawable, используйте элемент < bitmap >. Например:

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

Если Вы сохраните этот XML в файл icon.xml (в директории альтернативных ресурсов, такой как res/drawable-en-rCA/), то он будет скомпилирован в ресурс, к которому можно обращаться как к R.drawable.icon, но в действительности это будет алиас на ресурс R.drawable.icon_ca (который сохранен в каталоге res/drawable/).

Ресурс Layout

Чтобы создать алиас на существующий layout, используйте элемент < include >, обернутый в < merge >. Например:

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

Если Вы сохраните этот XML в файл main.xml, то он будет скомпилирован в ресурс, к которому можно обращаться как к R.layout.main, но в действительности это будет алиас на ресурс R.layout.main_ltr.

Ресурсы строк (Strings) и другие простые значения

Чтобы создать алиас для существующей строки, просто используйте resource 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.

Другие простые значения работают таким же образом. Вот пример для цвета (color):

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

[Предоставление наилучшей совместимости устройств с помощью ресурсов]

Чтобы Ваша программа могла поддерживать как можно больше конфигураций устройств, очень важно предоставить ресурсы по умолчанию для каждого типа ресурсов, который использует Ваше приложение.

Например, если Ваше приложение поддерживает несколько языков, всегда добавляйте директорию values/ (в которой будут сохранены Ваши строки) без квалификатора языка и региона. Если вы вместо этого поместите Ваши строки в директории, которые имеют квалификаторы языка и региона, то Ваше приложение завершится с ошибкой при запуске на устройстве, у которого установлен язык, не поддерживаемый Вашими строками. Однако если Вы предоставите ресурсы по умолчанию values/, то Ваше приложение сможет правильно запуститься (даже если пользователь не поймет ничего в интерфейсе, это всегда лучше краха приложения).

Аналогично, если Вы предоставите разные layout-ресурсы, базируясь на ориентации экрана, Вы все равно должны выбрать одну ориентацию в качестве ориентации по умолчанию. Например, вместо того, чтобы предоставить ресурсы layout в каталогах layout-land/ для пейзажной ориентации (landscape) и layout-port/ для портретной ориентации (portrait), оставьте одну в качестве ориентации по умолчанию, такую как layout/ для ориентации landscape и layout-port/ для ориентации portrait.

Предоставлять ресурсы по умолчанию важно не только потому что Ваше приложение может работать на конфигурации Android, которую Вы не ожидали, но также и потому, что новые версии Android иногда добавляют квалификаторы конфигурации, которые старые версии не поддерживают. Если Вы используете новый квалификатор ресурса, но поддерживаете совместимость кода со старыми версиями Android, то когда старая версия Android запустит Ваше приложение, оно рухнет, если Вы не предоставите ресурсы по умолчанию, потому что не сможет использовать имена ресурсов с новым квалификатором. Например, если Ваша minSdkVersion установлена в 4, и Вы квалифицируете все Ваши drawable-ресурсы с использованием ночного режима (night mode, night или notnight, которые были добавлены в API Level 8), то устройство на системе API level 4 не сможет получить доступ к Вашим drawable-ресурсам и завершится по ошибке. В этом случае Вы можете захотеть использовать в качестве ресурса по умолчанию notnight, так что Вам нужно исключить этот квалификатор для drawable-ресурсов, которые находятся либо в drawable/, либо в drawable-night/.

Таким образом, чтобы предоставить наилучшую совместимость для устройств, всегда предоставляйте ресурсы по умолчанию (default resources) для тех ресурсов, которые нужны Вашему приложению, чтобы оно могло правильно работать. Затем создайте альтернативные ресурсы для отдельных конфигураций устройств, используя квалификаторы конфигурации.

Есть только одно исключение из этого правила: если minSdkVersion Вашего приложения 4 или больше, то Вам не нужно иметь drawable-ресурсы по умолчанию, когда Вы предоставили альтернативные drawable-ресурсы с квалификатором плотности экрана (screen density qualifier). Даже без drawable-ресурсов по умолчанию Android может найти лучший вариант альтернативных плотностей экрана, и смасштабировать картинки как это требуется. Однако, для лучшей поддержки на всех типов устройств Вы должны предоставить альтернативные drawable-ресурсы для всех трех типов плотностей экрана.

[По какому принципу Android находит самый подходящий ресурс]

Когда Вы запрашиваете ресурс, для которого Вы предоставили альтернативы, Android во время выполнения выберет из них какой-то один, в зависимости от текущей конфигурации устройства. Чтобы продемонстрировать, как Android выбирает альтернативный ресурс, предположим, что есть следующие drawable директории, каждая из которых содержит различные версии тех же самых картинок:

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

И предположим, что устройство имеет следующую конфигурацию:

Locale (язык) = en-GB
Ориентация экрана портретная = port
Screen pixel density (плотность пикселов экрана) = hdpi
Тип тачскрина = notouch
Главный метод текстового ввода = 12key

Путем сравнения конфигурации устройства с доступными альтернативными ресурсами, Android выберет в такой ситуации рисуемые ресурсы из drawable-en-port.

Рис. 2. Диаграмма, показывающая алгоритм выбора наилучшего ресурса для приложения.

Когда система принимает решение о том, какой ресурс выбрать, она придерживается следующей логики:

1. Отбрасываются ресурсы, которые противоречат конфигурации устройства. Для нашего примера директория drawable-fr-rCA/ будет отброшена, потому что противоречит установленной локали en-GB.

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

Исключение из правила: плотность пикселов на экране является единственным квалификатором, который не отбрасывается из за противоречия с конфигурацией. Даже если плотность экрана устройства hdpi, директория drawable-port-ldpi/ не будет отброшена, потому что в этой точке принимается решение, что любое разрешение подходит. Дополнительную информацию см. в документе Supporting Multiple Screens.

2. Выбирается в списке следующий по важности квалификатор (список согласно таблице 2). Просмотр списка начинается с квалификатора MCC, и далее просмотр переходит все ниже и ниже по списку.

3. Делается проверка: указан ли в имени какой-либо директории этот квалификатор? Если нет, то переход на шаг 2, и продолжение просмотра списка. Если да, то продолжить с шага 4.

4. Отбрасываются ресурсы, которые не включают этот квалификатор. В нашем примере система отбросит все директории ресурсов, которые не включают квалификатор языка:

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

Исключение из правила: если рассматриваемый квалификатор плотность экрана, то Android выбирает самую близко подходящую к устройству плотность экрана. В целом Android предпочитает уменьшить масштаб бОльшего исходного изображения вместо увеличения масштаба меньшего исходного изображения. См. Supporting Multiple Screens.

5. Происходит возврат назад и повторяются шаги 2, 3 и 4, пока не останется только одна директория. В нашем примере ориентация экрана оказывается следующим квалификатором, для которого есть любые соответствия. Таким образом, ресурсы с не указанной ориентацией экрана будут отброшены:

drawable-en/
drawable-en-port/
drawable-en-notouch-12key/

В результате осталась только конфигурация drawable-en-port.

Через эта процедуру проходит каждый запрашиваемый ресурс, но система оптимизирует некоторые аспекты. Одна их таких оптимизаций - могут быть отброшены альтернативные ресурсы, которые никогда не будут подходить. Например, если язык конфигурации English ("en"), то любая директория, которая содержит в имени другой квалификатор, никогда не попадет в пул опрашиваемых ресурсов (хотя директории ресурсов без квалификатора языка все еще будут в опрашиваемом пуле).

Когда происходит выбор ресурсов на основе квалификаторов размера экрана, система будет использовать ресурсы, разработанные для экранов меньшего размера, чем текущий экран, если нет ресурсов с совпадением лучше (например, если необходимо, то экраны с большим размером будут использовать ресурсы экрана с нормальным размером). Однако если единственные имеющиеся ресурсы будут предназначены для экрана больше, чем текущий, то система не будет их использовать, и Ваше приложение завершится с ошибкой, если никакие другие ресурсы не подойдут для текущей конфигурации (например, если все layout-ресурсы помечены квалификатором xlarge, но устройство имеет экран с размером normal).

Примечание: приоритет квалификатора (согласно таблице 2) более важен, чем количество квалификаторов, которые полностью соответствуют устройству. К примеру на шаге 4 последний выбор в списке включает три квалификатора, которые полностью соответствуют устройству (ориентация экрана, тип тачскрина, метод ввода), в то время как drawable-en совпадает только по одному параметру (язык). Однако, поскольку язык имеет согласно таблице 2 приоритет выше (он находится ближе к началу таблицы), чем эти другие квалификаторы, то конфигурация drawable-port-notouch-12key будет отброшена.

Чтобы узнать больше о том, как использовать ресурсы в приложении, см. [3].

[Ссылки]

1. Providing Resources site:developer.android.com.
2. Типы ресурсов приложения Android.
3. Получение доступа к ресурсам приложения Android.
4. AnimationDrawable: создание анимированной кнопки.
5. Словарик Android.