应用资源概览

资源是指代码使用的附加文件和静态内容，例如位图、布局定义、界面字符串、动画说明等。

请始终将应用资源（例如图片和字符串）与代码分隔开，以便能够独立地维护这些资源。此外，还应为特定设备配置提供备用资源，方法是将其进行分组并放入专门命名的资源目录中。在运行时，Android 会根据当前配置使用合适的资源。例如，您可能想根据屏幕尺寸提供不同的界面布局，或根据语言设置提供不同的字符串。

外部化应用资源后，您便可使用在项目的 R 类中生成的资源 ID 来访问相应资源。本文档介绍了如何对 Android 项目中的资源进行分组。此外，还介绍了如何为特定设备配置提供备用资源，以及如何从您的应用代码或其他 XML 文件访问这些资源。

分组资源类型

将每种类型的资源放在项目的 res/ 目录下的相应子目录中。例如，以下是一个简单项目的文件层次结构：

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

res/ 目录中包含存储在其子目录中的所有资源，包括一个图片资源、两个布局资源、一个用于存储启动器图标的 mipmap/ 目录，以及一个字符串资源文件。资源目录名称非常重要，具体说明请参见表 1。

注意：如需详细了解如何使用 mipmap 文件夹，请参阅将应用图标放在 mipmap 目录中。

表 1. 项目 res/ 目录中支持的资源目录。

目录	资源类型
animator/	用于定义属性动画的 XML 文件。
anim/	用于定义补间动画的 XML 文件。属性动画也可保存在此目录中，但为了区分这两种类型，属性动画首选 animator/ 目录。
color/	用于定义颜色状态列表的 XML 文件。如需了解详情，请参阅颜色状态列表资源。
drawable/	位图文件（PNG、.9.png、JPG 或 GIF）或编译为以下可绘制资源子类型的 XML 文件： 位图文件 九宫图（可调整大小的位图） 状态列表 形状 动画可绘制对象 其他可绘制对象 如需了解详情，请参阅可绘制资源。
mipmap/	适用于不同启动器图标密度的可绘制对象文件。如需详细了解如何使用 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 文件名定义单个资源，而 values/ 目录中的文件可描述多个资源。对于此目录中的文件，<resources> 元素的每个子元素均会定义一个资源。例如，<string> 元素会创建一个 R.string 资源，<color> 元素会创建一个 R.color 资源。 由于每个资源均使用自己的 XML 元素进行定义，因此您可以随意命名文件，并在同一文件中放入不同的资源类型。但是，您可能需要将不同的资源类型分别放在不同的文件中，使其一目了然。例如，对于可在此目录中创建的资源，下面给出了相应的文件名约定： arrays.xml 用于资源数组（类型化数组） colors.xml 用于颜色值 dimens.xml 用于维度值 strings.xml 用于字符串值 styles.xml 用于样式 如需了解详情，请参阅字符串资源、样式资源和更多资源类型。
xml/	可在运行时通过调用 Resources.getXML() 读取的任意 XML 文件。各种 XML 配置文件（例如搜索配置）都必须保存在此处。
font/	带有扩展名的字体文件（例如 TTF、OTF 或 TTC），或包含 <font-family> 元素的 XML 文件。如需详细了解以资源形式使用的字体，请参阅将字体添加为 XML 资源。

注意：切勿将资源文件直接保存在 res/ 目录内，否则会导致编译器错误。

如需详细了解各种资源类型，请参阅资源类型概览。

在表 1 定义的子目录中，保存的资源为默认资源。换言之，这些资源定义应用的默认设计和内容。然而，不同类型的 Android 设备可能需要不同类型的资源。

例如，您可以为屏幕尺寸大于普通屏幕的设备提供不同的布局资源，以充分利用额外的屏幕空间。您还可以提供不同的字符串资源，以便根据设备的语言设置翻译界面中的文本。如需为不同设备配置提供这些不同资源，除默认资源以外，您还需提供备用资源。

提供备用资源

大多数应用都提供备用资源，以便支持特定的设备配置。例如，对于不同的屏幕密度和语言，分别添加备用可绘制资源和备用字符串资源。在运行时，Android 会检测当前设备配置并为应用加载合适的资源。

