Trang này được dịch bởi Cloud Translation API.

Tạo đối tượng sửa đổi tuỳ chỉnh

Compose cung cấp nhiều đối tượng sửa đổi cho các hành vi phổ biến ngay từ đầu, nhưng bạn cũng có thể tạo đối tượng sửa đổi tuỳ chỉnh của riêng mình.

Đối tượng sửa đổi có nhiều phần:

Nhà máy đối tượng sửa đổi
- Đây là một hàm mở rộng trên Modifier, cung cấp một API theo ngôn ngữ cho đối tượng sửa đổi và cho phép các đối tượng sửa đổi dễ dàng được nối với nhau. Nhà máy đối tượng sửa đổi tạo ra các phần tử đối tượng sửa đổi mà Compose sử dụng để sửa đổi giao diện người dùng.
Phần tử sửa đổi
- Đây là nơi bạn có thể triển khai hành vi của đối tượng sửa đổi.

Có nhiều cách để triển khai đối tượng sửa đổi tuỳ chỉnh tuỳ thuộc vào chức năng cần thiết. Thông thường, cách dễ nhất để triển khai đối tượng sửa đổi tuỳ chỉnh là triển khai một nhà máy đối tượng sửa đổi tuỳ chỉnh kết hợp các nhà máy đối tượng sửa đổi đã xác định khác với nhau. Nếu bạn cần hành vi tuỳ chỉnh hơn, hãy triển khai phần tử đối tượng sửa đổi bằng cách sử dụng các API Modifier.Node. Các API này có cấp thấp hơn nhưng linh hoạt hơn.

Liên kết các đối tượng sửa đổi hiện có với nhau

Bạn thường có thể tạo công cụ sửa đổi tuỳ chỉnh chỉ bằng cách sử dụng các công cụ sửa đổi hiện có. Ví dụ: Modifier.clip() được triển khai bằng đối tượng sửa đổi graphicsLayer. Chiến lược này sử dụng các phần tử đối tượng sửa đổi hiện có và bạn cung cấp nhà máy đối tượng sửa đổi tuỳ chỉnh của riêng mình.

Trước khi triển khai đối tượng sửa đổi tuỳ chỉnh của riêng bạn, hãy xem liệu bạn có thể sử dụng cùng một chiến lược hay không.

fun Modifier.clip(shape: Shape) = graphicsLayer(shape = shape, clip = true)CustomModifierSnippets.kt

Hoặc nếu thấy mình thường xuyên lặp lại cùng một nhóm đối tượng sửa đổi, bạn có thể gói các đối tượng đó vào đối tượng sửa đổi của riêng mình:

fun Modifier.myBackground(color: Color) = padding(16.dp)
    .clip(RoundedCornerShape(8.dp))
    .background(color)CustomModifierSnippets.kt

Tạo đối tượng sửa đổi tuỳ chỉnh bằng nhà máy đối tượng sửa đổi có thể kết hợp

Bạn cũng có thể tạo đối tượng sửa đổi tuỳ chỉnh bằng cách sử dụng hàm có khả năng kết hợp để truyền giá trị đến đối tượng sửa đổi hiện có. Đây được gọi là nhà máy đối tượng sửa đổi có thể kết hợp.

Việc sử dụng nhà máy đối tượng sửa đổi có thể kết hợp để tạo đối tượng sửa đổi cũng cho phép sử dụng các API Compose cấp cao hơn, chẳng hạn như animate*AsState và các API ảnh động được hỗ trợ trạng thái Compose khác. Ví dụ: đoạn mã sau đây cho thấy một công cụ sửa đổi tạo ảnh động cho thay đổi về alpha khi bật/tắt:

@Composable
fun Modifier.fade(enable: Boolean): Modifier {
    val alpha by animateFloatAsState(if (enable) 0.5f else 1.0f)
    return this then Modifier.graphicsLayer { this.alpha = alpha }
}CustomModifierSnippets.kt

Nếu đối tượng sửa đổi tuỳ chỉnh của bạn là một phương thức thuận tiện để cung cấp giá trị mặc định từ CompositionLocal, thì cách dễ nhất để triển khai phương thức này là sử dụng nhà máy đối tượng sửa đổi có thể kết hợp:

