工具屬性參考資料

雖然 Jetpack Compose 會直接在 Kotlin 中處理 UI 設計階段工具,但 tools: 命名空間對於專案層級的設定仍然至關重要。標準 Android XML 檔案 (例如 AndroidManifest.xmlres/raw/keep.xml) 會使用 tools: 屬性管理 Lint 警告,並設定資源縮減器。

當您建構應用程式時,建構工具會移除這些屬性,因此不會對 APK 大小或執行階段行為造成任何影響。

如要在 XML 檔案中使用這些屬性,請在各 XML 檔案的根元素中新增 tools 命名空間,如下所示:

<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")。如要改用嚴格模式,請在 <resources> 標記中加入 shrinkMode="strict",如下所示:

<?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()

如要使用,請在資源目錄中建立包含 <resources> 標記的 XML 檔案 (例如 res/raw/keep.xml),並以半形逗號分隔的清單指定要在 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 外掛程式誤將資源視為已參照。

如要使用,請在資源目錄中建立包含 <resources> 標記的 XML 檔案 (例如 res/raw/keep.xml),並以半形逗號分隔的清單指定要在 tools:discard 屬性中捨棄的各項資源。您可以使用星號字元做為萬用字元。

例如:

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

詳情請參閱「縮減資源」一節。

其他資源

Views content