图 1. 根据屏幕尺寸，两台设备使用不同的布局资源。

如需为一组资源指定适用于特定配置的备用资源，请执行以下操作：

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 限定符表示该目录中的资源适用于屏幕密度较高的设备。这些可绘制目录中的图片根据特定的屏幕密度来调整大小，但文件名完全相同。如此一来，用于引用 icon.png 或 background.png 图片的资源 ID 始终相同。Android 会通过将设备配置信息与资源目录名称中的限定符进行比较，选择最符合当前设备的各个资源版本。

注意：定义备用资源时，请确保也在默认配置中定义该资源。否则，当设备更改配置时，您的应用可能会遇到运行时异常。例如，如果您仅向 values-en（而不是 values）添加字符串，则当用户更改默认系统语言时，您的应用可能会出现 Resource Not Found 异常。

表 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 限定符，请谨慎执行此操作并测试限定符是否按预期工作。 另请参阅配置字段 mcc 和 mnc，二者分别表示当前的移动设备国家/地区代码和移动网络代码。
语言、脚本（可选）和区域（可选）	示例： en fr en-rUS fr-rFR fr-rCA b+en b+en+US b+es+419 b+zh+Hant b+sr+Latn+RS	语言通过由两个字母组成的 ISO 639-1 语言代码进行定义，可以选择后跟两个字母组成的 ISO 3166-1-alpha-2 区域码（前缀用小写字母 r）。 这些代码不区分大小写。r 前缀用于区分区域码。您不能单独指定区域。 Android 7.0（API 级别 24）引入对 BCP 47 语言标记的支持，可供您用来限定特定于语言和区域的资源。语言标记由一个或多个子标记序列组成，每个子标记都能优化或缩小由整体标记标识的语言范围。如需了解有关语言标记的详细信息，请参阅用于标识语言的标记。 如要使用 BCP 47 语言标记，请将 b+ 和两个字母的 ISO 639-1 语言代码串联；其后还可选择使用其他子标记，用 + 分隔即可。 如果用户在系统设置中更改语言，则语言标记可能会在应用的生命周期中发生变更。如需了解这会在运行时期间给应用带来哪些影响，请参阅处理配置更改。 如需查看将应用本地化为其他语言的完整指南，请参阅本地化您的应用。 另请参阅 getLocales() 方法，了解该方法提供的已定义语言区域列表。此列表包含主要的语言区域。
布局方向	ldrtl ldltr	应用的布局方向。ldrtl 是指“布局方向从右到左”。ldltr 是指“布局方向从左到右”（默认的隐式值）。 此配置适用于布局、可绘制对象或值等任何资源。 例如，如需针对阿拉伯语提供某种特定布局，并针对任何其他“从右到左”的语言（例如波斯语或希伯来语）提供某种通用布局，则可使用以下目录： res/   layout/     main.xml（默认布局）   layout-ar/     main.xml（特定于阿拉伯语的布局）   layout-ldrtl/     main.xml（任何“从右到左”语言，阿拉伯语除外，因为“ar”语言限定符具有更高的优先级。） 注意：如要为应用启用从右到左的布局功能，则必须将 SupportsRtl 设置为 "true"，并将 TargetSdkVersion 设置为 17 或更高版本。 此项为 API 级别 17 中的新增配置。
最小宽度	sw<N>dp 示例： sw320dp sw600dp sw720dp 等等	应用可用屏幕区域的最短尺寸。具体而言，应用窗口的 smallestWidth 是窗口可用高度和宽度的最小尺寸。您也可将其视为窗口的“最小可能宽度”。您可使用此限定符，让应用界面的可用宽度至少为 <N> dp。 例如，如果布局要求屏幕区域的最小尺寸始终至少为 600 dp，则可使用此限定符在 res/layout-sw600dp/ 目录中创建布局资源。仅当可用屏幕的最小尺寸至少为 600 dp（无论 600 dp 表示的边是用户所认为的高度还是宽度）时，系统才会使用这些资源。调整窗口大小（更改可用宽度/高度）或重新定位（可能会更改系统边衬区）时，最小宽度可能会改变。 使用最小宽度确定一般屏幕尺寸非常有用，因为宽度通常是设计布局时的驱动因素。界面通常是竖直滚动的，但其在水平方向上所需的最小空间则相对有很多的限制。 可用宽度也是确定是否针对手机使用单窗格布局，或针对平板电脑使用多窗格布局的关键因素。因此，您可能最关注每台设备上的最小可能宽度。 设备的最小宽度会将屏幕装饰元素和系统界面考虑在内。例如，如果设备屏幕上的永久性界面元素沿着最小宽度轴占据空间，则系统会声明最小宽度小于实际屏幕尺寸，因为这些屏幕像素不适用于您的界面。 以下是一些可用于常见屏幕尺寸的值： 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）和 smallestScreenWidthDp 配置字段（存放设备的 smallestWidth 值）。 如需详细了解如何使用此限定符针对不同的屏幕进行设计，请参阅 使用 View 实现响应式/自适应设计。
可用宽度和高度	w<N>dp h<N>dp 示例： w720dp w1024dp h720dp h1024dp 等等	指定资源使用的最小可用屏幕宽度或高度（以 dp 为单位，由 <N> 值定义）。当设备屏幕方向在横屏和竖屏之间切换时、设备折叠或展开时或者系统进入或退出多窗口模式时，系统会将这些配置值与当前的显示宽度和高度进行比较。在多窗口模式下，这些值反映的是包含应用的窗口的宽度和高度，而不是设备屏幕的宽度和高度。同样，对于嵌入的 activity，该值与各个 activity 的宽度和高度（而非屏幕的宽度和高度）。如需了解详情，请参阅 activity 嵌入。 可用宽度和高度通常有助于确定是否使用多窗格布局，因为即使是在平板电脑设备上，您通常也不希望在竖屏模式下像横屏模式那样使用多窗格布局。因此，您可以使用这些限定符来指定布局所需的最小宽度和/或高度，而无需同时使用屏幕尺寸和屏幕方向限定符。 当应用为这些配置提供具有不同值的多个资源目录时，系统会使用最接近（但未超出）设备当前屏幕宽度的值。系统将实际屏幕宽度与指定宽度之间的差值和实际屏幕高度与指定高度之间的差值相加（未指定的高度和宽度值为 0），以确定最接近的目录。 该值会排除窗口边衬区占据的区域，因此，如果设备显示屏的边缘具有永久性界面元素，则宽度和高度值会小于实际屏幕尺寸（即使应用使用 Window.setDecorFitsSystemWindows 或 WindowCompat.setDecorFitsSystemWindows 以边缘对齐的方式显示）。 部分非固定的竖屏装饰（例如可在全屏模式下可隐藏的手机状态栏）和窗口装饰（例如标题栏或操作栏）不在考虑范围之内，因此应用必须准备好处理稍小于其指定值的空间。 注意：系统会选择宽度和高度均匹配的资源。因此，强烈建议您同时指定这两种资源，而不是仅指定其中一种资源。例如，如果实际屏幕为 w720dp 乘以 h1280dp，并且其中一个资源符合 w720dp 的条件，另一个资源符合 w700dp-h1200dp 的条件，即使前一个资源与其指定的资源完全匹配，系统也会选择后者。 此项为 API 级别 13 中的新增配置。 另请参阅 screenWidthDp 和 screenHeightDp 配置字段，这些字段用于保存当前屏幕的宽度和高度。 如需详细了解如何使用此限定符针对不同的屏幕进行设计，请参阅 使用 View 实现响应式/自适应设计。
屏幕尺寸	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 中的新增配置。 此配置完全基于屏幕的纵横比（long 屏较宽），与屏幕方向无关。 另请参阅 screenLayout 配置字段，该字段用于指示屏幕是否为宽屏。
圆形屏幕	round notround	round：圆形屏幕，例如圆形可穿戴式设备 notround：方形屏幕，例如手机或平板电脑 此项为 API 级别 23 中的新增配置。 另请参阅 isScreenRound() 配置方法，该方法用于指示屏幕是否为圆形屏幕。
广色域	widecg nowidecg	widecg：显示广色域，如 Display P3 或 AdobeRGB nowidecg：显示窄色域，如 sRGB 此项为 API 级别 26 中的新增配置。 另请参阅 isScreenWideColorGamut() 配置方法，该方法用于指示屏幕是否具有广色域。
高动态范围 (HDR)	highdr lowdr	highdr：显示高动态范围 lowdr：显示低/标准动态范围 此项为 API 级别 26 中的新增配置。 另请参阅 isScreenHdr() 配置方法，该方法用于指示屏幕是否具有 HDR 功能。
屏幕方向	port land	port：设备处于竖屏模式（纵向） land：设备处于横屏模式（水平） 如果用户旋转屏幕，此配置可能会在应用生命周期中发生变化。如需了解这会在运行时期间给应用带来哪些影响，请参阅处理配置更改。 另请参阅 orientation 配置字段，该字段用于指示当前的设备方向。
界面模式	car desk television appliance watch vrheadset	car：设备正在车载基座中显示 desk：设备正在桌面基座中显示 television：设备正在通过电视显示内容，通过将界面投影到离用户较远的大屏幕上，为用户提供“十英尺”体验。该体验主要面向遥控交互或其他非触控式交互 appliance：设备用作不带显示屏的装置 watch：设备配有显示屏，并且可戴在手腕上 vrheadset：设备正在通过虚拟现实耳机显示内容 此项为 API 级别 8 中的新增配置；API 13 中的新增电视配置；API 20 中的新增手表配置。 如需了解在设备插入基座或从基座中取出时您的应用会如何响应，请参阅确定和监控插接状态和基座类型。 如果用户将设备插入基座，此配置可能会在应用生命周期中发生变化。您可以使用 UiModeManager 启用或停用其中的部分模式。如需了解这会在运行时期间给应用带来哪些影响，请参阅处理配置更改。
夜间模式	night notnight	night：夜晚时光 notnight：日间节目 此项为 API 级别 8 中的新增配置。 如果夜间模式停留在自动模式（默认），此配置可能会在应用生命周期中发生变化。在这种情况下，该模式会根据当天的时间进行调整。您可以使用 UiModeManager 启用或停用此模式。如需了解这会在运行时期间给应用带来哪些影响，请参阅处理配置更改。
屏幕像素密度 (dpi)	ldpi mdpi hdpi xhdpi xxhdpi xxxhdpi nodpi tvdpi anydpi nnndpi	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。 这不属于“主要”密度组。它主要用于 720p 电视，而大多数应用都不需要它。对于 1080p 电视面板，请使用 xhdpi；对于 4K 电视面板，请使用 xxxhdpi。此项为 API 级别 13 中的新增配置。 anydpi：适合所有屏幕密度，其优先级高于其他限定符。这对于矢量可绘制对象非常有用。此项为 API 级别 21 中的新增配置。 nnndpi：用于表示非标准密度，其中 nnn 是正整数屏幕密度。大多数情况下不使用此限定符。使用标准密度存储分区，可显著减少因支持市场上各种设备屏幕密度而产生的开销。 这六种主要密度之间的缩放比例为 3:4:6:8:12:16（tvdpi 密度忽略不计）。因此，9x9 (ldpi) 位图相当于 12x12 (mdpi)、18x18 (hdpi)、24x24 (xhdpi) 位图，依此类推。 注意：使用密度限定符并不意味着资源仅适用于该密度的屏幕。如果您没有为备用资源提供最符合当前设备配置的限定符，则系统会使用其中最匹配的资源。 如需详细了解如何处理不同屏幕密度以及 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 配置字段，该字段用于指示可用的主要文本输入法。
导航键可用性	navexposed navhidden	navexposed：导航键可供用户使用。 navhidden：导航键不可用（例如位于合上的盖子后面）。 如果用户显示导航键，此配置可能会在应用生命周期中发生变化。如需了解这会在运行时期间给应用带来哪些影响，请参阅处理配置更改。 另请参阅 navigationHidden 配置字段，该字段用于指示导航键是否处于隐藏状态。
主要的非触摸导航方法	nonav dpad trackball wheel	nonav：除了使用触摸屏以外，设备没有其他导航设施。 dpad：设备具有用于导航的方向键。 trackball：设备具有用于导航的轨迹球。 wheel：设备具有用于导航方向盘（不常见）。 另请参阅 navigation 配置字段，该字段用于指示可用的导航方法类型。
平台版本（API 级别）	示例： v3 v4 v7 等等	设备支持的 API 级别。例如，v1 对应 API 级别 1（搭载 Android 1.0 或更高版本的设备）；v4 对应 API 级别 4（搭载 Android 1.6 或更高版本的设备）。如需了解有关这些值的详细信息，请参阅 Android API 级别文档。

