lightbulb_outline Help shape the future of the Google Play Console, Android Studio, and Firebase. Start survey

Предоставление ресурсов

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

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

Группирование типов ресурсов

Следует поместить ресурсы каждого типа в определенный подкаталог каталога res/ вашего проекта. В качестве примера приведена иерархия файлов для простого проекта:

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

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

Примечание. Подробные сведения об использовании папок множественного отображения см. в разделе Обзор управления проектами.

Таблица 1. Каталоги ресурсов, поддерживаемые в каталоге res/ проекта.

Каталог Тип ресурсов
animator/ Файлы XML, которые определяют анимации свойств.
anim/ Файлы XML, которые определяют анимации преобразований. (Анимации свойств также можно сохранять в этом каталоге, но для анимаций свойств предпочтительнее использовать каталог animator/, чтобы различать эти два типа).
color/ Файлы XML, которые определяют список состояний цветов. См. раздел Ресурс списка состояний цветов
drawable/

Файлы растровых изображений (.png, .9.png, .jpg, .gif) или файлы XML, которые составляют следующие подтипы графических ресурсов:

  • Файлы растровых изображений
  • Файлы из девяти фрагментов (растровые изображения с возможностью изменения размера)
  • Списки состояний
  • Формы
  • Графические анимации
  • Другие графические элементы

См. раздел Графические ресурсы.

mipmap/ Графические файлы для значков запуска с различной плотностью. Подробные сведения об управлении значками запуска с помощью папок mipmap/ см. в разделе Обзор управления проектами.
layout/ Файлы XML, которые определяют макет пользовательского интерфейса. См. раздел Ресурсы макетов.
menu/ Файлы XML, которые определяют меню приложения, такие как меню параметров, контекстные меню или вложенные меню. См. раздел Ресурсы меню.
raw/

Произвольные файлы для сохранения в исходной форме. Чтобы открыть эти ресурсы с помощью InputStream, вызовите Resources.openRawResource() с идентификатором ресурса, который имеет вид R.raw.<em>filename</em>.

Однако, если требуется получить доступ к исходным именам файлов и иерархии файлов, можно сохранять некоторые ресурсы в каталоге assets/ (вместо каталога res/raw/). Файлы в каталоге assets/ не получают идентификатора ресурса, поэтому их чтение возможно только с помощью AssetManager.

values/

Файлы XML, которые содержат простые значения, такие как строки, целые числа и цвета.

Тогда как XML-файлы ресурсов в других подкаталогах каталога res/ определяют отдельные ресурсы на базе имени файла XML, файлы в каталоге values/ описывают несколько ресурсов. Для файла в этом каталоге каждый дочерний элемент элемента &lt;resources&gt; определяет один ресурс. Например, элемент &lt;string&gt; создает ресурс R.string, а элемент &lt;color&gt; создает ресурс R.color .

Так как каждый ресурс определяется с помощью своего собственного элемента XML, можно назначать имя файла по своему усмотрению и помещать ресурсы разных типов в один файл. Тем не мене, может появиться необходимость поместить ресурсы отдельных типов в разные файлы. Например, ниже приведены соглашения для имен файлов ресурсов, которые можно создать в этом каталоге:

См. разделы Строковые ресурсы, Ресурсы стиля и Дополнительные типы ресурсов.

xml/ Произвольные XML-файлы, которые можно читать в режиме выполнения вызовом метода Resources.getXML(). Здесь должны сохраняться различные файлы конфигурации XML, например, конфигурация с возможностью поиска.

Предупреждение! Не сохраняйте файлы ресурсов непосредственно в каталоге res/, так как это вызывает ошибку компилятора.

Дополнительную информацию об определенных типах ресурсов см. в документации Типы ресурсов.

Ресурсы, сохраненные в подкаталогах, которые описаны в таблице 1, являются ресурсами «по умолчанию». Таким образом, эти ресурсы определяют дизайн и содержимое приложения по умолчанию. Однако различные типы устройств Android могут вызывать различные типы ресурсов. Например, если устройство оснащено экраном больше нормального, следует предоставить другие ресурсы макета, которые будут использовать преимущества дополнительного места на экране. Или, если устройство содержит различные языковые настройки, следует предоставить другие строковые ресурсы, содержащие перевод текста пользовательского интерфейса. Чтобы предоставить разные ресурсы для разных конфигураций устройств, необходимо предоставить альтернативные ресурсы в дополнение к ресурсам по умолчанию.

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

