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

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

ระยะที่ 1: ระยะการแต่งเพลง

ตัวแก้ไขเหล่านี้จะประเมินอาร์กิวเมนต์พร้อมกันภายใน@Composable body สถานะใดก็ตามที่อ่านที่นี่จะลงทะเบียนการอ้างอิงกับขอบเขตการรีสตาร์ทของ 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)
  • ตัวแก้ไขแบบรวมแบบไดนามิก
    • Modifier.composed { ... } (เรียกใช้เนื้อหาของ Factory ระหว่างการคอมโพส)

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

ระยะเลย์เอาต์แบ่งออกเป็น 2 ขั้นตอนย่อยที่แตกต่างกันโดยมีขอบเขตการล้างแคชแยกกัน ดังนี้

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

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

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

ขั้นตอนที่ 2B: การเรียกกลับของตําแหน่งและเลย์เอาต์

กำหนดตำแหน่งพิกัด (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) { ... }
  • Modifier.onPlaced { layoutCoordinates -> ... }: เรียกใช้หลังจากที่กำหนดพิกัดขององค์ประกอบระดับบนสุดในระหว่างการวาง
  • Modifier.onSizeChanged { intSize -> ... }: เรียกใช้หลังจากที่การวัดเลย์เอาต์เสร็จสมบูรณ์ หากมีการเปลี่ยนขนาด
  • Modifier.onGloballyPositioned { layoutCoordinates -> ... }: เรียกใช้หลังจาก การส่งเลย์เอาต์หน้าต่างทั้งหมดเสร็จสิ้น

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

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

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

ตัวแก้ไข / รูปแบบ มูลค่าโดยตรง (องค์ประกอบ) สายพันธุ์แลมบ์ดา (ระยะเลื่อน) เมื่อมีการเปลี่ยนแปลงสถานะ
หักลบ Modifier.offset(x, y) Modifier.offset { IntOffset(x, y) } เลย์เอาต์ (ตำแหน่ง) (ข้ามการจัดองค์ประกอบ)
อัลฟ่า / ความทึบ 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) } เลย์เอาต์ (ตำแหน่ง) (ข้ามการจัดองค์ประกอบ)

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

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

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