应用资源概述

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

始终将应用资源（例如图像和字符串）从代码中外部化，以便您可以独立维护它们。另外，通过将资源分组到特殊命名的资源目录中，为特定设备配置提供替代资源。在运行时，Android 将根据当前配置使用相应的资源。例如，您可能希望根据屏幕尺寸提供不同的 UI 布局，或根据语言设置提供不同的字符串。

将应用资源外部化后，可以使用在项目 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/ 目录中支持的资源目录。

注意： 切勿将资源文件直接保存到 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. 配置限定符名称。

注意：并非所有版本的 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/ 目录中。然后创建一个 icon.xml 文件，放在 res/drawable-en-rCA/ 和 res/drawable-fr-rCA/ 中，使用 <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/ 中。

布局

要创建现有布局的别名，请使用 <include> 元素，将其包装在 <merge> 中

<?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。

虽然 R 类是指定资源 ID 的位置，但您无需查看该类来发现资源 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 访问资源 部分。

在代码中访问资源

您可以通过将资源 ID 作为方法参数传递来在代码中使用资源。例如，可以使用 ImageView 设置 res/drawable/myimage.png 资源，方法是使用 setImageResource()

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

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

您还可以使用 Resources 中的方法检索单个资源，您可以使用 getResources() 获取 Resources 的实例。

语法

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

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

// 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 属性和元素的值。在创建布局文件时，通常这样做，以便为小部件提供字符串和图像。

例如，如果您将 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" />

这听起来很冗余，但在使用替代资源时非常有用。有关更多信息，请参阅有关 创建别名资源 的部分。

引用样式属性

样式属性资源使您可以引用当前应用主题中属性的值。引用样式属性使您可以通过对 UI 元素进行样式化以匹配当前主题提供的标准变体来自定义 UI 元素的外观，而不是提供硬编码值。引用样式属性实际上表示“使用当前主题中此属性定义的样式”。

要引用样式属性，名称语法与普通资源格式几乎相同，但使用问号 (?) 而不是“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)

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. 消除与设备配置相矛盾的资源文件。

   由于与 en-GB 区域设置相矛盾，因此 drawable-fr-rCA/ 目录被消除。

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

   例外：屏幕像素密度是不会因矛盾而被消除的唯一限定符。即使设备的屏幕密度为 hdpi，drawable-port-ldpi/ 也不会被消除，因为此时每种屏幕密度都被视为匹配。有关信息，请参阅 屏幕兼容性概述。

2. 在列表中找到下一个优先级最高的限定符 (表格 2)。（从 MCC 开始。）
3. 任何资源目录是否包含此限定符？
   • 如果否，请返回步骤二并查看下一个限定符。在此示例中，答案为“否”，直到到达语言限定符。
   • 如果是，请继续执行步骤四。
4. 消除不包含此限定符的资源目录。在此示例中，系统接下来消除所有不包含语言限定符的目录

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

   例外：如果所讨论的限定符是屏幕像素密度，Android 会选择最接近设备屏幕密度的选项。一般来说，Android 更倾向于将较大的原始图像缩小，而不是将较小的原始图像放大。有关更多信息，请参阅 屏幕兼容性概述。

5. 重复步骤二、三和四，直到只剩下一个目录。在此示例中，屏幕方向是下一个存在任何匹配项的限定符。因此，不指定屏幕方向的资源将被消除

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

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

尽管此过程针对请求的每个资源都执行，但系统会对其某些方面进行优化。一种优化是，一旦知道设备配置，它可能会消除永远不会匹配的备用资源。例如，如果配置语言是英语，那么任何语言限定符设置为非英语的资源目录都不会包含在要检查的资源池中（尽管没有语言限定符的资源目录仍然包含在内）。

根据屏幕大小限定符选择资源时，如果不存在与当前屏幕更好地匹配的资源，系统会使用为小于当前屏幕的屏幕设计的资源。例如，大型屏幕会根据需要使用普通大小屏幕的资源。

但是，如果唯一可用的资源大于当前屏幕，则系统不会使用它们，如果没有任何其他资源与设备配置匹配，您的应用将崩溃。例如，如果所有布局资源都标记为 xlarge 限定符，但设备是普通大小屏幕，就会发生这种情况。

注意：限定符的优先级（在 表格 2 中）比与设备完全匹配的限定符数量更重要。在上一个示例中，在步骤四中，列表中的最后一个选项包含三个与设备完全匹配的限定符（方向、触摸屏类型和输入方法），而 drawable-en 只有一个与之匹配的参数（语言）。但是，语言的优先级高于这些其他限定符，因此 drawable-port-notouch-12key 被消除。