应用资源概览

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

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

外部化应用资源后，您便可使用在项目 R 类中生成的资源 ID 来访问这些资源。本文档会介绍如何对 Android 项

分组资源类型

您应将各类资源放入项目 res/ 目录的特定子目录中。例如，以下是一个简单项目的文件层次结构：

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

如此示例所示，res/ 目录包含所有资源（在子目录中）：一个图像资源、两个布局资源、启动器图标的 mipmap/ 目录以及一个字符串资源文件。资源目录名称非常重要，具体说明请见表 1。

**请注意：**如需了解有关使用 mipmap 文件夹的详细信息，请参阅管理项目概览。意：**切勿将资源文件直接保存在 res/ 目录内，因为这样会造成编译错误。

如需了解有关特定资源类型的详细信息，请参阅资源类型文档。

在表 1 定义的子目录中，保存的资源为“默认”资源。换言之，这些资源定义应用的默认设计和内容。然而，不同类型的 Android 设备可能需要不同类型的资源。例如，如果设备屏幕比标准屏幕大，则应提供不同的布局资源，从而充分利用额外的屏幕空间。或者，如果设备的语言设置不同，则应提供不同的字符串资源，以便将界面中的文本转换为其他语言。如要为不同设备配置提供这些不同资源，除默认资源以外，您还需提供备用资源。

提供备用资源

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

图 1. 两种不同的设备，均使用不同的布局资源。

为一组资源指定配置特定的备用资源：

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

Android 支持若干配置限定符，您可以通过使用短划线分隔每个限定符，从而向一个目录名称添加多个限定符。表 2 按优先级顺序列出了有效的配置限定符；如果对资源目录使用多个限定符，则必须按照表中所列顺序将其添加到目录名称中。

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

限定符命名规则

以下是一些关于使用配置限定符名称的规则：

• 您可以为单组资源指定多个限定符，并使用短划线分隔。例如，drawable-en-rUS-land 适用于屏幕方向为横向的美国英语设备。
• 这些限定符必须遵循中列出的顺序。例如：
  • 错误：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/ 目录中。然后，在 res/drawable-en-rCA/ 和 res/drawable-fr-rCA/ 中创建 icon.xml 文件，使用 <bitmap> 元素引用 icon_ca.png 资源。这样，您只需存储 PNG 文件的一个版本和两个指向该版本的小型 XML 文件。（XML 文件示例如下。）

可绘制对象

如要创建指向现有可绘制对象的别名，请使用 <drawable> 元素。例如：

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

如果将此文件保存为 drawables.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 资源：

val imageView = findViewById(R.id.myimageview) as ImageView
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 的实例。

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

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

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

在 XML 中访问资源

您可以使用对现有资源的引用，为某些 XML 属性和元素定义值。创建布局文件时，为给您的微件提供字符串和图像，您会经常这样做。

例如，如果您为布局添加 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 中的值（例如，对微件应用可绘制图像），但您也可在 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" />

这听起来多余，但对使用备用资源可能很有帮助。阅读更多关于创建别名资源的内容。

引用样式属性

利用样式属性资源，您可以在当前应用的主题背景中引用某个属性的值。借助引用样式属性，在自定义界面元素的外观时，您无需采用提供硬编码值这种方式，您可以通过为其设置样式，以匹配当前主题背景提供的标准变体来达成目的。引用样式属性的实质作用是，“在当前主题背景中使用此属性定义的样式”。

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

?[<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 样式属性的值用作此微件中 android:textColor 的值。由于系统资源工具知道此环境中肯定存在某个属性资源，因此您无需显式声明类型（类型应为 ?android:attr/textColorSecondary）— 您可以将 attr 类型排除在外。

访问原始文件

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

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

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

访问平台资源

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

listAdapter = ArrayAdapter(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。

尽管系统会对所请求的每个资源执行此程序，但是其仍会对某些方面做进一步优化。例如，已知设备配置后，系统会淘汰可能永远无法匹配的备用资源。比如，如果配置语言是英语（“en”），则系统绝不会将语言限定符设置为非英语的任何资源目录加入选中的资源池（不过，仍会将不带语言限定符的资源目录加入该池）。

在根据屏幕尺寸限定符选择资源时，如果没有更好的匹配资源，则系统将使用专为小于当前屏幕的屏幕而设计的资源（例如，必要时，大尺寸屏幕将使用标准尺寸的屏幕资源）。但是，如果唯一可用的资源大于当前屏幕，则系统不会使用这些资源，并且如果没有其他资源与设备配置匹配，应用将会崩溃（例如，如果所有布局资源均用 xlarge 限定符标记，但设备是标准尺寸的屏幕）。