在應用程式中新增 Jetpack Compose

如果您想在現有專案中使用 Jetpack Compose，就必須使用必要的設定和依附元件來設定專案。

設定開發環境

安裝正確的 Android Studio 版本

為了在使用 Jetpack Compose 進行開發時享有最佳體驗，請下載 Android Studio，並設定與 Android Studio 版本對應的 Android Gradle 外掛程式：

buildscript {
    ...
    dependencies {
        classpath "com.android.tools.build:gradle:7.0.0"
        ...
    }
}

設定 Kotlin

請確認您在專案中使用的是 Kotlin 1.6.10：

plugins {
    id 'kotlin-android'
}

設定 Gradle

您必須將應用程式的最低 API 級別設為 21 以上，並在應用程式的 build.gradle 檔案中啟用 Jetpack Compose，如下所示。此外，您也必須設定 Kotlin 編譯器外掛程式的版本。

android {
    defaultConfig {
        ...
        minSdkVersion 21
    }

    buildFeatures {
        // Enables Jetpack Compose for this module
        compose true
    }
    ...

    // Set both the Java and Kotlin compilers to target Java 8.
    compileOptions {
        sourceCompatibility JavaVersion.VERSION_1_8
        targetCompatibility JavaVersion.VERSION_1_8
    }
    kotlinOptions {
        jvmTarget = "1.8"
    }

    composeOptions {
        kotlinCompilerExtensionVersion '1.1.1'
    }
}

新增 Jetpack Compose 工具包依附元件

在應用程式的 build.gradle 檔案中加入 Jetpack Compose 工具包依附元件，如下所示：

dependencies {
    // Integration with activities
    implementation 'androidx.activity:activity-compose:1.4.0'
    // Compose Material Design
    implementation 'androidx.compose.material:material:1.1.1'
    // Animations
    implementation 'androidx.compose.animation:animation:1.1.1'
    // Tooling support (Previews, etc.)
    implementation 'androidx.compose.ui:ui-tooling:1.1.1'
    // Integration with ViewModels
    implementation 'androidx.lifecycle:lifecycle-viewmodel-compose:2.4.1'
    // UI Tests
    androidTestImplementation 'androidx.compose.ui:ui-test-junit4:1.1.1'
}

在 Compose 中重複使用 View 主題

如果您剛剛才在專案中加入 Compose，可能會希望讓 Compose 沿用 View 系統提供的主題，而非從頭開始撰寫質感主題。

如果您在 Android 應用程式中使用 MDC 程式庫，可以利用 MDC Compose Theme Adapter 程式庫，在可組合項目中重複使用以 View 為基礎的現有主題顏色、字體排版和形狀主題設定。只要使用 MdcTheme API 即可進行這項作業。

如果您要改為採用 AppCompat XML 主題，請使用內含 AppCompatTheme API 的 AppCompat Compose Theme Adapter。

在應用程式的 build.gradle 檔案中加入所需依附元件，如下所示：

dependencies {
    // When using a MDC theme
    implementation "com.google.android.material:compose-theme-adapter:1.1.1"

    // When using a AppCompat theme
    implementation "com.google.accompanist:accompanist-appcompat-theme:0.16.0"
}

開始遷移至 Compose

假設我們想將使用者問候語文字遷移至應用程式中的 Jetpack Compose。我們可能會在 XML 版面配置中提供以下內容：

<...>
    <!-- Other content -->

    <TextView
        android:id="@+id/greeting"
        android:layout_width="match_parent"
        android:layout_height="wrap_content"
        android:layout_marginStart="@dimen/margin_small"
        android:layout_marginEnd="@dimen/margin_small"
        android:gravity="center_horizontal"
        android:text="@string/greeting"
        android:textAppearance="?attr/textAppearanceHeadline5"
        ... />
</...>

如要將這些內容遷移至 Compose，我們可將 TextView 替換成 ComposeView，並保留相同的版面配置參數和 id。系統會將所有其他 XML 屬性遷移至 Compose：

<...>
    <!-- Other content -->

    <androidx.compose.ui.platform.ComposeView
        android:id="@+id/greeting"
        android:layout_width="match_parent"
        android:layout_height="wrap_content"/>
</...>

這樣一來，我們就能透過使用該 XML 版面配置的 Activity 或 Fragment 取得 ComposeView，並呼叫 setContent 方法以在該版面配置中新增 Compose 內容：

class MyActivity : AppCompatActivity() {
    override fun onCreate(savedInstanceState: Bundle?) {
        super.onCreate(savedInstanceState)
        // ...

        val greeting = findViewById<ComposeView>(R.id.greeting)
        greeting.setContent {
            MdcTheme { // or AppCompatTheme
                Greeting()
            }
        }
    }
}

@Composable
private fun Greeting() {
    Text(
        text = stringResource(R.string.greeting),
        style = MaterialTheme.typography.h5,
        modifier = Modifier
            .fillMaxWidth()
            .padding(horizontal = dimensionResource(R.dimen.margin_small))
            .wrapContentWidth(Alignment.CenterHorizontally)
    )
}

如需 ComposeView 和其他互通性 API 的詳細資訊，請參閱 Interoperability API 指南。如要進一步瞭解 Compose 中的 stringResource、dimensionResource 和其他資源 API，請參閱 Compose 中的資源指南。

測試混合型使用者介面

將應用程式的各個部分遷移至 Compose 後，請務必進行測試，以確保沒有任何內容遭到毀損。

當活動或片段使用 Compose (而不是使用 ActivityScenarioRule) 時，您必須使用 createAndroidComposeRule 以整合 ActivityScenarioRule 與 ComposeTestRule，藉此同時測試 Compose 和 View 程式碼。

class MyActivityTest {
    @Rule
    @JvmField
    val composeTestRule = createAndroidComposeRule<MyActivity>()

    @Test
    fun testGreeting() {
        val greeting = InstrumentationRegistry.getInstrumentation()
            .targetContext.resources.getString(R.string.greeting)

        composeTestRule.onNodeWithText(greeting).assertIsDisplayed()
    }
}

如要進一步瞭解測試方式以及與 Espresso 的互通性，請參閱測試 Compose 版面配置指南。

如果您在應用程式中使用導覽元件，請參閱使用 Compose 進行導覽指南的互通性一節。

後續步驟

如要進一步瞭解 Compose，請前往說明文件索引。您可以透過不同方式在應用程式中採用 Compose，詳情請參閱在您的應用程式中採用 Compose 指南，您也可以透過這篇文章連結至其他指南，例如「在現有架構中的 Compose」以及「在現有 UI 中的 Compose」。