รายละเอียดตัวปรับตามระยะ

Jetpack Compose จะเรียกใช้ตัวแก้ไขในระยะต่างๆ รายละเอียดต่อไปนี้แสดงให้เห็นว่าตัวแก้ไขทั่วไปอยู่ในเฟสใด และระบบจะประเมินอาร์กิวเมนต์หรือ Lambda เมื่อใด

ระยะที่ 1: ระยะการจัดองค์ประกอบ

ตัวแก้ไขเหล่านี้จะประเมินอาร์กิวเมนต์แบบซิงโครนัสภายในเนื้อหา @Composable การอ่านสถานะที่นี่จะลงทะเบียนทรัพยากร Dependency กับขอบเขตการรีสตาร์ท Composable และทริกเกอร์การจัดองค์ประกอบใหม่ทั้งหมดเมื่อมีการเปลี่ยนแปลง

  • ตัวแก้ไขขนาดและมิติข้อมูลแบบคงที่:
    • 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) (ใน RowScope หรือ ColumnScope)
    • Modifier.width(IntrinsicSize.Min / Max)
    • Modifier.height(IntrinsicSize.Min / Max)
  • ระยะห่างและส่วนแทรกแบบคงที่
    • Modifier.padding(all = dp), Modifier.padding(start, top, end, bottom)
    • Modifier.windowInsetsPadding(insets), Modifier.statusBarsPadding()
  • ตัวแก้ไขภาพค่าโดยตรง:
    • Modifier.alpha(float) (อ่านสถานะระหว่างการคอมโพสิชัน)
    • Modifier.rotate(degrees) (อ่านสถานะระหว่างการคอมโพสิชัน)
    • Modifier.scale(scaleX, scaleY) (อ่านสถานะระหว่างการคอมโพสิชัน)
    • Modifier.background(color = Color, shape = Shape)
    • Modifier.border(width, color, shape)
    • Modifier.shadow(elevation, shape)
    • Modifier.clip(shape)
    • Modifier.blur(radius)
  • ตัวแก้ไขตำแหน่งแบบคงที่
    • Modifier.offset(x = dp, y = dp) (การโอเวอร์โหลดค่าโดยตรง)
    • Modifier.absoluteOffset(x = dp, y = dp)
  • ตัวแก้ไข Composable แบบไดนามิก:
    • Modifier.composed { ... } (เรียกใช้เนื้อหาโรงงานระหว่างการคอมโพสิชัน ไม่แนะนำให้ใช้เพื่อประสิทธิภาพ ให้ใช้ Modifier.Node สำหรับตัวแก้ไขที่กำหนดเองแทน)

ระยะที่ 2: ระยะเลย์เอาต์

ระยะเลย์เอาต์แบ่งออกเป็น 2 ขั้นตอนย่อยที่แตกต่างกันซึ่งมีขอบเขตการทำให้เป็นโมฆะแยกกัน ดังนี้

ขั้นตอนที่ 2ก: การวัดผล

กำหนดขนาด (width, height) และข้อจำกัด การอ่านสถานะที่นี่จะทริกเกอร์การวัดอีกครั้งและการจัดวางใหม่

  • Modifier.layout { measurable, constraints -> ... }: โค้ดก่อน layout(w, h) จะทำงานระหว่างการวัด

ขั้นตอนที่ 2B: Callback ของตำแหน่งและเลย์เอาต์

กำหนดตำแหน่งพิกัด (x, y) การอ่านสถานะภายในบล็อกการวางจะทริกเกอร์การวางใหม่เท่านั้น (ข้ามการวัดและการจัดองค์ประกอบ)

  • Modifier.offset { IntOffset(x, y) } (lambda overload)
  • Modifier.absoluteOffset { IntOffset(x, y) } (lambda overload)
  • Modifier.layout { ... layout(w, h) { placeable.place(x, y) } }: โค้ดภายในบล็อก layout(w, h) { ... }

นอกจากนี้ Layout observation callback ยังทำงานระหว่างหรือหลังการส่งผ่านเลย์เอาต์ด้วย (หลีกเลี่ยงการเขียนไปยังสถานะที่อ่านใน Composition ภายใน Callback เหล่านี้ เนื่องจากจะทำให้เกิดการเขียนย้อนกลับ)

  • Modifier.onSizeChanged { intSize -> ... }: เรียกใช้หลังจากวัดเลย์เอาต์เสร็จสมบูรณ์หากขนาดของโหนดมีการเปลี่ยนแปลง
  • Modifier.onPlaced { layoutCoordinates -> ... } และ Modifier.onLayoutRectChanged { ... }: เรียกใช้หลังจากวางเพื่อรายงานพิกัดหรือขอบเขตในเครื่องโดยไม่ต้องสมัครรับข้อมูลการส่งผ่านเลย์เอาต์หน้าต่างส่วนกลาง
  • Modifier.onGloballyPositioned { layoutCoordinates -> ... }: เรียกใช้หลังจากที่การส่งผ่านเลย์เอาต์ของหน้าต่างทั้งหมดเสร็จสิ้นเมื่อใดก็ตามที่โหนดมีการย้าย หลีกเลี่ยง onGloballyPositioned หากเป็นไปได้ และเลือกใช้ Modifier.onVisibilityChanged สำหรับการติดตามวิวพอร์ต, Modifier.onPlaced หรือ Modifier.onLayoutRectChanged สำหรับขอบเขตในเครื่อง หรือ requireLayoutCoordinates() ตามต้องการภายใน Modifier.Node

ระยะที่ 3: ระยะการจับสลาก