注意：并非所有版本的 Android 系统都支持所有限定符。使用新限定符会隐式添加平台版本限定符，因此较旧版本系统的设备可以忽略它。例如，使用 w600dp 限定符会自动包括 v13 限定符，因为可用宽度限定符是 API 级别 13 中的新增配置。为避免出现任何问题，请始终包含一组默认资源（一组不包含任何限定符的资源）。如需了解详细信息，请参阅利用资源提供最佳的设备兼容性部分。

限定符命名规则

以下是一些使用配置限定符名称时需遵循的规则：

• 您可以为单组资源指定多个限定符，并使用短划线分隔。例如，drawable-en-rUS-land 适用于屏幕方向为横向且语言为美式英语的设备。
• 这些限定符必须遵循表 2 中列出的顺序。
  • 错误：drawable-hdpi-port/
  • 正确：drawable-port-hdpi/
• 不得嵌套备用资源目录。例如，您的目录不能为 res/drawable/drawable-en/。
• 值不区分大小写。资源编译器会在处理之前将目录名称转换为小写形式，以避免在不区分大小的文件系统中出现问题。名称中使用的所有大写字母只是为了便于认读。
• 每种限定符类型仅支持一个值。例如，如需针对西班牙语和法语使用相同的可绘制对象文件，则您不能拥有名为 drawable-es-fr/ 的目录，而是需要两个包含相应文件的资源目录，如 drawable-es/ 和 drawable-fr/。但是，您并不需要真的在这两个位置复制文件，而是可以为资源创建别名，如创建别名资源部分所述。

