Perincian pengubah menurut fase

Jetpack Compose menjalankan pengubah di berbagai fase yang berbeda. Perincian berikut menunjukkan fase tempat pengubah umum berada dan kapan argumen atau lambda dievaluasi.

Fase 1: Fase komposisi

Pengubah ini mengevaluasi argumen secara sinkron di dalam @Composable body. Setiap status yang dibaca di sini mendaftarkan dependensi dengan cakupan mulai ulang Composable dan memicu rekomposisi penuh saat diubah.

  • Dimensi Statis & Pengubah Ukuran:
    • Modifier.size(dp), Modifier.width(dp), Modifier.height(dp)
    • Modifier.fillMaxSize(), Modifier.fillMaxWidth(), Modifier.fillMaxHeight()
    • Modifier.wrapContentSize(), Modifier.wrapContentWidth(), Modifier.wrapContentHeight()
    • Modifier.requiredSize(), Modifier.defaultMinSize()
    • Modifier.aspectRatio(ratio)
    • Modifier.weight(weight) (dalam RowScope atau ColumnScope)
    • Modifier.width(IntrinsicSize.Min / Max)
    • Modifier.height(IntrinsicSize.Min / Max)
  • Jarak & Inset Statis:
    • Modifier.padding(all = dp), Modifier.padding(start, top, end, bottom)
    • Modifier.windowInsetsPadding(insets), Modifier.statusBarsPadding()
  • Pengubah Visual Nilai Langsung:
    • Modifier.alpha(float) (membaca status selama komposisi)
    • Modifier.rotate(degrees) (membaca status selama komposisi)
    • Modifier.scale(scaleX, scaleY) (membaca status selama komposisi)
    • Modifier.background(color = Color, shape = Shape)
    • Modifier.border(width, color, shape)
    • Modifier.shadow(elevation, shape)
    • Modifier.clip(shape)
    • Modifier.blur(radius)
  • Pengubah Posisi Statis:
    • Modifier.offset(x = dp, y = dp) (overload nilai langsung)
    • Modifier.absoluteOffset(x = dp, y = dp)
  • Pengubah Composable Dinamis:
    • Modifier.composed { ... } (menjalankan isi pabrik selama komposisi)

Fase 2: Fase tata letak

Fase Tata Letak dibagi menjadi dua sub-langkah berbeda dengan cakupan pembatalan yang terpisah:

Langkah 2A: Pengukuran

Menentukan ukuran (width, height) dan batasan. Pembacaan status di sini memicu pengukuran ulang dan penempatan ulang:

  • Modifier.layout { measurable, constraints -> ... }: Kode sebelum layout(w, h) dieksekusi selama pengukuran.

Langkah 2B: Callback penempatan & tata letak

Menentukan posisi koordinat (x, y). Pembacaan status di sini hanya memicu penempatan ulang (melewati pengukuran dan komposisi):

  • Modifier.offset { IntOffset(x, y) } (lambda overload)
  • Modifier.absoluteOffset { IntOffset(x, y) } (lambda overload)
  • Modifier.layout { ... layout(w, h) { placeable.place(x, y) } }: Kode di dalam blok layout(w, h) { ... }.
  • Modifier.onPlaced { layoutCoordinates -> ... }: Dipanggil setelah koordinat induk ditentukan selama penempatan.
  • Modifier.onSizeChanged { intSize -> ... }: Dipanggil setelah pengukuran tata letak selesai jika ukuran berubah.
  • Modifier.onGloballyPositioned { layoutCoordinates -> ... }: Dipanggil setelah seluruh proses tata letak jendela selesai.

Fase 3: Fase menggambar

Pengubah ini dieksekusi selama penggambaran kanvas. Pembacaan status di dalam blok ini melewati Komposisi dan Tata Letak, hanya menjalankan proses menggambar:

  • Modifier.graphicsLayer { ... }:
    • Properti yang diperbarui di lambda: alpha, translationX, translationY, scaleX, scaleY, rotationX, rotationY, rotationZ, shadowElevation, shape, clip, renderEffect, transformOrigin.
  • Modifier.drawBehind { ... }:
    • Menggambar perintah kanvas di belakang konten composable.
  • Modifier.drawWithContent { ... }:
    • Mengontrol urutan gambar dengan drawContent().
  • Modifier.drawWithCache { ... }:
    • Blok luar berjalan pada perubahan ukuran atau tata letak untuk meng-cache objek Path, Paint, atau Brush; onDrawBehind atau onDrawWithContent berjalan pada setiap gambar frame.

