应用资源概述

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

始终将应用资源（例如图像和字符串）从代码中外部化，以便您可以独立维护它们。此外，还可以通过将它们分组到特殊命名的资源目录中，为特定设备配置提供替代资源。运行时，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/ 目录中。然后在 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>

如果你将此文件保存为备选资源目录（例如 res/values-en-rCA/）中的 icon.xml，则将其编译成一个可以作为 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 是资源名称。许多 Android API 在你提供此格式的资源 ID 时都可以访问你的资源。有关更多信息，请参阅在代码中访问资源 部分。

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

  @string/hello

  string 是资源类型，hello 是资源名称。你可以在需要提供资源中值的 XML 资源中的任何位置使用此语法。有关更多信息，请参阅从 XML 访问资源 部分。

在代码中访问资源

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

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() 获取其实例。

语法

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

[<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 属性和元素的值。在创建布局文件时，通常会这样做，以便为你的 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" />

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

引用样式属性

样式属性资源允许您引用当前应用主题中属性的值。引用样式属性允许您通过将 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. 消除与设备配置相矛盾的资源文件。

   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. 任何资源目录是否包含此限定符？
   • 如果不是，请返回步骤二并查看下一个限定符。在此示例中，答案为“否”，直到达到语言限定符。
   • 如果是，请继续执行步骤四。
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 被消除。