Bảng chi tiết đối tượng sửa đổi theo giai đoạn

Jetpack Compose thực thi các đối tượng sửa đổi qua nhiều giai đoạn riêng biệt. Thông tin chi tiết sau đây cho biết các đối tượng sửa đổi thường gặp thuộc giai đoạn nào và khi nào các đối số hoặc lambda của chúng được đánh giá.

Giai đoạn 1: Giai đoạn thành phần

Các đối tượng sửa đổi này đánh giá các đối số đồng bộ bên trong @Composablebody. Mọi trạng thái được đọc ở đây đều đăng ký một phần phụ thuộc với phạm vi khởi động lại Thành phần kết hợp và kích hoạt quá trình kết hợp lại hoàn toàn khi thay đổi.

• Phương diện tĩnh và các đối tượng sửa đổi kích thước:
  • 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) (trong RowScope hoặc ColumnScope)
  • Modifier.width(IntrinsicSize.Min / Max)
  • Modifier.height(IntrinsicSize.Min / Max)
• Khoảng cách và phần lồng ghép tĩnh:
  • Modifier.padding(all = dp), Modifier.padding(start, top, end, bottom)
  • Modifier.windowInsetsPadding(insets), Modifier.statusBarsPadding()
• Đối tượng sửa đổi trực quan về giá trị trực tiếp:
  • Modifier.alpha(float) (đọc trạng thái trong quá trình kết hợp)
  • Modifier.rotate(degrees) (đọc trạng thái trong quá trình kết hợp)
  • Modifier.scale(scaleX, scaleY) (đọc trạng thái trong quá trình kết hợp)
  • Modifier.background(color = Color, shape = Shape)
  • Modifier.border(width, color, shape)
  • Modifier.shadow(elevation, shape)
  • Modifier.clip(shape)
  • Modifier.blur(radius)
• Static Position Modifiers (Đối tượng sửa đổi vị trí tĩnh):
  • Modifier.offset(x = dp, y = dp) (quá tải giá trị trực tiếp)
  • Modifier.absoluteOffset(x = dp, y = dp)
• Dynamic Composable Modifiers (Sửa đổi thành phần kết hợp linh động):
  • Modifier.composed { ... } (chạy phần nội dung của thành phần trong quá trình kết hợp)

Giai đoạn 2: Giai đoạn bố cục

Giai đoạn Bố cục được chia thành 2 bước phụ riêng biệt với các phạm vi vô hiệu hoá riêng:

Bước 2A: Đo lường

Xác định kích thước (width, height) và các điều kiện ràng buộc. Trạng thái được đọc ở đây sẽ kích hoạt đo lường lại và đặt lại vị trí:

• Modifier.layout { measurable, constraints -> ... }: Mã trước layout(w, h) sẽ thực thi trong quá trình đo lường.

Bước 2B: Các lệnh gọi lại về vị trí và bố cục

Xác định vị trí toạ độ (x, y). Trạng thái được đọc ở đây chỉ kích hoạt việc đặt lại (bỏ qua quá trình đo lường và kết hợp):

• Modifier.offset { IntOffset(x, y) } (lambda overload)
• Modifier.absoluteOffset { IntOffset(x, y) } (lambda overload)
• Modifier.layout { ... layout(w, h) { placeable.place(x, y) } }: Mã bên trong khối layout(w, h) { ... }.
• Modifier.onPlaced { layoutCoordinates -> ... }: Được gọi sau khi xác định toạ độ gốc trong quá trình đặt.
• Modifier.onSizeChanged { intSize -> ... }: Được gọi sau khi quá trình đo lường bố cục hoàn tất nếu kích thước thay đổi.
• Modifier.onGloballyPositioned { layoutCoordinates -> ... }: Được gọi sau khi toàn bộ quá trình bố trí cửa sổ kết thúc.

Giai đoạn 3: Giai đoạn vẽ

Các đối tượng sửa đổi này sẽ thực thi trong quá trình vẽ canvas. Trạng thái đọc bên trong các khối này sẽ bỏ qua cả Thành phần và Bố cục, chỉ chạy đường truyền vẽ:

• Modifier.graphicsLayer { ... }:
  • Các thuộc tính được cập nhật trong lambda: alpha, translationX, translationY, scaleX, scaleY, rotationX, rotationY, rotationZ, shadowElevation, shape, clip, renderEffect, transformOrigin.