Di luar loop rekomposisi - pengubah pengamatan

Beberapa pengubah beroperasi di luar tiga fase frame untuk menangani aksesibilitas, input pengguna, dan pengamatan siklus proses.

Semantik & aksesibilitas

Memproses properti semantik untuk layanan aksesibilitas (TalkBack) dan pengujian:

  • Modifier.semantics { ... }
  • Modifier.clearAndSetSemantics { ... }

Input, gestur & peristiwa

Beroperasi di luar pipeline rendering frame tiga fase, menerima peristiwa gerakan OS dan interaksi pengguna:

  • Modifier.pointerInput(key) { detectTapGestures { ... } } / detectDragGestures / awaitPointerEventScope
  • Modifier.clickable(enabled, onClickLabel) { ... }
  • Modifier.combinedClickable { ... }
  • Modifier.toggleable { ... }
  • Modifier.selectable { ... }
  • Modifier.draggable(...) / Modifier.scrollable(...) / Modifier.draggable2D(...)
  • Modifier.onFocusChanged { focusState -> ... }
  • Modifier.onKeyEvent { keyEvent -> ... }
  • Modifier.onVisibilityChanged { isVisible -> ... }: Callback dipanggil saat visibilitas composable berubah setelah penundaan yang dikonfigurasi, dalam rutin bersama.

Referensi Cepat: Fase nilai versus Lambda

Membaca nilai status dalam lambda akan menunda pembacaan ke fase berikutnya, yang melewati fase sebelumnya saat status tersebut berubah:

Pengubah / Pola Nilai Langsung (Komposisi) Varian Lambda (Fase yang Ditangguhkan) Saat Status Berubah
Offset Modifier.offset(x, y) Modifier.offset { IntOffset(x, y) } Tata Letak (Penempatan) (Melewati Komposisi)
Alfa / Opasitas Modifier.alpha(alpha) Modifier.graphicsLayer { this.alpha = alpha } Menggambar (Melewati Komposisi & Tata Letak)
Rotasi Modifier.rotate(degrees) Modifier.graphicsLayer { rotationZ = degrees } Menggambar (Melewati Komposisi & Tata Letak)
Menskalakan Modifier.scale(scale) Modifier.graphicsLayer { scaleX = s; scaleY = s } Menggambar (Melewati Komposisi & Tata Letak)
Translation Modifier.padding(...) Modifier.graphicsLayer { translationX = ... } Menggambar (Melewati Komposisi & Tata Letak)
Warna Latar Belakang Modifier.background(color) Modifier.drawBehind { drawRect(color) } Menggambar (Melewati Komposisi & Tata Letak)
Scroll / Paralaks Modifier.offset(scroll.dp) Modifier.offset { IntOffset(0, scroll) } Tata Letak (Penempatan) (Melewati Komposisi)

Pemetaan antarmuka Modifier.Node

Untuk pengubah kustom yang menggunakan API Modifier.Node berperforma tinggi, pemetaan fase langsung ke antarmuka kemampuan node:

Fase Antarmuka Modifier.Node Metode Inti
Tata Letak (Ukur & Tempatkan) LayoutModifierNode measure(measurable, constraints)
Tata Letak (Koordinat Global) GlobalPositionAwareModifierNode onGloballyPositioned(coordinates)
Tata Letak (Penempatan) LayoutAwareModifierNode onRemeasured(size), onPlaced(coordinates)
Gambar DrawModifierNode draw(ContentDrawScope)
Input / Pointer PointerInputModifierNode onPointerEvent(...), onCancelPointerInput()
Semantik SemanticsModifierNode applySemantics(SemanticsPropertyReceiver)
Fokus FocusEventModifierNode onFocusEvent(focusState)