ตัวแก้ไขเหล่านี้จะทำงานระหว่างการวาด Canvas การอ่านสถานะภายในบล็อกเหล่านี้จะข้ามทั้งการจัดองค์ประกอบและเลย์เอาต์ โดยจะเรียกใช้เฉพาะการส่งผ่านการวาดเท่านั้น

  • Modifier.graphicsLayer { ... }:
    • พร็อพเพอร์ตี้ที่อัปเดตใน Lambda: alpha, translationX, translationY, scaleX, scaleY, rotationX, rotationY, rotationZ, shadowElevation, shape, clip, renderEffect, transformOrigin
  • Modifier.drawBehind { ... }:
    • วาดคำสั่ง Canvas ไว้ด้านหลังเนื้อหาที่ประกอบกันได้
  • Modifier.drawWithContent { ... }:
    • ควบคุมลำดับการวาดด้วย drawContent()
  • Modifier.drawWithCache { ... }:
    • บล็อกด้านนอกจะทำงานเมื่อมีการเปลี่ยนแปลงขนาดหรือเลย์เอาต์เพื่อแคชออบเจ็กต์ Path, Paint หรือ Brush ส่วน onDrawBehind หรือ onDrawWithContent จะทำงานเมื่อมีการวาดเฟรมแต่ละเฟรม

นอกลูปการจัดองค์ประกอบใหม่ - ตัวแก้ไขการสังเกตการณ์

ตัวแก้ไขบางตัวทำงานนอกเฟสทั้ง 3 เฟสเพื่อจัดการการช่วยเหลือพิเศษ อินพุตของผู้ใช้ และการสังเกตวงจร

ความหมายและการช่วยเหลือพิเศษ

ประมวลผลพร็อพเพอร์ตี้เชิงความหมายสำหรับบริการการช่วยเหลือพิเศษ (TalkBack) และการทดสอบ

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

อินพุต ท่าทางสัมผัส และเหตุการณ์

ทำงานนอกไปป์ไลน์การแสดงผลเฟรม 3 ระยะ โดยรับเหตุการณ์การเคลื่อนไหวของระบบปฏิบัติการและการโต้ตอบของผู้ใช้ ดังนี้

  • 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 เมื่อระดับการเข้าถึงของ Composable มีการเปลี่ยนแปลงหลังจากความล่าช้าที่กำหนดค่าไว้ใน Coroutine

ข้อมูลอ้างอิงแบบย่อ: ระยะมูลค่าเทียบกับระยะแลมบ์ดา

การอ่านค่าสถานะใน Lambda จะเลื่อนการอ่านไปยังระยะหลัง ซึ่งจะข้ามระยะก่อนหน้าเมื่อสถานะนั้นเปลี่ยนแปลง

ตัวแก้ไข / รูปแบบ มูลค่าโดยตรง (องค์ประกอบ) ตัวแปรแลมบ์ดา (ระยะที่เลื่อนออกไป) เมื่อสถานะเปลี่ยน
Offset Modifier.offset(x, y) Modifier.offset { IntOffset(x, y) } เลย์เอาต์ (ตำแหน่ง) (ข้าม Composition)
อัลฟ่า / ความทึบแสง Modifier.alpha(alpha) Modifier.graphicsLayer { this.alpha = alpha } การวาดภาพ (ข้ามการจัดองค์ประกอบและเลย์เอาต์)
การหมุน Modifier.rotate(degrees) Modifier.graphicsLayer { rotationZ = degrees } การวาดภาพ (ข้ามการจัดองค์ประกอบและเลย์เอาต์)
Scale Modifier.scale(scale) Modifier.graphicsLayer { scaleX = s; scaleY = s } การวาดภาพ (ข้ามการจัดองค์ประกอบและเลย์เอาต์)
คำแปล Modifier.padding(...) Modifier.graphicsLayer { translationX = ... } การวาดภาพ (ข้ามการจัดองค์ประกอบและเลย์เอาต์)
สีพื้นหลัง Modifier.background(color) Modifier.drawBehind { drawRect(color) } การวาดภาพ (ข้ามการจัดองค์ประกอบและเลย์เอาต์)
เลื่อน / พารัลแลกซ์ Modifier.offset(scroll.dp) Modifier.offset { IntOffset(0, scroll) } เลย์เอาต์ (ตำแหน่ง) (ข้าม Composition)

การแมปอินเทอร์เฟซ Modifier.Node

สำหรับตัวแก้ไขที่กำหนดเองซึ่งใช้ Modifier.Node API ประสิทธิภาพสูง เฟสจะแมปกับอินเทอร์เฟซความสามารถของโหนดโดยตรง ดังนี้

ระยะเวลาดำเนินการ อินเทอร์เฟซ Modifier.Node เมธอดหลัก
เลย์เอาต์ (วัดและวาง) LayoutModifierNode measure(measurable, constraints)
เลย์เอาต์ (พิกัดส่วนกลาง) GlobalPositionAwareModifierNode (ต้องการ requireLayoutCoordinates() แบบออนดีมานด์) onGloballyPositioned(coordinates)
เลย์เอาต์ (ตำแหน่งโฆษณา) LayoutAwareModifierNode onRemeasured(size), onPlaced(coordinates)
Drawing DrawModifierNode draw(ContentDrawScope)
อินพุต / ตัวชี้ PointerInputModifierNode onPointerEvent(...), onCancelPointerInput()
ความหมาย SemanticsModifierNode applySemantics(SemanticsPropertyReceiver)
โฟกัส FocusEventModifierNode onFocusEvent(focusState)