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. Nội dung phân tích sau đây cho biết các đối tượng sửa đổi phổ biến thuộc giai đoạn nào và thời điểm các đối số hoặc hàm 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 phần thân @Composable. Bất kỳ trạng thái nào được đọc ở đây đều đăng ký phần phụ thuộc với phạm vi khởi động lại của thành phần kết hợp và kích hoạt quá trình kết hợp lại đầy đủ khi thay đổi.

  • Kích thước tĩnh và đố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) (bằng 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 hình ảnh 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)
  • Đố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)
  • Đối tượng sửa đổi thành phần kết hợp động:
    • Modifier.composed { ... } (chạy phần thân của nhà máy trong quá trình kết hợp; không nên dùng cho hiệu suất – hãy sử dụng Modifier.Node cho đối tượng sửa đổi tuỳ chỉnh)

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

Giai đoạn Bố cục được chia thành hai 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 quy tắc ràng buộc. Việc đọc trạng thái ở đâ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) thực thi trong quá trình đo lường.

Bước 2B: 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 bên trong các khối vị trí chỉ kích hoạt vị trí mới (bỏ qua đo lường và thành phần):

  • Modifier.offset { IntOffset(x, y) } (quá tải lambda)
  • Modifier.absoluteOffset { IntOffset(x, y) } (quá tải lambda)
  • Modifier.layout { ... layout(w, h) { placeable.place(x, y) } }: Mã bên trong khối layout(w, h) { ... }.

Lệnh gọi lại quan sát bố cục cũng chạy trong hoặc sau lượt bố cục (tránh ghi vào trạng thái được đọc trong Thành phần bên trong các lệnh gọi lại này, vì làm như vậy sẽ gây ra việc ghi ngược):

  • 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 của nút thay đổi.
  • Modifier.onPlaced { layoutCoordinates -> ... } và Modifier.onLayoutRectChanged { ... }: Được gọi sau khi đặt để báo cáo toạ độ hoặc ranh giới cục bộ mà không cần đăng ký các lượt truyền bố cục cửa sổ chung.
  • Modifier.onGloballyPositioned { layoutCoordinates -> ... }: Được gọi sau khi toàn bộ lượt bố cục cửa sổ hoàn tất mỗi khi có nút di chuyển. Tránh sử dụng onGloballyPositioned khi có thể; ưu tiên Modifier.onVisibilityChanged để theo dõi khung nhìn, Modifier.onPlaced hoặc Modifier.onLayoutRectChanged cho các giới hạn cục bộ hoặc requireLayoutCoordinates() theo yêu cầu bên trong Modifier.Node.

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

Các đối tượng sửa đổi này 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 lượt 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 composable.
  • 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 các đối tượng Path, Paint hoặc Brush vào bộ nhớ đệm; onDrawBehind hoặc onDrawWithContent chạy trên mỗi lần vẽ khung hình.

Bên 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 ba giai đoạn khung để xử lý khả năng hỗ trợ tiếp cận, hoạt động đầu vào của người dùng và quan sát vòng đời.

Ngữ nghĩa và 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 { ... }

Thao tá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 ba giai đoạn, nhận các sự kiện chuyển động của hệ điều hành và hoạt động 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 độ trễ đã định 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 giá trị trạng thái trong lambda sẽ trì hoãn việc đọc sang giai đoạn sau, giúp 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 trì hoãn) 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 bố cục và thành phần)
Xoay Modifier.rotate(degrees) Modifier.graphicsLayer { rotationZ = degrees } Vẽ (Bỏ qua Bố cục và Sắp xếp)
Mở rộng quy mô Modifier.scale(scale) Modifier.graphicsLayer { scaleX = s; scaleY = s } Vẽ (Bỏ qua bố cục và thành phần)
Bản dịch Modifier.padding(...) Modifier.graphicsLayer { translationX = ... } Vẽ (Bỏ qua bố cục và thành phần)
Màu nền Modifier.background(color) Modifier.drawBehind { drawRect(color) } Vẽ (Bỏ qua 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)

Liên kết giao diện Modifier.Node

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

Giai đoạn Giao diện Modifier.Node Phương thức cốt lõi
Bố cục (Đo lường và đặt vị trí) LayoutModifierNode measure(measurable, constraints)
Bố cục (Toạ độ chung) GlobalPositionAwareModifierNode (ưu tiên requireLayoutCoordinates() theo yêu cầu) onGloballyPositioned(coordinates)
Bố cục (Vị trí đặt quảng cáo) 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)