@Composable
fun Modifier.fadedBackground(): Modifier {
    val color = LocalContentColor.current
    return this then Modifier.background(color.copy(alpha = 0.5f))
}CustomModifierSnippets.kt

Phương pháp này có một số lưu ý được nêu chi tiết bên dưới.

Các giá trị `CompositionLocal` được phân giải tại vị trí gọi của nhà máy đối tượng sửa đổi

Khi tạo một đối tượng sửa đổi tuỳ chỉnh bằng nhà máy đối tượng sửa đổi có thể kết hợp, các thành phần kết hợp cục bộ sẽ lấy giá trị từ cây thành phần kết hợp nơi các thành phần kết hợp đó được tạo, chứ không phải được sử dụng. Điều này có thể dẫn đến kết quả không mong muốn. Ví dụ: lấy ví dụ về đối tượng sửa đổi cục bộ của thành phần ở trên, được triển khai hơi khác bằng cách sử dụng hàm có khả năng kết hợp:

@Composable
fun Modifier.myBackground(): Modifier {
    val color = LocalContentColor.current
    return this then Modifier.background(color.copy(alpha = 0.5f))
}

@Composable
fun MyScreen() {
    CompositionLocalProvider(LocalContentColor provides Color.Green) {
        // Background modifier created with green background
        val backgroundModifier = Modifier.myBackground()

        // LocalContentColor updated to red
        CompositionLocalProvider(LocalContentColor provides Color.Red) {

            // Box will have green background, not red as expected.
            Box(modifier = backgroundModifier)
        }
    }
}CustomModifierSnippets.kt

Nếu đây không phải là cách bạn muốn đối tượng sửa đổi hoạt động, hãy sử dụng Modifier.Node tuỳ chỉnh, vì các thành phần cục bộ sẽ được phân giải chính xác tại vị trí sử dụng và có thể được chuyển lên một cách an toàn.

Các đối tượng sửa đổi hàm có khả năng kết hợp không bao giờ bị bỏ qua

Các đối tượng sửa đổi nhà máy có khả năng kết hợp không bao giờ bị bỏ qua vì không thể bỏ qua các hàm có khả năng kết hợp có giá trị trả về. Điều này có nghĩa là hàm đối tượng sửa đổi sẽ được gọi trong mỗi lần kết hợp lại. Điều này có thể gây tốn kém nếu hàm này kết hợp lại thường xuyên.

Bạn phải gọi đối tượng sửa đổi hàm có khả năng kết hợp trong một hàm có khả năng kết hợp

Giống như tất cả các hàm có khả năng kết hợp, đối tượng sửa đổi nhà máy có khả năng kết hợp phải được gọi từ trong thành phần. Điều này giới hạn vị trí có thể chuyển đối tượng sửa đổi lên trên, vì đối tượng này không bao giờ được chuyển ra khỏi thành phần. So sánh, bạn có thể chuyển các nhà máy đối tượng sửa đổi không có khả năng kết hợp ra khỏi các hàm có khả năng kết hợp để dễ dàng sử dụng lại và cải thiện hiệu suất:

val extractedModifier = Modifier.background(Color.Red) // Hoisted to save allocations

@Composable
fun Modifier.composableModifier(): Modifier {
    val color = LocalContentColor.current.copy(alpha = 0.5f)
    return this then Modifier.background(color)
}

@Composable
fun MyComposable() {
    val composedModifier = Modifier.composableModifier() // Cannot be extracted any higher
}CustomModifierSnippets.kt

Triển khai hành vi đối tượng sửa đổi tuỳ chỉnh bằng `Modifier.Node`

Modifier.Node là một API cấp thấp hơn để tạo đối tượng sửa đổi trong Compose. Đây cũng là API mà Compose triển khai các đối tượng sửa đổi của riêng mình và là cách hiệu quả nhất để tạo đối tượng sửa đổi tuỳ chỉnh.

Triển khai đối tượng sửa đổi tuỳ chỉnh bằng `Modifier.Node`

Có ba phần để triển khai đối tượng sửa đổi tuỳ chỉnh bằng Modifier.Node:

