Áp dụng logic hoặc trình bao bọc cho đích đến

Bạn có thể cung cấp thêm thông tin hoặc áp dụng cùng một logic cho các đích đến bằng cách sử dụng lớp NavEntryDecorator. Lớp này gói từng NavEntry trong ngăn xếp lui bằng một hàm composable. Nói cách khác, nó trang trí nội dung của mục nhập.

Tạo trình trang trí tuỳ chỉnh

Để tạo một trình trang trí, hãy mở rộng lớp NavEntryDecorator và ghi đè các phương thức sau:

  • decorate – Một hàm composable lambda được gọi cho mỗi NavEntry trong ngăn xếp lui. Hàm này nhận NavEntry làm tham số. Nhờ đó, bạn có thể tạo các đối tượng trạng thái được liên kết với contentKey của mục nhập. Bạn có thể sử dụng CompositionLocalProvider để cung cấp các phần phụ thuộc cho nội dung của mục nhập. Bạn cũng có thể bao quanh nội dung bằng một hàm composable hoặc kích hoạt các hiệu ứng phụ. Bạn phải luôn gọi entry.Content() bên trong phương thức này.
  • onPop – Lệnh gọi lại được gọi khi NavEntry bị xoá khỏi ngăn xếp lui và thoát khỏi thành phần. Hàm này nhận contentKey của mục đã xoá. Sử dụng contentKey để xác định và dọn dẹp mọi trạng thái liên kết với mục nhập đó.

Ví dụ sau đây mở rộng lớp NavEntryDecorator để tạo một trình trang trí tuỳ chỉnh.

// import androidx.navigation3.runtime.NavEntryDecorator
class CustomNavEntryDecorator<T : Any> : NavEntryDecorator<T>(
    decorate = { entry ->
        Log.d("CustomNavEntryDecorator", "entry with ${entry.contentKey} entered composition and was decorated")
        entry.Content()
    },
    onPop = { contentKey -> Log.d("CustomNavEntryDecorator", "entry with $contentKey was popped") }
)

Nếu trình trang trí của bạn cần quyền truy cập vào state, hãy tạo một hàm composable để tạo state đó, sau đó sử dụng state đó để tạo trình trang trí. Để xem ví dụ về cách triển khai, hãy xem mã nguồn cho rememberSaveableStateHolderNavEntryDecorator. Thao tác này sẽ tạo trạng thái (SaveableStateHolder) và sử dụng trạng thái đó để tạo trình trang trí.

Trang trí ngăn xếp lui

Sau khi tạo NavEntryDecorator, hãy trang trí các mục trong ngăn xếp lui theo một trong hai cách sau:

  • Sử dụng rememberDecoratedNavEntries. Hàm này hữu ích khi bạn có nhiều ngăn xếp lui, mỗi ngăn xếp có một nhóm đối tượng trang trí riêng (xem mã mẫu này để biết thêm thông tin chi tiết). Hàm này trả về danh sách NavEntry được trang trí mà bạn có thể sử dụng với NavDisplay.
  • Cung cấp trực tiếp trình trang trí cho NavDisplay bằng tham số entryDecorators. NavDisplay gọi rememberDecoratedNavEntries theo cách không rõ ràng và hiển thị các mục được trang trí.

Thêm trình trang trí mặc định

Navigation 3 có một trình trang trí mặc định tên là SaveableStateHolderNavEntryDecorator, cho phép giữ lại trạng thái của NavEntry khi có thay đổi về cấu hình và khi bị buộc tắt. Hàm này gói nội dung NavEntry bằng SaveableStateProvider, cho phép các lệnh gọi rememberSaveable bên trong nội dung NavEntry hoạt động chính xác.

Trừ phi trình trang trí của bạn cung cấp SaveableStateProvider, bạn nên đưa SaveableStateHolderNavEntryDecorator vào làm trình trang trí đầu tiên trong danh sách các trình trang trí được cung cấp. Nó được tạo bằng rememberSaveableStateHolderNavEntryDecorator.

Ví dụ:

// import androidx.navigation3.runtime.rememberSaveableStateHolderNavEntryDecorator
NavDisplay(
    entryDecorators = listOf(
        rememberSaveableStateHolderNavEntryDecorator(),
        remember { CustomNavEntryDecorator() }
    ),
    // ...
)

Truyền kết quả bằng ResultEventBusNavEntryDecorator

Kể từ Navigation 3 1.2.0, bạn có thể sử dụng ResultEventBusNavEntryDecorator để cung cấp ResultEventBus cho mỗi NavEntry bằng cách sử dụng thành phần cục bộ LocalResultEventBus.

Theo mặc định, rememberResultEventBusNavEntryDecorator sẽ tạo và ghi nhớ thực thể ResultEventBus của riêng mình trong nội bộ bằng cách sử dụng rememberResultEventBus. Nếu cần truy cập vào tuyến nghe sự kiện bên ngoài hệ phân cấp của đối tượng trang trí (chẳng hạn như ở giàn giáo ứng dụng cấp cao nhất), bạn có thể kéo ResultEventBus lên bằng cách gọi rememberResultEventBus và truyền vào rememberResultEventBusNavEntryDecorator(resultEventBus):

val resultEventBus = rememberResultEventBus()

NavDisplay(
    /* ... */
    entryDecorators = listOf(
        rememberSaveableStateHolderNavEntryDecorator(),
        rememberResultEventBusNavEntryDecorator(resultEventBus = resultEventBus)
    )
)

Để biết thêm thông tin chi tiết về cách gửi và quan sát kết quả, hãy xem phần Trả về kết quả.

Trường hợp sử dụng trình trang trí

Sử dụng trình trang trí để:

  • Tạo một phần phụ thuộc cho mỗi NavEntry trong ngăn xếp lui. Ví dụ: ViewModelStoreNavEntryDecorator tạo một ViewModelStore cho mỗi NavEntry.
  • Chuyển kết quả và giao tiếp giữa các đích đến. Ví dụ: ResultEventBusNavEntryDecorator cung cấp ResultEventBus cho các đích đến trong ngăn xếp lui.
  • Xác định phạm vi của một đối tượng cho nhiều NavEntry. Ví dụ: để chia sẻ một ViewModel giữa nhiều mục.
  • Thực hiện cùng một thao tác cho nhiều NavEntry. Ví dụ: để thực hiện các thao tác ghi nhật ký, gỡ lỗi hoặc theo dõi cho từng mục nhập.
  • Gói NavEntry bằng cùng một hàm composable.
  • Dọn dẹp trạng thái liên kết với NavEntry. Ví dụ: khi một mục nhập bị xoá khỏi ngăn xếp lui, ViewModelStoreNavEntryDecorator sẽ xoá ViewModelStore liên kết với mục nhập đó.

Đừng sử dụng trình trang trí để:

  • Truyền một phần phụ thuộc đến một NavEntry duy nhất.
  • Cung cấp các phần phụ thuộc có phạm vi rộng hơn ngăn xếp lui.

Trong cả hai trường hợp này, hãy truyền trực tiếp phần phụ thuộc khi tạo NavEntry.

Để xem thêm các đoạn mã ví dụ, hãy xem NavEntryDecorator.