快速入門

透過集合功能整理內容 你可以依據偏好儲存及分類內容。

為了獲得最佳的 Compose 開發體驗,請下載並安裝 Android Studio。Android Studio 有許多智慧型編輯器功能,不但有新的專案範本,還能在開發時立即預覽 Compose UI 和動畫。

取得 Android Studio

請依照以下操作說明,建立新的 Compose 應用程式專案、為現有應用程式專案設定 Compose 或匯入以 Compose 編寫的範例應用程式。

建立可支援 Compose 的新應用程式

如要建立預設支援 Compose 的新專案,Android Studio 已準備多種專案範本,可協助您快速上手。如要建立已正確設定 Compose 的新專案,請按照以下步驟操作:

  1. 如果您位於「Welcome to Android Studio」視窗,請按一下「Start a new Android Studio project」。如果您已開啟 Android Studio 專案,請從選單列中依序選取「File」>「New」>「New Project」
  2. 在「Select a Project Template」視窗中選取「Empty Compose Activity」,然後按一下「Next」
  3. 在「Configure your project」視窗中執行以下操作:
    1. 按照平常作業方式分別設定「Name」、「Package name」和「Save location」。請注意,在「Language」下拉式選單中,「Kotlin」是唯一可用的選項,因為 Jetpack Compose 只能使用以 Kotlin 編寫的類別。
    2. 在「Minimum API level」下拉式選單中,選取 21 以上的 API 級別。
  4. 按一下「Finish」(完成)

您現在可以開始使用 Jetpack Compose 開發應用程式了。為了協助您開始使用並學習工具包的使用方式,建議您從「Jetpack Compose 教學課程」開始著手。

為現有應用程式設定 Compose

如要開始使用 Compose,您必須先在專案中加入一些建構設定。請在應用程式的 build.gradle 檔案中加入以下定義:

Groovy

android {
    buildFeatures {
        compose true
    }

    composeOptions {
        kotlinCompilerExtensionVersion = "1.3.2"
    }
}

Kotlin

android {
    buildFeatures {
        compose = true
    }

    composeOptions {
        kotlinCompilerExtensionVersion = "1.3.2"
    }
}

注意事項:

  • 在 Android 的 BuildFeatures 區塊中,將 compose 旗標設為 true 即可啟用 Compose 功能。
  • ComposeOptions 區塊中定義的 Kotlin Compiler 擴充功能版本必須搭配特定的 Kotlin 版本。請務必查閱相容性對應清單,並選擇與專案的 Kotlin 版本相符的程式庫版本。

此外,您也必須將以下區塊中的 Compose BOM 和所需 Compose 程式庫依附元件子集加入依附元件:

Groovy

dependencies {

    def composeBom = platform('androidx.compose:compose-bom:2022.10.00')
    implementation composeBom
    androidTestImplementation composeBom

    // Choose one of the following:
    // Material Design 3
    implementation 'androidx.compose.material3:material3'
    // or Material Design 2
    implementation 'androidx.compose.material:material'
    // or skip Material Design and build directly on top of foundational components
    implementation 'androidx.compose.foundation:foundation'
    // or only import the main APIs for the underlying toolkit systems,
    // such as input and measurement/layout
    implementation 'androidx.compose.ui:ui'

    // Android Studio Preview support
    implementation 'androidx.compose.ui:ui-tooling-preview'
    debugImplementation 'androidx.compose.ui:ui-tooling'

    // UI Tests
    androidTestImplementation 'androidx.compose.ui:ui-test-junit4'
    debugImplementation 'androidx.compose.ui:ui-test-manifest'

    // Optional - Included automatically by material, only add when you need
    // the icons but not the material library (e.g. when using Material3 or a
    // custom design system based on Foundation)
    implementation 'androidx.compose.material:material-icons-core'
    // Optional - Add full set of material icons
    implementation 'androidx.compose.material:material-icons-extended'
    // Optional - Add window size utils
    implementation 'androidx.compose.material3:material3-window-size-class'

    // Optional - Integration with activities
    implementation 'androidx.activity:activity-compose:1.5.1'
    // Optional - Integration with ViewModels
    implementation 'androidx.lifecycle:lifecycle-viewmodel-compose:2.5.1'
    // Optional - Integration with LiveData
    implementation 'androidx.compose.runtime:runtime-livedata'
    // Optional - Integration with RxJava
    implementation 'androidx.compose.runtime:runtime-rxjava2'

}