将备用资源保存到以这些限定符命名的目录后，Android 系统会基于当前设备配置自动使用您应用中的资源。在每次请求资源时，Android 系统会检查包含所请求资源文件的备用资源目录，然后寻找最匹配的资源。

如果没有与特定设备配置匹配的备用资源，则 Android 系统会使用相应的默认资源（一组不包含配置限定符的特定类型的资源）。

创建别名资源

如果您想将某一资源用于多种设备配置，但不想以默认资源的形式提供该资源，则无需将同一资源放入多个备用资源目录中。不过，您可以创建备用资源，充当默认资源目录中所保存资源的别名。

注意：并非所有资源都提供能够为另一资源创建别名的机制。特别是，xml/ 目录中的动画资源、菜单资源、原始资源及其他未指定资源均不提供此功能。

例如，假设您有一个应用图标 icon.png，并且需要针对不同语言区域提供该图标的不同版本。但是，加拿大英语和加拿大法语这两种语言区域需使用同一版本。无需将同一图片复制到加拿大英语和加拿大法语的资源目录中。不过，您可以将这两种语言使用的图片保存为除 icon.png 之外的任意名称（例如 icon_ca.png），并将其放入默认的 res/drawable/ 目录中。然后，在 res/drawable-en-rCA/ 和 res/drawable-fr-rCA/ 中创建 icon.xml 文件，使用 <bitmap> 元素引用 icon_ca.png 资源。这样您就可以只保存一个版本的 PNG 文件和两个指向该版本的小型 XML 文件。如需了解详情，请参阅以下部分中的示例。