Рисунок 1. Два разных устройства, которые используют разные ресурсы макета.

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

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

  1. Создайте новый каталог в каталоге res/ с именем следующего вида <em>&lt;имя_ресурса&gt;</em>-<em>&lt;квалификатор_конфигурации&gt;</em>.
    • &lt;resources_name&gt; – имя каталога соответствующих ресурсов по умолчанию (определено в таблице 1).
    • &lt;qualifier&gt; – имя, которое указывает определенную конфигурацию, для которой должны использоваться эти ресурсы (определено в таблице 2).

    Можно добавлять несколько квалификаторов &lt;qualifier&gt;. Разделяйте их знаком дефиса.

    Предупреждение! При добавлении нескольких квалификаторов необходимо располагать их в том же порядке, в котором они перечислены в таблице 2. Если порядок квалификаторов нарушен, ресурсы игнорируются.

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

В качестве примера здесь приведено несколько ресурсов по умолчанию и альтернативных ресурсов:

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

Квалификатор hdpi указывает, что ресурсы в этом каталоге предназначены для устройств, оснащенных экраном высокой плотности. Изображения в каждом из этих каталогов для графических объектов имеют размер для определенной плотности экрана, но имена файлов полностью совпадают. Таким образом, идентификатор ресурса, который указывает на изображение icon.png или background.png, всегда одинаков, но Android выбирает версию каждого ресурса, которая оптимально соответствует текущему устройству, сравнивая информацию о конфигурации устройства с квалификаторами в имени каталога ресурсов.

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

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

Конфигурация Значения квалификатора Описание
MCC и MNC Примеры:
mcc310
mcc310-mnc004
mcc208-mnc00
и т. д.

Код страны для мобильной связи (MCC), за которым может следовать код сети мобильной связи (MNC) из SIM-карты устройства. Например, mcc310 – код США для любого поставщика услуг, mcc310-mnc004 – код США для Verizon и mcc208-mnc00 – код Франции для Orange.

Если в устройстве используется радиосвязь (телефон GSM), значения MCC и MNC добываются из SIM-карты.

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

См. также поля конфигурации mcc и mnc, которые указывают текущий код страны при мобильной связи и код сети мобильной связи соответственно.

Язык и регион Примеры:
en
fr
en-rUS
fr-rFR
fr-rCA
и т. д.

Язык задается двухбуквенным кодом языка ISO 639-1, к которому можно добавить двухбуквенный код региона 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.

smallestWidth sw<N>dp

Примеры:
sw320dp
sw600dp
sw720dp
и т. д.

Основной размер экрана, указывающий минимальный размер доступной области экрана. Точнее говоря, минимальная ширина устройства – это наименьший из двух размеров экрана: высоты и ширины (можно также называть ее «меньшей стороной» экрана). Этот квалификатор позволяет гарантировать, что независимо от текущей ориентации экрана приложение имеет доступную ширину пользовательского интерфейса не менее &lt;N&gt; пикселов.

Например, если для макета требуется, чтобы минимальный размер области экрана всегда был не менее 600 пикселов, можно использовать этот квалификатор для создания ресурсов этого макета, res/layout-sw600dp/. Система будет использовать эти ресурсы только в том случае, если минимальный размер доступной области экрана составляет не менее 600 пикселов, независимо от воспринимаемой пользователем высоты или ширины. Значение минимальной ширины является постоянной характеристикой размера экрана для устройства; минимальная ширина устройства не изменяется при изменении ориентации экрана.

Минимальная ширина устройства учитывает оформление экрана и пользовательский интерфейс системы. Например, если не экране присутствуют постоянные элементы пользовательского интерфейса, которые занимают пространство вдоль оси минимальной ширины, система объявляет, что минимальная ширина меньше фактического размера экрана, так как эти пикселы экрана недоступны для пользовательского интерфейса приложения. Следовательно используемое значение должно быть фактическим наименьшим размером, который необходим для вашего макета (обычно это значение является «минимальной шириной», которую поддерживает ваш макет, независимо от текущей ориентации экрана).

