Android 元件匯入 (Imports)

在撰寫 Kotlin / Android 程式時，最常遇到的第一個問題通常不是語法，而是「這個元件要去哪裡找？」。當你複製貼上一段程式碼，發現滿滿的紅字錯誤，這通常代表你缺少了 import 敘述。

為什麼需要 Import？

Android 框架非常的龐大，包含了數千個類別 (Class) 和函式。為了避免名稱衝突並保持組織條理，這些類別被分門別類放在不同的 套件 (Package) 中。

例如，我們常用的 Text 元件，在 Android 中其實有好幾個不同的版本：

  1. androidx.compose.material3.Text (Material 3 設計系統)
  2. androidx.compose.material.Text (舊版 Material 2)
  3. org.w3c.dom.Text (XML 解析用的，跟 UI 無關)

如果你的程式碼中只寫了 Text("Hello")，編譯器會因為不知道你想用哪一個 Text 而報錯。因此，我們必須透過 import 關鍵字來明確告訴編譯器：「我要用的是哪一個套件裡的 Text」。

// 明確匯入 Material 3 的 Text
import androidx.compose.material3.Text

@Composable
fun Greeting() {
    Text("Hello Android")
}

IDE 快速修正 (Quick Fix) - 最重要的一招

身為開發者，你不需要背誦每個元件的完整 package路徑。Android Studio 提供了非常強大的自動匯入功能。

當你看到程式碼出現紅字，代表該元件尚未匯入或無法識別。

如何自動匯入？

  1. 將輸入游標移動到報錯的紅字元件名稱上 (例如 Text)。
  2. 按下快速鍵：
    • Windows / Linux: Alt + Enter
    • macOS: Option + Enter
  3. IDE 會彈出選單，通常第一個選項就是 Import class。按下 Enter 即可。
如果有多個同名的元件可供選擇 (例如前面提到的多種 Text)，IDE 會列出清單讓你選擇。這時候就需要根據你的專案需求 (例如你是否正在使用 Material 3) 來選擇正確的選項。

自動整理 Imports

隨著開發進行，我們可能會刪除一些沒用到的程式碼，導致留下多餘的 import 敘述 (通常會變成灰色)。你可以使用快捷鍵一次清理它們：

  • Windows / Linux: Ctrl + Alt + O (Optimize Imports)
  • macOS: Ctrl + Option + O

如何知道要匯入哪一個？Package 常見規則

當 IDE 跳出多個選項讓你選擇時，新手往往會感到困惑。以下是一些判斷的依據：

1. 辨識 View 系統 vs Jetpack Compose

  • View 系統 (傳統 XML): 元件通常位於 android.widget.* 或 android.view.*。
    • 例如：android.widget.TextView, android.widget.Button
  • Jetpack Compose (現代 UI): 元件通常位於 androidx.compose.*。
    • 例如：androidx.compose.material3.Button, androidx.compose.foundation.Image

2. Material Design 版本

目前 Android 推薦使用 Material 3。

  • Material 3: androidx.compose.material3.* (首選)
  • Material 2: androidx.compose.material.* (舊專案可能還在用)

如果在選單中看到這兩個，優先選擇 material3 (除非你的專案確定是舊版)。

3. Java/Kotlin 基礎類別

有時候你會看到來自 java.util.* 或 kotlin.collections.* 的選項 (例如 List)。

  • 在 Kotlin 專案中，通常優先選擇 Kotlin 的標準函式庫 (通常不需要顯式 import，或者 IDE 會自動處理好)。
  • 避免誤選到 java.awt.* 或 javax.swing.*，這些是桌機版 Java GUI 的套件，Android 不支援。

常見問題與解決

1. 按了 Alt/Option + Enter 卻沒有 Import 選項？

這通常代表 IDE 找不到 這個元件。可能原因：

  • 拼字錯誤: 檢查是否有打錯字。
  • 缺少依賴 (Dependency): 你可能想用的函式庫還沒加到 build.gradle.kts 中。例如想用 Coil 載入圖片，但忘記加 implementation 依賴，這時 IDE 就找不到 AsyncImage。

2. 也是紅字，但 Import 也沒用？

有時候紅字不一定是缺 Import，可能是：

  • 型別錯誤: 傳入參數的型別不對。
  • 版本不相容: 使用了該版本 SDK 還不支援的 API。
  • 缺少參數: 必填的參數沒有填。

這時除了 Import，還要仔細看 IDE 顯示的錯誤訊息 (將滑鼠懸停在紅字上)。