可绘制对象

如要为现有可绘制对象创建别名，请使用 <drawable> 元素：

<?xml version="1.0" encoding="utf-8"?>
<resources>
    <drawable name="icon">@drawable/icon_ca</drawable>
</resources>

如果您将此文件保存为 icon.xml并放入备用资源目录中（例如 res/values-en-rCA/），那么它将被编译为可作为 R.drawable.icon 引用的资源，但它实际上是 R.drawable.icon_ca 资源（保存在 res/drawable/ 中）的别名。

布局

如要为现有布局创建别名，请使用封装在 <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>

访问应用资源

在应用中提供资源后，您可通过引用其资源 ID 来应用该资源。所有资源 ID 都在您项目的 R 类中进行定义，该类由 aapt 工具自动生成。

编译应用时，aapt 会生成 R 类，其中包含 res/ 目录中所有资源的资源 ID。每种类型的资源都有对应的 R 子类（例如，R.drawable 对应所有可绘制资源）。且相应类型的每个资源都有对应的静态整数（例如 R.drawable.icon）。该整型数就是可用来检索资源的资源 ID。

尽管资源 ID 是在 R 类中指定的，但您不需要在该类中查找资源 ID。资源 ID 始终由以下部分组成：

• 资源类型：每个资源都会被划分到相应的“类型”，例如 string、drawable 和 layout。如需详细了解不同的资源类型，请参阅资源类型概览。
• 资源名称是不带扩展名的文件名，或 XML android:name 属性中的值（如资源是字符串等简单值）。