Quá trình triển khai Modifier.Node chứa logic và trạng thái của đối tượng sửa đổi.
ModifierNodeElement tạo và cập nhật các thực thể nút đối tượng sửa đổi.
Một nhà máy đối tượng sửa đổi không bắt buộc như mô tả ở trên.

Các lớp ModifierNodeElement không có trạng thái và các thực thể mới được phân bổ cho mỗi lần kết hợp lại, trong khi các lớp Modifier.Node có thể có trạng thái và sẽ tồn tại qua nhiều lần kết hợp lại, thậm chí có thể được sử dụng lại.

Phần sau đây mô tả từng phần và đưa ra ví dụ về cách tạo một công cụ sửa đổi tuỳ chỉnh để vẽ một vòng tròn.

`Modifier.Node`

Việc triển khai Modifier.Node (trong ví dụ này là CircleNode) sẽ triển khai chức năng của đối tượng sửa đổi tuỳ chỉnh.

// Modifier.Node
private class CircleNode(var color: Color) : DrawModifierNode, Modifier.Node() {
    override fun ContentDrawScope.draw() {
        drawCircle(color)
    }
}CustomModifierSnippets.kt

Trong ví dụ này, hàm này vẽ vòng tròn có màu được truyền vào hàm đối tượng sửa đổi.

Một nút triển khai Modifier.Node cũng như không có hoặc có nhiều loại nút. Có nhiều loại nút dựa trên chức năng mà đối tượng sửa đổi yêu cầu. Ví dụ trên cần có khả năng vẽ, vì vậy, ví dụ này triển khai DrawModifierNode, cho phép ghi đè phương thức vẽ.

Sau đây là các loại hiện có:

Điểm	Tác dụng	Đường liên kết đến mẫu
`LayoutModifierNode`	`Modifier.Node` thay đổi cách đo lường và sắp xếp bố cục nội dung được bao bọc.	Mẫu
`DrawModifierNode`	`Modifier.Node` vẽ vào không gian của bố cục.	Mẫu
`CompositionLocalConsumerModifierNode`	Việc triển khai giao diện này cho phép `Modifier.Node` đọc thành phần cục bộ.	Mẫu
`SemanticsModifierNode`	`Modifier.Node` thêm khoá/giá trị ngữ nghĩa để sử dụng trong kiểm thử, hỗ trợ tiếp cận và các trường hợp sử dụng tương tự.	Mẫu
`PointerInputModifierNode`	`Modifier.Node` nhận PointerInputChanges.	Mẫu
`ParentDataModifierNode`	`Modifier.Node` cung cấp dữ liệu cho bố cục mẹ.	Mẫu
`LayoutAwareModifierNode`	`Modifier.Node` nhận lệnh gọi lại `onMeasured` và `onPlaced`.	Mẫu
`GlobalPositionAwareModifierNode`	`Modifier.Node` nhận lệnh gọi lại `onGloballyPositioned` với `LayoutCoordinates` cuối cùng của bố cục khi vị trí toàn cục của nội dung có thể đã thay đổi.	Mẫu
`ObserverModifierNode`	Các `Modifier.Node` triển khai `ObserverNode` có thể cung cấp phương thức triển khai `onObservedReadsChanged` riêng sẽ được gọi để phản hồi các thay đổi đối với đối tượng ảnh chụp nhanh được đọc trong khối `observeReads`.	Mẫu
`DelegatingNode`	`Modifier.Node` có thể uỷ quyền công việc cho các thực thể `Modifier.Node` khác. Điều này có thể hữu ích khi kết hợp nhiều cách triển khai nút thành một.	Mẫu
`TraversableNode`	Cho phép các lớp `Modifier.Node` di chuyển lên/xuống cây nút cho các lớp cùng loại hoặc cho một khoá cụ thể.	Mẫu

Các nút sẽ tự động mất hiệu lực khi lệnh cập nhật được gọi trên phần tử tương ứng. Vì ví dụ của chúng ta là DrawModifierNode, nên bất cứ khi nào phương thức cập nhật được gọi trên phần tử, nút này sẽ kích hoạt quá trình vẽ lại và màu của phần tử sẽ cập nhật chính xác. Bạn có thể chọn không sử dụng tính năng tự động vô hiệu hoá như được nêu chi tiết dưới đây.