Здесь приведены некоторые значения, которые можно использовать для экранов обычных размеров:

  • 320 для устройств с конфигурациями экрана:
    • 240x320 ldpi (смартфон QVGA)
    • 320x480 mdpi (смартфон)
    • 480x800 hdpi (смартфон высокой плотности)
  • 480 для таких экранов, как 480x800 mdpi (планшет/смартфон).
  • 600 для таких экранов, как 600x1024 mdpi (планшет с диагональю 7").
  • 720 для таких экранов, как 720x1280 mdpi (планшет с диагональю 10").

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

Добавлено в API уровня 13.

См. также атрибут android:requiresSmallestWidthDp, который объявляет минимальную ширину, совместимую с вашим приложением, и поле конфигурации smallestScreenWidthDp, которое содержит значение минимальной ширины устройства.

Дополнительную информацию о разработке для различных экранов и использовании этого квалификатора см. в руководстве разработчика Поддержка нескольких экранов.

Доступная ширина w<N>dp

Примеры:
w720dp
w1024dp
и т. д.

Указывает минимальную доступную ширину экрана в единицах dp, для которой должен использоваться ресурс, заданный значением <N>. Это значение конфигурации будет изменяться в соответствии с текущей фактической шириной при изменении альбомной/книжной ориентации.

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

Добавлено в API уровня 13.

См. также поле конфигурации screenWidthDp , которое содержит текущую ширину экрана.

Дополнительную информацию о разработке для различных экранов и использовании этого квалификатора см. в руководстве разработчика Поддержка нескольких экранов.

Доступная высота h<N>dp

Примеры:
h720dp
h1024dp
и т. д.

Указывает минимальную доступную высоту экрана в пикселах, для которой должен использоваться ресурс, заданный значением <N>. Это значение конфигурации будет изменяться в соответствии с текущей фактической высотой при изменении альбомной/книжной ориентации.

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

Добавлено в API уровня 13.

См. также поле конфигурации screenHeightDp , которое содержит текущую ширину экрана.

Дополнительную информацию о разработке для различных экранов и использовании этого квалификатора см. в руководстве разработчика Поддержка нескольких экранов.

Размер экрана small
normal
large
xlarge
  • small: Экраны, подобные по размеру экрану QVGA низкой плотности. Минимальный размер макета для маленького экрана составляет приблизительно 320x426 пикселов. Примерами являются экраны QVGA низкой плотности и VGA высокой плотности.
  • normal: Экраны, подобные по размеру экрану HVGA средней плотности. Минимальный размер макета для нормального экрана составляет приблизительно 320x470 пикселов. Примерами таких экранов являются экраны WQVGA низкой плотности, HVGA средней плотности, WVGA высокой плотности.
  • large: Экраны, подобные по размеру экрану VGA средней плотности. Минимальный размер макета для большого экрана составляет приблизительно 480x640 пикселов. Примерами являются экраны VGA и WVGA средней плотности.
  • xlarge: Экраны значительно крупнее обычного экрана HVGA средней плотности. Минимальный размер макета для очень большого экрана составляет приблизительно 720x960 пикселов. В большинстве случаев устройства с очень большими экранами слишком велики для карманного использования и, скорее всего, относятся к планшетам. Добавлено в API уровня 9.

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

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

Добавлено в API уровня 4.

Дополнительную информацию см. в разделе Поддержка нескольких экранов.

См. также поле конфигурации screenLayout, которое указывает тип размера экрана: маленький, нормальный или большой.

Формат экрана long
notlong
  • long: Длинные экраны, такие как WQVGA, WVGA, FWVGA
  • notlong: Недлинные экраны, такие как QVGA, HVGA и VGA

Добавлено в API уровня 4.

Формат основан исключительно на соотношении сторон экрана («длинный» экран шире). Это не связано с ориентацией экрана.

См. также поле конфигурации screenLayout, которое указывает, является ли экран длинным.

Ориентация экрана port
land
  • port: Устройство в портретной (вертикальной) ориентации
  • land: Устройство в книжной (горизонтальной) ориентации

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

См. также поле конфигурации orientation, которое указывает текущую ориентацию устройства.

Режим пользовательского интерфейса car
desk
television
appliance watch
  • car: Устройство подсоединено к автомобильной док-станции
  • desk: Устройство подсоединено к настольной док-станции
  • television: Устройство подсоединено к телевизору, обеспечивая взаимодействие с расстояния «три метра», когда пользовательский интерфейс находится на большом экране, находящемся вдалеке от пользователя, ориентированное на управление с помощью навигационной клавиши или другого устройства без указателя
  • appliance: Устройство служит в качестве прибора без дисплея
  • watch: Устройство с дисплеем для ношения на запястье

Добавлено в API уровня 8, телевизор добавлен в API 13, часы добавлены в API 20.

Информацию о том, как приложение может реагировать на установку устройства в док-станцию или извлечение из нее, прочитайте документ Определение и мониторинг типа и состояния подключения к док-станции.

Подключение может измениться за время работы приложения, если пользователь помещает устройство в док-станцию. Некоторые из этих режимов можно включить или отключить с помощью UiModeManager. В разделе Обработка изменений в режиме выполнения содержится информация о воздействии таких изменений на приложение во время выполнения.

Ночной режим night
notnight
  • night: Ночное время
  • notnight: Дневное время

Добавлено в API уровня 8.

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

Плотность пикселов на экране (dpi) ldpi
mdpi
hdpi
xhdpi
xxhdpi
xxxhdpi
nodpi
tvdpi
  • ldpi: Экраны низкой плотности; приблизительно 120 dpi.
  • mdpi: Экраны средней плотности (обычные HVGA); приблизительно 160 dpi.
  • hdpi: Экраны высокой плотности; приблизительно 240 dpi.
  • xhdpi: Экраны очень высокой плотности; приблизительно 320 dpi. Добавлено в API уровня 8.
  • xxhdpi: Экраны сверхвысокой плотности; приблизительно 480 dpi. Добавлено в API уровня 16.
  • xxxhdpi: Использование исключительно высокой плотности (только значок запуска, см. примечание в документе Поддержка нескольких экранов); приблизительно 640 dpi. Добавлено в API уровня 18.
  • nodpi: Этот режим можно использовать для растровых графических ресурсов, которые не требуется масштабировать в соответствии с плотностью устройства.
  • tvdpi: Экраны промежуточной плотности между mdpi и hdpi; приблизительно 213 dpi. Этот режим не считается «основной» группой плотности. Он главным образом предназначен для телевизоров, и большинство приложений в нем не нуждается — при условии, что ресурсов mdpi и hdpi достаточно для большинства приложений, и система будет масштабировать их при необходимости. Этот квалификатор введен в API уровня 13.

Шесть основных уровней плотности соотносятся как 3:4:6:8:12:16 (если игнорировать плотность tvdpi). Так, растровое изображение 9x9 в ldpi представляется как 12x12 в mdpi, 18x18 в hdpi, 24x24 в xhdpi и т. д.

Если графические ресурсы выглядят недостаточно хорошо на телевизоре или других определенных устройствах, и хочется попробовать ресурсы tvdpi, используйте масштабный коэффициент 1,33*mdpi. Например, изображение 100 x 100 пикселов для экранов mdpi должно иметь размер 133 x 133 пиксела для tvdpi.

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

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

Тип сенсорного экрана notouch
finger
  • notouch: Устройство не оснащено сенсорным экраном.
  • finger: Устройство оснащено сенсорным экраном, предназначенным для ввода с помощью пальцев пользователя.

См. также поле конфигурации touchscreen, которое указывает тип сенсорного экрана устройства.

Доступность клавиатуры keysexposed
keyshidden
keyssoft
  • keysexposed: В устройстве доступна клавиатура. Если в устройстве включена экранная клавиатура (что весьма вероятно), она может использоваться даже в случае, когда аппаратная клавиатура недоступна пользователю, даже если устройство не имеет аппаратной клавиатуры. Если экранная клавиатура отсутствует или отключена, это квалификатор используется только в том случае, когда доступна аппаратная клавиатура.
  • keyshidden: Устройство имеет аппаратную клавиатуру, но она скрыта, и в устройстве не включена экранная клавиатура.
  • keyssoft: Экранная клавиатура в устройстве включена независимо от того, видна она или нет.

Если предоставляются ресурсы keysexposed, но не предоставляются ресурсы keyssoft, система использует ресурсы keysexposed независимо от видимости клавиатуры, поскольку в системе включена экранная клавиатура.

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

См. также поля конфигурации hardKeyboardHidden и keyboardHidden, которые указывают видимость аппаратной клавиатуры и видимость клавиатуры любого типа (включая экранную), соответственно.

Основной способ ввода текста nokeys
qwerty
12key
  • nokeys: В устройстве отсутствуют аппаратные клавиши для ввода текста.
  • qwerty: Устройство оснащено аппаратной клавиатурой с раскладкой qwerty, независимо от того, видна она пользователю или нет.
  • 12key: Устройство оснащено аппаратной клавиатурой с 12 клавишами, независимо от того, видна она пользователю или нет.

См. также поле конфигурации keyboard, которое указывает основной доступный способ ввода текста.

Версия платформы (уровень API) Примеры:
v3
v4
v7
и т. д.

Уровень API, поддерживаемый устройством. Например, v1 для уровня API 1 (устройства с Android 1.0 или выше) и v4 для уровня API 4 (устройства с Android 1.6 или выше). В документе Уровни API Android содержится дополнительная информация об этих значениях.

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

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

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

  • Можно указать несколько квалификаторов для одного набора ресурсов, разделяя их дефисами. Например, drawable-en-rUS-land применяется к устройствам в США, на английском языке в альбомной ориентации.
  • Квалификаторы должны идти в том же порядке, в котором они перечислены в таблице 2. Например:
    • Неправильно: drawable-hdpi-port/
    • Правильно: drawable-port-hdpi/
  • Нельзя использовать вложенные каталоги альтернативных ресурсов. Например, нельзя иметь каталог res/drawable/drawable-en/.
  • Значения не зависят от регистра букв. Компилятор ресурсов преобразует имена каталогов в нижний регистр перед обработкой, чтобы избежать проблем в файловых системах, не учитывающих регистр. Прописные буквы в именах служат исключительно для удобочитаемости.
  • Поддерживается только одно значение квалификатора каждого типа. Например, если требуется использовать одинаковые графические файлы для испанского и французского языков, нельзя создавать каталог с именем drawable-rES-rFR/. Вместо этого необходимо создать два каталога ресурсов, например, drawable-rES/ и drawable-rFR/, которые содержат соответствующие файлы. Однако не обязательно фактически копировать одинаковые файлы в оба каталога. Вместо этого можно создать псевдоним для ресурса. См. раздел Создание псевдонимов ресурсов ниже.

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

Создание псевдонимов ресурсов

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

Примечание. Не все ресурсы предлагают механизм, позволяющий создавать псевдоним для другого ресурса. В частности, анимации, меню, необработанные и другие неустановленные ресурсы в каталоге xml/ не содержат такой возможности.

Например, представьте, что имеется значок приложения, icon.png, и требуется иметь уникальные версии этого значка для разных языков. Однако в двух языках, канадском английском и канадском французском, требуется использовать одинаковую версию. Можно предположить, что требуется скопировать одно изображение в каталоги ресурсов для обоих языков, но это неверно. Вместо этого можно сохранить изображение для обоих языков, как icon_ca.png (любое имя, кроме icon.png), и поместить его в каталог по умолчанию res/drawable/. Затем создайте файл icon.xml в каталогах res/drawable-en-rCA/ и res/drawable-fr-rCA/ который ссылается на ресурс icon_ca.png с помощью элемента &lt;bitmap&gt;. Это позволяет хранить только одну версию файла PNG и два маленьких файла XML, которые указывают на него. (Пример файла XML показан ниже.)

Графические объекты

Чтобы создать псевдоним для существующего графического объекта, используйте элемент &lt;bitmap&gt;. Например:

<?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, но фактически он является псевдонимом для ресурса R.drawable.icon_ca (который сохранен в каталоге res/drawable/).

Макет

Чтобы создать псевдоним для существующего макета, используйте элемент &lt;include&gt; , заключенный в теги &lt;merge&gt;. Например:

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

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

Строки и другие простые значения

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

<?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="yellow">#f00</color>
    <color name="highlight">@color/red</color>
</resources>

Обеспечение оптимальной совместимости устройства с ресурсами

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

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

Таким же образом, если вы предоставляете различные ресурсы макета в зависимости от ориентации экрана, следует указать одну ориентацию в качестве ориентации по умолчанию. Например, вместо предоставления ресурсов макета в каталоге layout-land/ для альбомной ориентации и в каталоге layout-port/ для книжной ориентации, оставьте один вариант по умолчанию: например, layout/ для альбомной и layout-port/ для книжной ориентации.

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

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

Из этого правила есть одно исключение: Если в приложении для параметра minSdkVersion установлено значение 4 или выше, не требуется предоставлять графические ресурсы по умолчанию при предоставлении альтернативных графических ресурсов с квалификатором плотность экрана. Даже без графических ресурсов по умолчанию Android может найти наиболее подходящую альтернативную плотность экрана и масштабировать растровые изображения при необходимости. Однако для оптимальной работы на устройствах всех типов следует предоставить альтернативные графические ресурсы для всех трех типов плотности.

Как 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. Исключение файлов ресурсов, которые противоречат конфигурации устройства.

    Каталог 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/ не исключается, так как на этом этапе любая плотность экрана считается подходящей. Более подробная информация доступна в документе Поддержка нескольких экранов.

  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. Вернуться и повторять шаги 2, 3 и 4, пока не останется только один каталог. В нашем примере следующим квалификатором, для которого есть совпадения, является ориентация экрана. Поэтому исключаются ресурсы, не указывающие ориентацию экрана:
    drawable-en/
    drawable-en-port/
    drawable-en-notouch-12key/
    

    Остается каталог drawable-en-port.

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

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

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

Для получения более подробной информации об использовании ресурсов в приложении перейдите к разделу Доступ к ресурсам.