访问资源的方法有两种：

• 在代码中：使用 R 类的子类中的静态整数，例如：

  R.string.hello

  string 为资源类型，hello 为资源名称。当您提供此格式的资源 ID 时，有许多 Android API 可以访问您的资源。如需了解详情，请参阅在代码中访问资源部分。

• 在 XML 中：使用与 R 类中所定义资源 ID 对应的特殊 XML 语法，例如：

  @string/hello

  string 为资源类型，hello 为资源名称。只要 XML 资源中的某处拥有您在资源中提供的值，您便可在该 XML 资源中使用此语法。如需了解详情，请参阅在 XML 访问资源部分。

在代码中访问资源

您可以将资源 ID 作为方法参数传入，从而在代码中使用资源。例如，您可以设置一个 ImageView，从而借助 setImageResource() 使用 res/drawable/myimage.png 资源：

Kotlin

val imageView = findViewById(R.id.myimageview) as ImageView
imageView.setImageResource(R.drawable.myimage)

Java

ImageView imageView = (ImageView) findViewById(R.id.myimageview);
imageView.setImageResource(R.drawable.myimage);

您还可利用 Resources 中的方法检索个别资源，并且您可通过 getResources() 获得该资源的实例。

语法

以下是在代码中引用资源的语法：

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

• <package_name> 是资源所在的软件包的名称（如果所引用的资源来自您自己的软件包，则不需要）。
• <resource_type> 是资源类型的 R 子类。
• <resource_name> 是不带扩展名的资源文件名，或 XML 元素中的 android:name 属性值（如果资源为简单值）。

如需详细了解各种资源类型及其引用方法，请参阅资源类型概览。

用例

许多方法都接受资源 ID 参数，您可利用 Resources 中的方法检索资源。您可以通过 Context.getResources() 获得 Resources 的实例。

以下是一些在代码中访问资源的示例：

Kotlin

// Load a background for the current screen from a drawable resource.
window.setBackgroundDrawableResource(R.drawable.my_background_image)

// Set the Activity title by getting a string from the Resources object, because
//  this method requires a CharSequence rather than a resource ID.
window.setTitle(resources.getText(R.string.main_title))

// Load a custom layout for the current screen.
setContentView(R.layout.main_screen)

// Set a slide in animation by getting an Animation from the Resources object.
flipper.setInAnimation(AnimationUtils.loadAnimation(this,
        R.anim.hyperspace_in))

// Set the text on a TextView object using a resource ID.
val msgTextView = findViewById(R.id.msg) as TextView
msgTextView.setText(R.string.hello_message)

Java

// Load a background for the current screen from a drawable resource.
getWindow().setBackgroundDrawableResource(R.drawable.my_background_image) ;