`ModifierNodeElement`

ModifierNodeElement là một lớp không thể thay đổi, chứa dữ liệu để tạo hoặc cập nhật đối tượng sửa đổi tuỳ chỉnh:

// ModifierNodeElement
private data class CircleElement(val color: Color) : ModifierNodeElement<CircleNode>() {
    override fun create() = CircleNode(color)

    override fun update(node: CircleNode) {
        node.color = color
    }
}CustomModifierSnippets.kt

Các phương thức triển khai ModifierNodeElement cần ghi đè các phương thức sau:

create: Đây là hàm tạo bản sao cho nút đối tượng sửa đổi. Phương thức này được gọi để tạo nút khi đối tượng sửa đổi được áp dụng lần đầu tiên. Thông thường, việc này tương đương với việc tạo nút và định cấu hình nút đó bằng các tham số được truyền vào nhà máy đối tượng sửa đổi.
update: Hàm này được gọi bất cứ khi nào đối tượng sửa đổi này được cung cấp ở cùng một vị trí mà nút này đã tồn tại, nhưng một thuộc tính đã thay đổi. Điều này được xác định bằng phương thức equals của lớp. Nút đối tượng sửa đổi đã được tạo trước đó sẽ được gửi dưới dạng tham số đến lệnh gọi update. Tại thời điểm này, bạn nên cập nhật các thuộc tính của nút để tương ứng với các tham số đã cập nhật. Khả năng sử dụng lại các nút theo cách này là yếu tố chính giúp tăng hiệu suất mà Modifier.Node mang lại; do đó, bạn phải cập nhật nút hiện có thay vì tạo nút mới trong phương thức update. Trong ví dụ về vòng tròn, màu của nút sẽ được cập nhật.

Ngoài ra, các hoạt động triển khai ModifierNodeElement cũng cần triển khai equals và hashCode. update sẽ chỉ được gọi nếu phép so sánh bằng với phần tử trước đó trả về giá trị sai.

Ví dụ trên sử dụng một lớp dữ liệu để thực hiện việc này. Các phương thức này được dùng để kiểm tra xem một nút có cần cập nhật hay không. Nếu phần tử của bạn có các thuộc tính không đóng góp vào việc liệu một nút có cần được cập nhật hay không hoặc bạn muốn tránh các lớp dữ liệu vì lý do tương thích nhị phân, thì bạn có thể triển khai equals và hashCode theo cách thủ công, ví dụ: phần tử sửa đổi khoảng đệm.

Nhà máy đối tượng sửa đổi

Đây là giao diện API công khai của công cụ sửa đổi. Hầu hết các phương thức triển khai chỉ cần tạo phần tử đối tượng sửa đổi và thêm phần tử đó vào chuỗi đối tượng sửa đổi:

// Modifier factory
fun Modifier.circle(color: Color) = this then CircleElement(color)CustomModifierSnippets.kt

Ví dụ đầy đủ

Ba phần này kết hợp với nhau để tạo đối tượng sửa đổi tuỳ chỉnh nhằm vẽ một vòng tròn bằng các API Modifier.Node:

// Modifier factory
fun Modifier.circle(color: Color) = this then CircleElement(color)

// ModifierNodeElement
private data class CircleElement(val color: Color) : ModifierNodeElement<CircleNode>() {
    override fun create() = CircleNode(color)

    override fun update(node: CircleNode) {
        node.color = color
    }
}

// Modifier.Node
private class CircleNode(var color: Color) : DrawModifierNode, Modifier.Node() {
    override fun ContentDrawScope.draw() {
        drawCircle(color)
    }
}CustomModifierSnippets.kt

Các trường hợp phổ biến sử dụng `Modifier.Node`

Khi tạo đối tượng sửa đổi tuỳ chỉnh bằng Modifier.Node, sau đây là một số trường hợp phổ biến mà bạn có thể gặp phải.

Không có tham số

Nếu đối tượng sửa đổi không có tham số, thì đối tượng đó không bao giờ cần cập nhật và hơn nữa, không cần phải là một lớp dữ liệu. Dưới đây là ví dụ về cách triển khai mẫu của một đối tượng sửa đổi áp dụng một khoảng đệm cố định cho một thành phần kết hợp:

