雖然 Jetpack Compose 會直接在 Kotlin 中處理 UI 設計階段工具,但 tools: 命名空間對於專案層級的設定仍然至關重要。標準 Android XML 檔案 (例如 AndroidManifest.xml 和 res/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" />
詳情請參閱「縮減資源」一節。