// Set the Activity title by getting a string from the Resources object, because
//  this method requires a CharSequence rather than a resource ID.
getWindow().setTitle(getResources().getText(R.string.main_title));

// Load a custom layout for the current screen.
setContentView(R.layout.main_screen);

// Set a slide in animation by getting an Animation from the Resources object.
flipper.setInAnimation(AnimationUtils.loadAnimation(this,
        R.anim.hyperspace_in));

// Set the text on a TextView object using a resource ID.
TextView msgTextView = (TextView) findViewById(R.id.msg);
msgTextView.setText(R.string.hello_message);

注意：切勿手动修改 R.java 文件。aapt 工具会在您编译项目时生成该文件。下次编译时，所有更改都会被覆盖。

在 XML 中访问资源

您可以利用对现有资源的引用，为某些 XML 属性和元素定义值。创建布局文件时，您经常需要这样做，以便为您的 widget 提供字符串和图片。

例如，如果您为布局添加 Button，请为按钮文本使用字符串资源：

<Button
    android:layout_width="fill_parent"
    android:layout_height="wrap_content"
    android:text="@string/submit" />

语法

以下是在 XML 资源中引用资源的语法：

@[<package_name>:]<resource_type>/<resource_name>

• <package_name> 是资源所在软件包的名称（如果所引用的资源来自同一软件包，则不需要）。
• <resource_type> 是资源类型的 R 子类。
• <resource_name> 是不带扩展名的资源文件名，或 XML 元素中的 android:name 属性值（如果资源为简单值）。

如需详细了解各种资源类型及其引用方法，请参阅资源类型概览。

用例

在某些情况下，您必须使用资源作为 XML 中的值（例如，针对 widget 应用可绘制图片），但您也可在 XML 中接受简单值的任何位置使用资源。例如，如果您拥有以下资源文件，其中包括一个颜色资源和一个字符串资源：

<?xml version="1.0" encoding="utf-8"?>
<resources>
   <color name="opaque_red">#f00</color>
   <string name="hello">Hello!</string>
</resources>

您可以在以下布局文件中使用这些资源来设置文本颜色和文本字符串：

<?xml version="1.0" encoding="utf-8"?>
<EditText xmlns:android="http://schemas.android.com/apk/res/android"
    android:layout_width="fill_parent"
    android:layout_height="fill_parent"
    android:textColor="@color/opaque_red"
    android:text="@string/hello" />

在这种情况下，您无需在资源引用中指定软件包名称，因为资源来自您自己的软件包。如需引用系统资源，您需要添加软件包名称，如以下示例所示：

<?xml version="1.0" encoding="utf-8"?>
<EditText xmlns:android="http://schemas.android.com/apk/res/android"
    android:layout_width="fill_parent"
    android:layout_height="fill_parent"
    android:textColor="@android:color/secondary_text_dark"
    android:text="@string/hello" />

注意：请始终使用字符串资源，以便将您的应用本地化为其他语言。如需了解如何创建备用资源（例如本地化字符串），请参阅提供备用资源。如需查看将应用本地化为其他语言的完整指南，请参阅本地化您的应用。

您甚至可以在 XML 中使用资源创建别名。例如，您可以创建一个可绘制资源，将其作为另一个可绘制资源的别名：

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

这听起来没有必要，但对使用备用资源会很有帮助。如需了解详情，请参阅创建别名资源部分。

引用样式属性

利用样式属性资源，您可以在当前应用的主题中引用属性的值。通过引用样式属性，您可以通过设置界面元素的样式，使其与当前主题提供的标准变体相匹配，从而自定义界面元素的外观，而不是提供硬编码的值。引用样式属性实际上意味着，“在当前主题中使用此属性定义的样式。”

如要引用样式属性，名称语法与常规资源格式几乎完全相同，区别在于您需要将 "@" 符号 (@) 改为问号 (?)，并且资源类型部分为可选项。因此，引用语法如下所示：

?[<package_name>:][<resource_type>/]<resource_name>

例如，以下代码展示了如何通过引用属性来设置文本颜色设，使其匹配系统主题背景的次要文本颜色：