fun Modifier.fixedPadding() = this then FixedPaddingElement

data object FixedPaddingElement : ModifierNodeElement<FixedPaddingNode>() {
    override fun create() = FixedPaddingNode()
    override fun update(node: FixedPaddingNode) {}
}

class FixedPaddingNode : LayoutModifierNode, Modifier.Node() {
    private val PADDING = 16.dp

    override fun MeasureScope.measure(
        measurable: Measurable,
        constraints: Constraints
    ): MeasureResult {
        val paddingPx = PADDING.roundToPx()
        val horizontal = paddingPx * 2
        val vertical = paddingPx * 2

        val placeable = measurable.measure(constraints.offset(-horizontal, -vertical))

        val width = constraints.constrainWidth(placeable.width + horizontal)
        val height = constraints.constrainHeight(placeable.height + vertical)
        return layout(width, height) {
            placeable.place(paddingPx, paddingPx)
        }
    }
}CustomModifierSnippets.kt

Tham chiếu thành phần cục bộ

Đối tượng sửa đổi Modifier.Node không tự động quan sát các thay đổi đối với đối tượng trạng thái Compose, chẳng hạn như CompositionLocal. Ưu điểm của đối tượng sửa đổi Modifier.Node so với đối tượng sửa đổi chỉ được tạo bằng nhà máy có khả năng kết hợp là đối tượng sửa đổi này có thể đọc giá trị của thành phần cục bộ từ vị trí sử dụng đối tượng sửa đổi trong cây giao diện người dùng, chứ không phải vị trí phân bổ đối tượng sửa đổi, bằng cách sử dụng currentValueOf.

Tuy nhiên, các thực thể nút đối tượng sửa đổi không tự động quan sát các thay đổi về trạng thái. Để tự động phản ứng với việc thay đổi thành phần cục bộ, bạn có thể đọc giá trị hiện tại của thành phần đó bên trong một phạm vi:

DrawModifierNode: ContentDrawScope
LayoutModifierNode: MeasureScope & IntrinsicMeasureScope
SemanticsModifierNode: SemanticsPropertyReceiver

Ví dụ này quan sát giá trị của LocalContentColor để vẽ nền dựa trên màu của giá trị đó. Vì ContentDrawScope quan sát các thay đổi về ảnh chụp nhanh, nên thao tác này sẽ tự động vẽ lại khi giá trị của LocalContentColor thay đổi:

class BackgroundColorConsumerNode :
    Modifier.Node(),
    DrawModifierNode,
    CompositionLocalConsumerModifierNode {
    override fun ContentDrawScope.draw() {
        val currentColor = currentValueOf(LocalContentColor)
        drawRect(color = currentColor)
        drawContent()
    }
}CustomModifierSnippets.kt

Để phản ứng với các thay đổi về trạng thái bên ngoài phạm vi và tự động cập nhật đối tượng sửa đổi, hãy sử dụng ObserverModifierNode.

Ví dụ: Modifier.scrollable sử dụng kỹ thuật này để quan sát các thay đổi trong LocalDensity. Dưới đây là ví dụ đơn giản:

class ScrollableNode :
    Modifier.Node(),
    ObserverModifierNode,
    CompositionLocalConsumerModifierNode {

    // Place holder fling behavior, we'll initialize it when the density is available.
    val defaultFlingBehavior = DefaultFlingBehavior(splineBasedDecay(UnityDensity))

    override fun onAttach() {
        updateDefaultFlingBehavior()
        observeReads { currentValueOf(LocalDensity) } // monitor change in Density
    }

    override fun onObservedReadsChanged() {
        // if density changes, update the default fling behavior.
        updateDefaultFlingBehavior()
    }

    private fun updateDefaultFlingBehavior() {
        val density = currentValueOf(LocalDensity)
        defaultFlingBehavior.flingDecay = splineBasedDecay(density)
    }
}CustomModifierSnippets.kt

Đối tượng sửa đổi ảnh động