• Modifier.drawBehind { ... }:
  • Vẽ các lệnh canvas phía sau nội dung có thể kết hợp.
• Modifier.drawWithContent { ... }:
  • Kiểm soát thứ tự vẽ bằng drawContent().
• Modifier.drawWithCache { ... }:
  • Khối bên ngoài chạy khi có thay đổi về kích thước hoặc bố cục để lưu vào bộ nhớ đệm các đối tượng Path, Paint hoặc Brush; onDrawBehind hoặc onDrawWithContent chạy trên mỗi khung hình vẽ.

Ngoài vòng lặp kết hợp lại – đối tượng sửa đổi quan sát

Một số đối tượng sửa đổi hoạt động bên ngoài 3 giai đoạn khung hình để xử lý khả năng hỗ trợ tiếp cận, hoạt động đầu vào của người dùng và các hoạt động quan sát vòng đời.

Ngữ nghĩa và khả năng hỗ trợ tiếp cận

Xử lý các thuộc tính ngữ nghĩa cho dịch vụ hỗ trợ tiếp cận (TalkBack) và thử nghiệm:

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

Phương thức nhập, cử chỉ và sự kiện

Hoạt động bên ngoài quy trình kết xuất khung hình gồm 3 giai đoạn, nhận các sự kiện chuyển động của hệ điều hành và lượt tương tác của người dùng:

• 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 -> ... }: Lệnh gọi lại được gọi khi khả năng hiển thị của một composable thay đổi sau khi trễ theo cấu hình, trong một coroutine.

---

Tài liệu tham khảo nhanh: Giai đoạn Giá trị so với giai đoạn Lambda

Việc đọc một giá trị trạng thái trong một lambda sẽ trì hoãn việc đọc sang một giai đoạn sau, bỏ qua các giai đoạn trước đó khi trạng thái đó thay đổi:

Đối tượng sửa đổi / Mẫu	Giá trị trực tiếp (Thành phần)	Biến thể Lambda (Giai đoạn hoãn lại)	Khi trạng thái thay đổi
Offset	Modifier.offset(x, y)	Modifier.offset { IntOffset(x, y) }	Bố cục (Vị trí) (Bỏ qua thành phần)
Alpha / Độ mờ	Modifier.alpha(alpha)	Modifier.graphicsLayer { this.alpha = alpha }	Vẽ (Bỏ qua phần Bố cục và thành phần)
Xoay	Modifier.rotate(degrees)	Modifier.graphicsLayer { rotationZ = degrees }	Vẽ (Bỏ qua phần Bố cục và thành phần)
Tỷ lệ	Modifier.scale(scale)	Modifier.graphicsLayer { scaleX = s; scaleY = s }	Vẽ (Bỏ qua phần Bố cục và thành phần)
Bản dịch	Modifier.padding(...)	Modifier.graphicsLayer { translationX = ... }	Vẽ (Bỏ qua phần Bố cục và thành phần)
Màu nền	Modifier.background(color)	Modifier.drawBehind { drawRect(color) }	Vẽ (Bỏ qua phần Bố cục và thành phần)
Cuộn / Thị sai	Modifier.offset(scroll.dp)	Modifier.offset { IntOffset(0, scroll) }	Bố cục (Vị trí) (Bỏ qua thành phần)

Ánh xạ giao diện Modifier.Node

Đối với các đối tượng sửa đổi tuỳ chỉnh bằng API Modifier.Node hiệu suất cao, các giai đoạn sẽ ánh xạ trực tiếp đến các giao diện chức năng của nút:

Giai đoạn	Modifier.Node Giao diện	Phương thức cốt lõi
Bố cục (Đo lường và đặt)	LayoutModifierNode	measure(measurable, constraints)
Bố cục (Toạ độ chung)	GlobalPositionAwareModifierNode	onGloballyPositioned(coordinates)
Bố cục (Vị trí)	LayoutAwareModifierNode	onRemeasured(size), onPlaced(coordinates)
Vẽ	DrawModifierNode	draw(ContentDrawScope)
Thiết bị đầu vào / Con trỏ	PointerInputModifierNode	onPointerEvent(...), onCancelPointerInput()
Ngữ nghĩa	SemanticsModifierNode	applySemantics(SemanticsPropertyReceiver)
Tiêu điểm	FocusEventModifierNode	onFocusEvent(focusState)