כתיבה וספריות אחרות

אתם יכולים להשתמש בספריות המועדפות עליכם ב-Compose. בקטע הזה מוסבר איך לשלב כמה מהספריות הכי שימושיות.

פעילות

כדי להשתמש ב-Compose בפעילות, צריך להשתמש ב-ComponentActivity, שהוא מחלקת משנה של Activity שמספקת את LifecycleOwner המתאים ואת הרכיבים ל-Compose. הוא מספק גם ממשקי API נוספים שמפרידים את הקוד שלכם משיטות דריסה במחלקת הפעילות. ‫Activity Compose חושף את ממשקי ה-API האלה לפונקציות Composable, כך שלא נדרש יותר להחליף שיטות מחוץ לפונקציות Composable או לאחזר מופע Activity מפורש. בנוסף, ממשקי ה-API האלה מבטיחים שהם יאותחלו רק פעם אחת, שהם ימשיכו לפעול גם אחרי הרכבה מחדש, ושהם ינקו את עצמם בצורה תקינה אם רכיב ה-Composable יוסר מההרכבה.

תוצאת הפעילות

‫rememberLauncherForActivityResult() API מאפשר לכם לקבל תוצאה מפעילות בקומפוזיציה:

@Composable
fun GetContentExample() {
    var imageUri by remember { mutableStateOf<Uri?>(null) }
    val launcher = rememberLauncherForActivityResult(ActivityResultContracts.GetContent()) { uri: Uri? ->
        imageUri = uri
    }
    Column {
        Button(onClick = { launcher.launch("image/*") }) {
            Text(text = "Load Image")
        }
        Image(
            painter = rememberAsyncImagePainter(imageUri),
            contentDescription = "My Image"
        )
    }
}

בדוגמה הזו מוצג חוזה פשוט של GetContent(). הקשה על הלחצן מפעילה את הבקשה. ה-lambda האחורי של rememberLauncherForActivityResult() מופעל ברגע שהמשתמש בוחר תמונה וחוזר לפעילות ההפעלה. התמונה שנבחרה נטענת באמצעות הפונקציה rememberImagePainter() של Coil.

אפשר להשתמש בכל מחלקת משנה של ActivityResultContract כארגומנט הראשון של rememberLauncherForActivityResult(). המשמעות היא שאפשר להשתמש בטכניקה הזו כדי לבקש תוכן מהמסגרת וגם בדפוסים נפוצים אחרים. אפשר גם ליצור חוזים מותאמים אישית ולהשתמש בהם בטכניקה הזו.

שליחת בקשה להרשאות בזמן ריצה

אפשר להשתמש באותו API של תוצאות פעילות ובאותו חוזה rememberLauncherForActivityResult() שמוסברים למעלה כדי לבקש הרשאות בזמן ריצה באמצעות חוזה RequestPermission להרשאה יחידה או חוזה RequestMultiplePermissions לכמה הרשאות.

אפשר גם להשתמש בספריית ההרשאות של Accompanist כשכבה מעל ממשקי ה-API האלה כדי למפות את המצב הנוכחי של ההרשאות למצב שבו ממשק המשתמש של Compose יכול להשתמש.

טיפול בכפתור 'הקודם' במערכת

כדי לספק ניווט לאחור מותאם אישית ולשנות את פעולת ברירת המחדל של הכפתור "הקודם" של המערכת מתוך הפונקציה הקומפוזבילית, הפונקציה הקומפוזבילית יכולה להשתמש ב-BackHandler כדי ליירט את האירוע הזה:

var backHandlingEnabled by remember { mutableStateOf(true) }
BackHandler(backHandlingEnabled) {
    // Handle back press
}

הארגומנט הראשון קובע אם BackHandler מופעל כרגע. אפשר להשתמש בארגומנט הזה כדי להשבית באופן זמני את ה-handler בהתאם למצב הרכיב. פונקציית ה-lambda האחרונה תופעל אם המשתמש יפעיל אירוע חזרה למערכת, ו-BackHandler מופעל כרגע.

ViewModel

אם משתמשים בספרייה Architecture Components ViewModel, אפשר לגשת אל ViewModel מכל קומפוזיציה על ידי קריאה לפונקציה viewModel(). מוסיפים את יחסי התלות הבאים לקובץ Gradle:

מגניב

dependencies {
    implementation 'androidx.lifecycle:lifecycle-viewmodel-compose:2.11.0'
}

Kotlin

dependencies {
    implementation("androidx.lifecycle:lifecycle-viewmodel-compose:2.11.0")
}

אחר כך תוכלו להשתמש בפונקציה viewModel() בקוד.

class MyViewModel : ViewModel() { /*...*/ }

// import androidx.lifecycle.viewmodel.compose.viewModel
@Composable
fun MyScreen(
    viewModel: MyViewModel = viewModel()
) {
    // use viewModel here
}