Các phương thức triển khai Modifier.Node có quyền truy cập vào coroutineScope. Điều này cho phép sử dụng Compose Animatable API. Ví dụ: đoạn mã này sửa đổi CircleNode ở trên để làm mờ và làm rõ lặp đi lặp lại:

class CircleNode(var color: Color) : Modifier.Node(), DrawModifierNode {
    private val alpha = Animatable(1f)

    override fun ContentDrawScope.draw() {
        drawCircle(color = color, alpha = alpha.value)
        drawContent()
    }

    override fun onAttach() {
        coroutineScope.launch {
            alpha.animateTo(
                0f,
                infiniteRepeatable(tween(1000), RepeatMode.Reverse)
            ) {
            }
        }
    }
}CustomModifierSnippets.kt

Chia sẻ trạng thái giữa các đối tượng sửa đổi bằng cách uỷ quyền

Đối tượng sửa đổi Modifier.Node có thể uỷ quyền cho các nút khác. Có nhiều trường hợp sử dụng cho việc này, chẳng hạn như trích xuất các phương thức triển khai phổ biến trên nhiều đối tượng sửa đổi, nhưng bạn cũng có thể dùng tính năng này để chia sẻ trạng thái chung trên các đối tượng sửa đổi.

Ví dụ: cách triển khai cơ bản của nút công cụ sửa đổi có thể nhấp để chia sẻ dữ liệu tương tác:

class ClickableNode : DelegatingNode() {
    val interactionData = InteractionData()
    val focusableNode = delegate(
        FocusableNode(interactionData)
    )
    val indicationNode = delegate(
        IndicationNode(interactionData)
    )
}CustomModifierSnippets.kt

Chọn không tự động vô hiệu hoá nút

Các nút Modifier.Node sẽ tự động mất hiệu lực khi lệnh gọi ModifierNodeElement tương ứng cập nhật. Đôi khi, trong một đối tượng sửa đổi phức tạp hơn, bạn có thể chọn không áp dụng hành vi này để có quyền kiểm soát chi tiết hơn về thời điểm đối tượng sửa đổi vô hiệu hoá các giai đoạn.

Điều này có thể đặc biệt hữu ích nếu đối tượng sửa đổi tuỳ chỉnh của bạn sửa đổi cả bố cục và bản vẽ. Khi chọn không tự động vô hiệu hoá, bạn chỉ cần vô hiệu hoá bản vẽ khi chỉ các thuộc tính liên quan đến bản vẽ, chẳng hạn như color, thay đổi và không vô hiệu hoá bố cục. Điều này có thể cải thiện hiệu suất của đối tượng sửa đổi.

Ví dụ giả định về điều này được hiển thị bên dưới với một đối tượng sửa đổi có hàm lambda color, size và onClick dưới dạng thuộc tính. Đối tượng sửa đổi này chỉ vô hiệu hoá những gì cần thiết và bỏ qua mọi trường hợp vô hiệu hoá không cần thiết:

class SampleInvalidatingNode(
    var color: Color,
    var size: IntSize,
    var onClick: () -> Unit
) : DelegatingNode(), LayoutModifierNode, DrawModifierNode {
    override val shouldAutoInvalidate: Boolean
        get() = false

    private val clickableNode = delegate(
        ClickablePointerInputNode(onClick)
    )

    fun update(color: Color, size: IntSize, onClick: () -> Unit) {
        if (this.color != color) {
            this.color = color
            // Only invalidate draw when color changes
            invalidateDraw()
        }

        if (this.size != size) {
            this.size = size
            // Only invalidate layout when size changes
            invalidateMeasurement()
        }

        // If only onClick changes, we don't need to invalidate anything
        clickableNode.update(onClick)
    }

    override fun ContentDrawScope.draw() {
        drawRect(color)
    }

    override fun MeasureScope.measure(
        measurable: Measurable,
        constraints: Constraints
    ): MeasureResult {
        val size = constraints.constrain(size)
        val placeable = measurable.measure(constraints)
        return layout(size.width, size.height) {
            placeable.place(0, 0)
        }
    }
}CustomModifierSnippets.kt

Các hạn chế và thứ tự của đối tượng sửa đổi

Tiếp

Danh sách đối tượng sửa đổi