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
- พร็อพเพอร์ตี้ที่อัปเดตใน Lambda:
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/awaitPointerEventScopeModifier.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) |