‫viewModel() מחזירה ViewModel קיים או יוצרת אחד חדש. כברירת מחדל, הערך ViewModel שמוחזר מוגבל לפעילות, לקטע או ליעד הניווט שמכילים אותו, והוא נשמר כל עוד ההיקף פעיל.

לדוגמה, אם הקומפוזיציה נמצאת בשימוש בפעילות, viewModel() מחזירה את אותו מופע עד שהפעילות מסתיימת או שהתהליך מופסק.

class MyViewModel : ViewModel() { /*...*/ }
// import androidx.lifecycle.viewmodel.compose.viewModel
@Composable
fun MyScreen(
    // Returns the same instance as long as the activity is alive,
    // just as if you grabbed the instance from an Activity or Fragment
    viewModel: MyViewModel = viewModel()
) { /* ... */ }

@Composable
fun MyScreen2(
    viewModel: MyViewModel = viewModel() // Same instance as in MyScreen
) { /* ... */ }

הנחיות שימוש

בדרך כלל ניגשים למופעים של ViewModel ב-composables ברמת המסך, כלומר קרוב ל-composable בסיסי שנקרא מפעילות, מ-fragment או מיעד של גרף ניווט. הסיבה לכך היא ש-ViewModels מוגדרים כברירת מחדל בהיקף של האובייקטים האלה ברמת המסך. מידע נוסף על מחזור החיים וההיקף של ViewModel

מומלץ להימנע מהעברה של מופעי ViewModel לרכיבי Composable אחרים, כי זה יכול להקשות על הבדיקה של רכיבי Composable האלה ולגרום לשיבוש תצוגות מקדימות. במקום זאת, מעבירים רק את הנתונים והפונקציות שהם צריכים כפרמטרים.

אפשר להשתמש במופעים של ViewModel כדי לנהל את המצב של קומפוזיציות ברמת מסך המשנה, אבל חשוב להכיר את מחזור החיים וההיקף של ViewModel. אם רכיב ה-Composable הוא עצמאי, כדאי להשתמש ב-Hilt כדי להזריק את ViewModel, וכך לא תצטרכו להעביר תלויות מרכיבי ה-Composable של ההורה.

אם למדד ViewModel יש תלויות, הפונקציה viewModel() מקבלת כפרמטר את האפשרות ViewModelProvider.Factory.

מידע נוסף על ViewModel בכתיבה ועל אופן השימוש במופעים עם ספריית הניווט בכתיבה, או פעילויות וקטעים, זמין במסמכי יכולת הפעולה ההדדית.

מקורות נתונים

ל-Compose יש תוספים לפתרונות הפופולריים ביותר של Android שמבוססים על סטרימינג. כל אחת מההרחבות האלה מסופקת על ידי ארטיפקט אחר:

  • LiveData.observeAsState() כלול בפריט המידע שנוצר בתהליך פיתוח (Artifact) androidx.compose.runtime:runtime-livedata:$composeVersion.
  • Flow.collectAsState() לא דורש תלות נוספת.
  • ‫Observable.subscribeAsState() כלול בארטיפקט androidx.compose.runtime:runtime-rxjava2:$composeVersion או androidx.compose.runtime:runtime-rxjava3:$composeVersion.

הארטיפקטים האלה נרשמים כמאזינים ומייצגים את הערכים כ-State. בכל פעם שמופק ערך חדש, Compose מבצע קומפוזיציה מחדש של אותם חלקים בממשק המשתמש שבהם נעשה שימוש ב-state.value. לדוגמה, בקוד הזה, ShowData מורכב מחדש בכל פעם ש-exampleLiveData פולט ערך חדש.

// import androidx.lifecycle.viewmodel.compose.viewModel
@Composable
fun MyScreen(
    viewModel: MyViewModel = viewModel()
) {
    val dataExample = viewModel.exampleLiveData.observeAsState()

    // Because the state is read here,
    // MyScreen recomposes whenever dataExample changes.
    dataExample.value?.let {
        ShowData(dataExample)
    }
}

פעולות אסינכרוניות ב-Compose

‫Jetpack Compose מאפשרת לכם להפעיל פעולות אסינכרוניות באמצעות קורוטינות מתוך רכיבי ה-Composable.

מידע נוסף זמין במאמר תיעוד בנושא תופעות לוואי על ממשקי ה-API‏ LaunchedEffect, produceState ו-rememberCoroutineScope.

רכיב הניווט מספק תמיכה באפליקציות Jetpack Compose. מידע נוסף זמין במאמרים ניווט באמצעות Compose והעברת נתונים מ-Jetpack Navigation ל-Navigation Compose.

Hilt

‫Hilt הוא הפתרון המומלץ להזרקת תלות באפליקציות ל-Android, והוא פועל בצורה חלקה עם Compose.