<EditText id="text"
    android:layout_width="fill_parent"
    android:layout_height="wrap_content"
    android:textColor="?android:textColorSecondary"
    android:text="@string/hello_world" />

在以上代码中，android:textColor 属性用于指定当前主题中某个样式属性的名称。Android 现在会将应用于 android:textColorSecondary 样式属性的值用作此 widget 中 android:textColor 的值。由于系统资源工具知道此环境中肯定存在某个属性资源，因此您无需显式声明类型（类型为 ?android:attr/textColorSecondary）。您可以将 attr 类型排除在外。

访问原始文件

尽管并不常见，但您可能会需要访问原始文件和目录。如果确有需要，将文件保存在 res/ 中并没有用，因为从 res/ 读取资源的唯一方法是使用资源 ID。您可以改为将资源保存在 assets/ 目录中。

保存在 assets/ 目录中的文件没有资源 ID，因此您无法通过 R 类或在 XML 资源中引用它们。您可以改为采用类似常见文件系统的方式查询 assets/ 目录中的文件，并利用 AssetManager 读取原始数据。

不过，如果您只需要能够读取原始数据（例如视频文件或音频文件），则可将文件保存在 res/raw/ 目录中，并利用 openRawResource() 读取字节流。

访问平台资源

Android 包含许多标准资源，例如样式、主题背景和布局。如要访问这些资源，请通过 android 软件包名称限定您的资源引用。例如，您可以将 Android 提供的布局资源用于 ListAdapter 中的列表项：

Kotlin

listAdapter = ArrayAdapter(this, android.R.layout.simple_list_item_1, myarray)

Java

setListAdapter(new ArrayAdapter<String>(this, android.R.layout.simple_list_item_1, myarray));

在上例中，simple_list_item_1 是平台为 ListView 中的项所定义的布局资源。您可以使用该资源，无需自行创建列表项布局。

利用资源提供最佳的设备兼容性

为使应用支持多种设备配置，请务必为应用使用的每种资源类型提供默认资源，这一点非常重要。

例如，如果应用支持多种语言，请始终包含不带语言和区域限定符的 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. 排除不包含此限定符的资源目录。在本例中，系统接下来会排除所有不包含语言限定符的目录：

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

   例外：如果涉及的限定符为屏幕像素密度，则 Android 会选择与设备屏幕密度最匹配的选项。一般而言，Android 会优先选择将较大的原始图片缩小，而不是将较小的原始图片放大。如需了解详情，请参阅屏幕兼容性概览。

5. 重复第 2 步、第 3 步和第 4 步，直到仅剩一个目录为止。在本例中，屏幕方向是下一个判断是否匹配的限定符。因此，没有指定屏幕方向的资源会被排除：

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

   剩下的目录是 drawable-en-port。

尽管系统会对所请求的每个资源执行此流程，但是其仍会对某些方面进行优化。例如，已知设备配置后，系统会排除可能永远无法匹配的备用资源。例如，如果配置语言是英语，那么语言限定符设置为非英语的所有资源目录都不会包含在接受检查的资源池中（不过，系统仍会检查不包含语言限定符的资源目录）。

在根据屏幕尺寸限定符选择资源时，如果没有更匹配的资源，系统将使用针对较小屏幕（小于当前屏幕）设计的资源。例如，大尺寸屏幕在必要时将使用适用于标准尺寸屏幕的资源。

但是，如果唯一可用的资源大于当前屏幕，系统将不会使用这些资源，而且如果没有其他资源与设备配置匹配，您的应用会崩溃。例如，如果所有布局资源均使用 xlarge 限定符进行标记，但设备的屏幕是标准尺寸，就会发生这种情况。

注意：限定符的优先级（参见表 2）比与设备完全匹配的限定符数量更加重要。在上述示例第 4 步中，列表剩下的最后选项包括三个与设备完全匹配的限定符（屏幕方向、触摸屏类型和输入法），而 drawable-en 只有一个匹配参数（语言）。但是，语言的优先级高于其他三个限定符，因此系统会排除 drawable-port-notouch-12key。