应用资源概览

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

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

如果你将此文件保存为备用资源目录中的 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 作为方法参数传递，在代码中使用资源。例如，你可以使用 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 属性和元素的值。你通常在创建布局文件时这样做，为你的界面小部件提供字符串和图片。

例如，如果你在布局中添加一个 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 元素来使其与当前主题提供的标准变体匹配，而不是提供硬编码值，从而自定义其外观。引用样式属性实质上是说：“使用当前主题中由该属性定义的样式。”

要引用样式属性，名称语法几乎与普通资源格式相同，但不是使用“@”符号 (@)，而是使用问号 (?)。资源类型部分是可选的。因此，引用语法如下：

?[<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 被排除。