工具属性参考

虽然 Jetpack Compose 直接在 Kotlin 中处理界面设计时工具，但 tools: 命名空间对于项目级配置仍然至关重要。标准 Android XML 文件（如 AndroidManifest.xml 和 res/raw/keep.xml）使用 tools: 属性来管理 lint 警告并配置资源缩减器。

在您构建应用时，构建工具会移除这些属性，以免它们会对 APK 大小或运行时行为产生影响。

若要使用这些属性，请将 tools 命名空间添加到各个目标 XML 文件的根元素中，如下所示：

<RootTag xmlns:android="http://schemas.android.com/apk/res/android"
    xmlns:tools="http://schemas.android.com/tools" >

错误处理属性

以下属性可帮助抑制 lint 警告消息：

tools:ignore

适用于：任何元素

使用者：lint

此属性用于接受您希望工具针对相应元素或其任何子元素忽略的 lint 问题 ID 的英文逗号分隔列表。

例如，您可以告知工具忽略 MissingTranslation 错误：

<string name="show_all_apps" tools:ignore="MissingTranslation">All</string>

tools:targetApi

适用于：任何元素

使用者：lint

此属性的工作方式与 Java 代码中的 @TargetApi 注释 或 Kotlin 代码中的 @RequiresApi 注释相同。通过它，您可以指定支持该元素的 API 级别（指定为整数或代号）。

它会告知 lint 工具，您认为该元素（及任何子元素）将只能在指定的 API 级别或更高级别中使用。这样，如果该元素或其属性在您指定为 minSdkVersion 的 API 级别中不可用，lint 将不会向您发出警告。

例如，您可能会使用此属性，因为您在AndroidManifest.xml中声明了一个 <service>，该服务使用仅在 API 级别 34 及更高级别中提供的前台服务类型 ，但项目的minSdkVersion 较低：

<service
    android:name=".playback.MediaPlaybackService"
    android:foregroundServiceType="mediaPlayback"
    xmlns:tools="http://schemas.android.com/tools"
    tools:targetApi="34" />

tools:locale

适用于 <resources>

使用者：lint、Android Studio 编辑器

此属性用于让工具知道给定 <resources> 元素中各项资源的默认语言/语言区域，以免拼写检查工具发出警告。 否则，该工具会假定语言为英语。

值必须是有效的语言区域限定符。

例如，您可将此属性添加到默认 values/strings.xml 文件中，以表明用于默认字符串的语言是西班牙语而非英语：

<resources xmlns:tools="http://schemas.android.com/tools"
    tools:locale="es">

资源缩减属性

通过以下属性，您不仅可启用严格引用检查，还可声明使用资源缩减时是保留还是舍弃某些资源。

如需启用资源缩减，请将 build.gradle 文件中的 shrinkResources 属性（若涉及代码缩减，则还包括 minifyEnabled）设为 true。

例如：

Groovy

android {
    ...
    buildTypes {
        release {
            shrinkResources true
            minifyEnabled true
            proguardFiles getDefaultProguardFile('proguard-android.txt'),
                    'proguard-rules.pro'
        }
    }
}

Kotlin

android {
    ...
    buildTypes {
        getByName("release") {
            isShrinkResources = true
            isMinifyEnabled = true
            proguardFiles(
                getDefaultProguardFile("proguard-android.txt"),
                "proguard-rules.pro"
            )
        }
    }
}

tools:shrinkMode

适用于：<resources>

使用者：具有资源缩减功能的构建工具

通过此属性，您可指定构建工具是否应使用以下各项：

  • 安全模式：保留所有明确引用的资源以及可能会通过调用 Resources.getIdentifier() 动态引用的资源。
  • 严格模式：仅保留代码或其他资源中明确引用的资源。

默认使用“安全模式”(shrinkMode="safe")。若要改用“严格模式”，请将 shrinkMode="strict" 添加到 <resources> 标记，如下所示：

<?xml version="1.0" encoding="utf-8"?>
<resources xmlns:tools="http://schemas.android.com/tools"
    tools:shrinkMode="strict" />

启用“严格模式”后，您可能需要使用 tools:keep 来保留已移除但您实际上需要的资源，并使用 tools:discard 来明确移除更多资源。

如需了解详情，请参阅缩减资源。

tools:keep

适用于：<resources>

使用者：具有资源缩减功能的构建工具

使用资源缩减功能移除不使用的资源时，您可以通过此属性指定要保留的资源，通常的原因是相应资源在运行时以间接方式引用，例如通过将动态生成的资源名称传递给 Resources.getIdentifier()。

要使用，请在资源目录中创建一个 XML 文件（例如， res/raw/keep.xml），其中包含 <resources> 标记 ，并将要保留在 tools:keep 属性中的各项资源指定为 逗号分隔列表。您可以使用星号字符作为通配符。

例如：

<?xml version="1.0" encoding="utf-8"?>
<resources xmlns:tools="http://schemas.android.com/tools"
    tools:keep="@layout/used_1,@layout/used_2,@layout/*_3" />

如需了解详情，请参阅缩减资源。

tools:discard

适用于 <resources>

使用者：具有资源缩减功能的构建工具

使用资源缩减功能删除不使用的资源时，您可以通过此属性指定要手动舍弃的资源，通常的原因是相应资源被引用的方式不会影响您的应用，或者 Gradle 插件错误地推导出相应资源被引用了。

要使用，请在资源目录中创建一个 XML 文件（例如， res/raw/keep.xml），其中包含 <resources> 标记 ，并将要舍弃在 tools:discard 属性中的各项资源指定为 逗号分隔列表。您可以使用星号字符作为通配符。

例如：

<?xml version="1.0" encoding="utf-8"?>
<resources xmlns:tools="http://schemas.android.com/tools"
    tools:discard="@layout/unused_1" />

如需了解详情，请参阅 缩减资源。

其他资源

查看内容