Kotlin

dependencies {

    val composeBom = platform("androidx.compose:compose-bom:2022.10.00")
    implementation composeBom
    androidTestImplementation composeBom

    // Choose one of the following:
    // Material Design 3
    implementation("androidx.compose.material3:material3")
    // or Material Design 2
    implementation("androidx.compose.material:material")
    // or skip Material Design and build directly on top of foundational components
    implementation("androidx.compose.foundation:foundation")
    // or only import the main APIs for the underlying toolkit systems,
    // such as input and measurement/layout
    implementation("androidx.compose.ui:ui")

    // Android Studio Preview support
    implementation("androidx.compose.ui:ui-tooling-preview")
    debugImplementation("androidx.compose.ui:ui-tooling")

    // UI Tests
    androidTestImplementation("androidx.compose.ui:ui-test-junit4")
    debugImplementation("androidx.compose.ui:ui-test-manifest")

    // Optional - Included automatically by material, only add when you need
    // the icons but not the material library (e.g. when using Material3 or a
    // custom design system based on Foundation)
    implementation("androidx.compose.material:material-icons-core")
    // Optional - Add full set of material icons
    implementation("androidx.compose.material:material-icons-extended")
    // Optional - Add window size utils
    implementation("androidx.compose.material3:material3-window-size-class")

    // Optional - Integration with activities
    implementation("androidx.activity:activity-compose:1.5.1")
    // Optional - Integration with ViewModels
    implementation("androidx.lifecycle:lifecycle-viewmodel-compose:2.5.1")
    // Optional - Integration with LiveData
    implementation("androidx.compose.runtime:runtime-livedata")
    // Optional - Integration with RxJava
    implementation("androidx.compose.runtime:runtime-rxjava2")

}

試用 Jetpack Compose 範例應用程式

如要實驗 Jetpack Compose 的功能,最快的做法是試用 GitHub 代管的 Jetpack Compose 範例應用程式。如要從 Android Studio 匯入範例應用程式專案,請按照以下步驟操作:

  1. 如果您位於「Welcome to Android Studio」視窗,請選取「Import an Android code sample」。如果您已開啟 Android Studio 專案,請依序點選選單列中的「File」>「New」>「Import Sample」
  2. 在「Browse Samples」精靈頂端附近的搜尋列中,輸入「compose」。
  3. 在搜尋結果中選取其中一個 Jetpack Compose 範例應用程式,然後按一下「Next」
  4. 變更「Application name」和「Project location」,或者保留預設值。
  5. 按一下「Finish」(完成)

Android Studio 會將範例應用程式下載至您指定的路徑,並開啟專案。接著,您可以在 IDE 預覽介面中檢查每個範例的 MainActivity.kt,瞭解 Jetpack Compose API 的效果,例如交叉漸變動畫、自訂元件、使用字體排版,以及顯示淺色和深色。

如要使用適用於 Wear OS 的 Jetpack Compose,請參閱「在 Wear OS 上設定 Jetpack Compose」。

使用物料清單

您只要指定 BOM 版本,即可利用 Compose 物料清單 (BOM) 管理所有 Compose 程式庫版本。BOM 本身具有不同 Compose 程式庫的穩定版本連結,以便順暢搭配運作。在應用程式中使用 BOM 時,不需要將任何版本加到 Compose 程式庫依附元件。更新 BOM 版本後,您使用的所有程式庫都會自動更新至新版本。

如要瞭解哪些 Compose 程式庫版本對應至特定的 BOM 版本,請參閱 BOM 與程式庫版本對應清單

為什麼 BOM 沒有納入 Compose Compiler 程式庫?

Compose Kotlin 編譯器擴充功能 (androidx.compose.compiler) 並未連結至 Compose 程式庫版本,而是連結至 Kotlin 編譯器外掛程式的版本,且發布頻率與 Compose 的其餘部分不同,因此請務必使用與您的 Kotlin 版本相容的版本。您可以在 Compose 對應 Kotlin 的相容性清單中找到對應至每個外掛程式版本的 Kotlin 版本。

如何使用與 BOM 中指定版本不同的程式庫版本?

build.gradle 依附元件區段中,保留 BOM 平台的匯入內容。在程式庫依附元件匯入內容中,指定所需版本。例如,如要使用質感設計 3 的 Alpha 版本 (無論 BOM 中指定的是哪個版本),請按照以下方式宣告依附元件:

