应用资源概览

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

务必将图像和字符串等应用资源从代码中外部化，以便您可以独立维护它们。此外，通过将它们分组到专门命名的资源目录中，为特定的设备配置提供替代资源。在运行时，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/ 目录下支持的资源目录。

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

如需了解有关各个资源类型的更多信息，请参阅资源类型概览。

您保存在表 1 中定义的子目录中的资源是您的默认资源。也就是说，这些资源定义了您应用的默认设计和内容。但是，不同类型的 Android 设备可能需要不同类型的资源。

例如，您可以为屏幕大于正常尺寸的设备提供不同的布局资源，以利用额外的屏幕空间。您还可以提供不同的字符串资源，根据设备的语言设置翻译用户界面中的文本。要为不同的设备配置提供这些不同的资源，您需要在默认资源之外提供替代资源。

提供替代资源

大多数应用提供替代资源来支持特定的设备配置。例如，为不同的屏幕密度包含替代 drawable 资源，为不同的语言包含替代字符串资源。在运行时，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 修饰符表示该目录中的资源适用于高密度屏幕设备。这些 drawable 目录中的图像针对特定的屏幕密度进行了尺寸调整，但文件名完全相同。这样，您用于引用 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 文件，则不能使用名为 drawable-es-fr/ 的目录。相反，您需要两个资源目录，例如 drawable-es/ 和 drawable-fr/，它们包含适当的文件。但是，您无需在两个位置实际复制文件。相反，您可以创建资源的别名，如创建别名资源部分所述。

将替代资源保存到使用这些修饰符命名的目录中后，Android 会根据当前设备配置自动在您的应用中应用资源。每次请求资源时，Android 都会检查包含请求资源文件的替代资源目录，然后找到最匹配的资源。

如果没有与特定设备配置匹配的替代资源，则 Android 会使用相应的默认资源——即不包含配置修饰符的特定资源类型的资源集。

创建别名资源

当您有一个希望用于多种设备配置但又不希望将其作为默认资源的资源时，无需将同一资源放在多个替代资源目录中。相反，您可以创建替代资源，该资源充当保存在默认资源目录中的资源的别名。

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

例如，假设您有一个应用图标 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

要创建现有 drawable 的别名，请使用 <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，但它实际上是保存在 res/drawable/ 中的 R.drawable.icon_ca 资源的别名。

布局

要创建现有布局的别名，请使用嵌套在 <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 子类，例如所有 drawable 资源的 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 中的方法检索单个资源，您可以通过 Context.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 中使用资源来表示某个值，例如将 drawable 图像应用于微件，但您也可以在 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 中使用资源来创建别名。例如，您可以创建一个 drawable 资源，该资源是另一个 drawable 资源的别名

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