הפונקציה viewModel() שמוזכרת בקטע ViewModel משתמשת באופן אוטומטי ב-ViewModel ש-Hilt בונה באמצעות ההערה @HiltViewModel. סיפקנו מסמכי תיעוד עם מידע על שילוב של ViewModel ב-Hilt.

@HiltViewModel
class MyViewModel @Inject constructor(
    private val savedStateHandle: SavedStateHandle,
    private val repository: ExampleRepository
) : ViewModel() { /* ... */ }

// import androidx.lifecycle.viewmodel.compose.viewModel
@Composable
fun MyScreen(
    viewModel: MyViewModel = viewModel()
) { /* ... */ }

‫Hilt ו-Navigation

‫Hilt משתלב גם עם ספריית Navigation Compose. מוסיפים את יחסי התלות הנוספים הבאים לקובץ Gradle:

מגניב

dependencies {
    implementation 'androidx.hilt:hilt-navigation-compose:1.4.0'
}

Kotlin

dependencies {
    implementation("androidx.hilt:hilt-navigation-compose:1.4.0")
}

כשמשתמשים ב-Navigation Compose, תמיד צריך להשתמש בפונקציה הקומפוזבילית hiltViewModel כדי לקבל מופע של @HiltViewModel עם ההערה ViewModel. האפשרות הזו פועלת עם קטעי קוד או פעילויות שמוערים באמצעות @AndroidEntryPoint.

לדוגמה, אם ExampleScreen הוא יעד בתרשים ניווט, צריך לקרוא ל-hiltViewModel() כדי לקבל מופע של ExampleViewModel בהיקף של היעד, כמו שמוצג בקטע הקוד הבא:

// import androidx.hilt.navigation.compose.hiltViewModel

@Composable
fun MyApp() {
    val navController = rememberNavController()
    val startRoute = "example"
    NavHost(navController, startDestination = startRoute) {
        composable("example") { backStackEntry ->
            // Creates a ViewModel from the current BackStackEntry
            // Available in the androidx.hilt:hilt-navigation-compose artifact
            val viewModel = hiltViewModel<MyViewModel>()
            MyScreen(viewModel)
        }
        /* ... */
    }
}

אם אתם צריכים לאחזר את המופע של ViewModel בהיקף של נתיבי ניווט או גרף הניווט, במקום זאת, השתמשו בפונקציה קומפוזבילית hiltViewModel והעבירו את backStackEntry המתאים כפרמטר:

// import androidx.hilt.navigation.compose.hiltViewModel
// import androidx.navigation.compose.getBackStackEntry

@Composable
fun MyApp() {
    val navController = rememberNavController()
    val startRoute = "example"
    val innerStartRoute = "exampleWithRoute"
    NavHost(navController, startDestination = startRoute) {
        navigation(startDestination = innerStartRoute, route = "Parent") {
            // ...
            composable("exampleWithRoute") { backStackEntry ->
                val parentEntry = remember(backStackEntry) {
                    navController.getBackStackEntry("Parent")
                }
                val parentViewModel = hiltViewModel<ParentViewModel>(parentEntry)
                ExampleWithRouteScreen(parentViewModel)
            }
        }
    }
}

חלוקה לדפים

ספריית ההחלפה של דפים (Paging) מאפשרת לטעון נתונים בהדרגה, והיא נתמכת ב-Compose. בדף המידע על הגרסה של Paging מופיע מידע על התלות הנוספת paging-compose שצריך להוסיף לפרויקט ולגרסה שלו.

דוגמה לממשקי ה-API של Compose בספריית Paging:

@Composable
fun MyScreen(flow: Flow<PagingData<String>>) {
    val lazyPagingItems = flow.collectAsLazyPagingItems()
    LazyColumn {
        items(
            lazyPagingItems.itemCount,
            key = lazyPagingItems.itemKey { it }
        ) { index ->
            val item = lazyPagingItems[index]
            Text("Item is $item")
        }
    }
}

מידע נוסף על שימוש בהחלפה בין דפים ב-Compose זמין במסמכי התיעוד בנושא רשימות ורשתות.

מפות

אפשר להשתמש בספריית Maps Compose כדי לספק את מפות Google באפליקציה. הנה דוגמה לשימוש:

@Composable
fun MapsExample() {
    val singapore = LatLng(1.35, 103.87)
    val cameraPositionState = rememberCameraPositionState {
        position = CameraPosition.fromLatLngZoom(singapore, 10f)
    }
    GoogleMap(
        modifier = Modifier.fillMaxSize(),
        cameraPositionState = cameraPositionState
    ) {
        Marker(
            state = remember { MarkerState(position = singapore) },
            title = "Singapore",
            snippet = "Marker in Singapore"
        )
    }
}