dependencies {
    // Import the Compose BOM
    implementation platform('androidx.compose:compose-bom:2022.10.00')

    // Override Material Design 3 library version with a pre-release version
    implementation 'androidx.compose.material3:material3:1.1.0-alpha01'

    // Import other Compose libraries without version numbers
    // ..
    implementation 'androidx.compose.foundation:foundation'
}

BOM 會自動將所有 Compose 程式庫加入應用程式嗎?

不會。如要在應用程式中加入及使用 Compose 程式庫,您必須在模組 (應用程式層級) Gradle 檔案 (通常是 app/build.gradle) 中,以獨立的依附元件行逐一宣告所有程式庫。

使用 BOM 可確保應用程式中所有 Compose 程式庫的版本都相容,但 BOM 實際上並未將這些 Compose 程式庫加入應用程式。

往後,Compose 程式庫將獨立建立版本,這表示版本編號會按照自身步調遞增。每個程式庫的最新穩定版本會經過測試,並保證可完美搭配運作。不過,要找出各程式庫的最新穩定版本可能並不容易,而 BOM 可協助您自動使用這些最新版本。

使用 BOM 是否為強制性質?

否,您仍可選擇手動新增每個依附元件版本。不過,我們建議您使用 BOM,因為這樣就能更容易同時使用所有最新穩定版本。

BOM 是否能與版本目錄搭配運作?

可以。您可以在版本目錄中加入 BOM 本身,並省略其他 Compose 程式庫版本:

[libraries]
androidx-compose-bom = { group = "androidx.compose", name = "compose-bom", version.ref = "androidxComposeBom" }
androidx-compose-foundation = { group = "androidx.compose.foundation", name = "foundation" }

別忘了在模組的 build.gradle 中匯入 BOM:

dependencies {
    val composeBom = platform(libs.androidx.compose.bom)
    implementation(composeBom)
    androidTestImplementation(composeBom)

    // import Compose dependencies as usual
}

如何回報 BOM 相關問題或提供意見回饋?

您可以透過 Issue Tracker 回報問題。

BOM 與程式庫版本對應清單

程式庫群組 2022.10.00 中的版本 2022.11.00 中的版本
androidx.compose.animation:animation 1.3.0 1.3.1
androidx.compose.animation:animation-core 1.3.0 1.3.1
androidx.compose.animation:animation-graphics 1.3.0 1.3.1
androidx.compose.foundation:foundation 1.3.0 1.3.1
androidx.compose.foundation:foundation-layout 1.3.0 1.3.1
androidx.compose.material:material 1.3.0 1.3.1
androidx.compose.material:material-icons-core 1.3.0 1.3.1
androidx.compose.material:material-icons-extended 1.3.0 1.3.1
androidx.compose.material:material-ripple 1.3.0 1.3.1
androidx.compose.material3:material3 1.0.0 1.0.1
androidx.compose.material3:material3-window-size-class 1.0.0 1.0.1
androidx.compose.runtime:runtime 1.3.0 1.3.1
androidx.compose.runtime:runtime-livedata 1.3.0 1.3.1
androidx.compose.runtime:runtime-rxjava2 1.3.0 1.3.1
androidx.compose.runtime:runtime-rxjava3 1.3.0 1.3.1
androidx.compose.runtime:runtime-saveable 1.3.0 1.3.1
androidx.compose.ui:ui 1.3.0 1.3.1
androidx.compose.ui:ui-geometry 1.3.0 1.3.1
androidx.compose.ui:ui-graphics 1.3.0 1.3.1
androidx.compose.ui:ui-test 1.3.0 1.3.1
androidx.compose.ui:ui-test-junit4 1.3.0 1.3.1
androidx.compose.ui:ui-test-manifest 1.3.0 1.3.1
androidx.compose.ui:ui-text 1.3.0 1.3.1
androidx.compose.ui:ui-text-google-fonts 1.3.0 1.3.1
androidx.compose.ui:ui-tooling 1.3.0 1.3.1
androidx.compose.ui:ui-tooling-data 1.3.0 1.3.1
androidx.compose.ui:ui-tooling-preview 1.3.0 1.3.1
androidx.compose.ui:ui-unit 1.3.0 1.3.1
androidx.compose.ui:ui-util 1.3.0 1.3.1
androidx.compose.ui:ui-viewbinding 1.3.0 1.3.1