Giới thiệu về phần lồng ghép cửa sổ

Nền tảng Android chịu trách nhiệm vẽ giao diện người dùng hệ thống, chẳng hạn như thanh trạng thái và thanh điều hướng. Giao diện người dùng hệ thống này sẽ xuất hiện bất kể người dùng đang sử dụng ứng dụng nào.

WindowInsets cung cấp thông tin về giao diện người dùng hệ thống để đảm bảo rằng ứng dụng của bạn vẽ ở đúng khu vực và giao diện người dùng của bạn không bị giao diện người dùng hệ thống che khuất.

Hình 1. Hiển thị tràn viền để vẽ phía sau các thanh hệ thống.

Trên Android 14 (cấp độ API 34) trở xuống, theo mặc định, giao diện người dùng của ứng dụng sẽ không vẽ bên dưới các thanh hệ thống và vết cắt trên màn hình.

Trên Android 15 (cấp độ API 35) trở lên, ứng dụng của bạn sẽ vẽ bên dưới các thanh hệ thống và vết cắt trên màn hình sau khi ứng dụng nhắm đến SDK 35. Điều này giúp mang lại trải nghiệm người dùng liền mạch hơn và cho phép ứng dụng của bạn tận dụng tối đa không gian cửa sổ có sẵn.

Việc hiển thị nội dung phía sau giao diện người dùng hệ thống được gọi là hiển thị tràn viền. Trên trang này, bạn sẽ tìm hiểu về các loại phần lồng ghép, cách hiển thị tràn viền và cách sử dụng các API phần lồng ghép để tạo ảnh động cho giao diện người dùng, đồng thời đảm bảo nội dung của ứng dụng không bị các phần tử giao diện người dùng hệ thống che khuất.

Quan trọng: Chế độ hiển thị tràn viền được thực thi trên Android 15 trở lên sau khi ứng dụng nhắm đến SDK 35. Nếu ứng dụng của bạn chưa hiển thị tràn viền, thì một số phần của ứng dụng có thể bị ẩn và bạn phải xử lý phần lồng ghép. Tuỳ thuộc vào ứng dụng, công việc này có thể quan trọng hoặc không. Thành phần Material 3 Scaffold có thể giảm bớt công việc cần thiết để tương thích với việc thực thi chế độ hiển thị tràn viền trên Android 15. Hãy xem bài viết Tạo thành phần khung hiển thị để giữ giao diện người dùng.

Kiến thức cơ bản về phần lồng ghép

Khi một ứng dụng hiển thị tràn viền, bạn cần đảm bảo rằng nội dung và lượt tương tác quan trọng không bị giao diện người dùng hệ thống che khuất. Ví dụ: nếu một nút được đặt phía sau thanh điều hướng, thì người dùng có thể không nhấp được vào nút đó.

Kích thước của giao diện người dùng hệ thống và thông tin về vị trí đặt giao diện người dùng hệ thống được chỉ định bằng cách sử dụng phần lồng ghép.

Mỗi phần của giao diện người dùng hệ thống có một loại phần lồng ghép tương ứng mô tả kích thước và vị trí của phần đó. Ví dụ: phần lồng ghép thanh trạng thái cung cấp kích thước và vị trí của thanh trạng thái, trong khi phần lồng ghép thanh điều hướng cung cấp kích thước và vị trí của thanh điều hướng. Mỗi loại phần lồng ghép bao gồm 4 kích thước tính bằng pixel: trên cùng, bên trái, bên phải và dưới cùng. Các kích thước này chỉ định khoảng cách mà giao diện người dùng hệ thống mở rộng từ các cạnh tương ứng của cửa sổ ứng dụng. Do đó, để tránh chồng chéo với loại giao diện người dùng hệ thống đó, giao diện người dùng ứng dụng phải được lồng ghép theo số lượng đó.

Các loại phần lồng ghép Android tích hợp này có sẵn thông qua WindowInsets:

WindowInsets.statusBars	Phần lồng ghép mô tả các thanh trạng thái. Đây là các thanh giao diện người dùng hệ thống ở trên cùng chứa biểu tượng thông báo và các chỉ báo khác.
WindowInsets.statusBarsIgnoringVisibility	Phần lồng ghép thanh trạng thái khi chúng xuất hiện. Nếu các thanh trạng thái bị ẩn (do chuyển sang chế độ toàn màn hình tối đa), thì các phần lồng ghép thanh trạng thái chính sẽ trống, nhưng các phần lồng ghép này sẽ không trống.
WindowInsets.navigationBars	Phần lồng ghép mô tả các thanh điều hướng. Đây là các thanh giao diện người dùng hệ thống ở bên trái, bên phải hoặc dưới cùng của thiết bị, mô tả thanh tác vụ hoặc biểu tượng điều hướng. Các thanh này có thể thay đổi trong thời gian chạy dựa trên phương thức điều hướng mà người dùng ưu tiên và tương tác với thanh tác vụ.
WindowInsets.navigationBarsIgnoringVisibility	Phần lồng ghép thanh điều hướng khi chúng xuất hiện. Nếu các thanh điều hướng bị ẩn (do chuyển sang chế độ toàn màn hình tối đa), thì các phần lồng ghép thanh điều hướng chính sẽ trống, nhưng các phần lồng ghép này sẽ không trống.
WindowInsets.captionBar	Phần lồng ghép mô tả kiểu trang trí cửa sổ giao diện người dùng hệ thống nếu ở trong cửa sổ dạng tự do, chẳng hạn như thanh tiêu đề trên cùng.
WindowInsets.captionBarIgnoringVisibility	Phần lồng ghép thanh chú thích khi chúng xuất hiện. Nếu các thanh chú thích bị ẩn, thì các phần lồng ghép thanh chú thích chính sẽ trống, nhưng các phần lồng ghép này sẽ không trống.
WindowInsets.systemBars	Hợp nhất các phần lồng ghép thanh hệ thống, bao gồm thanh trạng thái, thanh điều hướng và thanh chú thích.
WindowInsets.systemBarsIgnoringVisibility	Phần lồng ghép thanh hệ thống khi chúng xuất hiện. Nếu các thanh hệ thống bị ẩn (do chuyển sang chế độ toàn màn hình tối đa), thì các phần lồng ghép thanh hệ thống chính sẽ trống, nhưng các phần lồng ghép này sẽ không trống.
WindowInsets.ime	Phần lồng ghép mô tả khoảng không gian ở dưới cùng mà bàn phím phần mềm chiếm.
WindowInsets.imeAnimationSource	Phần lồng ghép mô tả khoảng không gian mà bàn phím phần mềm chiếm trước ảnh động bàn phím hiện tại.
WindowInsets.imeAnimationTarget	Phần lồng ghép mô tả khoảng không gian mà bàn phím phần mềm sẽ chiếm sau ảnh động bàn phím hiện tại.
WindowInsets.tappableElement	Một loại phần lồng ghép mô tả thông tin chi tiết hơn về giao diện người dùng điều hướng, cho biết khoảng không gian mà hệ thống sẽ xử lý "lượt nhấn" chứ không phải ứng dụng. Đối với các thanh điều hướng trong suốt có tính năng điều hướng bằng cử chỉ, một số phần tử ứng dụng có thể nhấn được thông qua giao diện người dùng điều hướng hệ thống.
WindowInsets.tappableElementIgnoringVisibility	Phần lồng ghép phần tử có thể nhấn khi chúng xuất hiện. Nếu các phần tử có thể nhấn bị ẩn (do chuyển sang chế độ toàn màn hình tối đa), thì các phần lồng ghép phần tử có thể nhấn chính sẽ trống, nhưng các phần lồng ghép này sẽ không trống.
WindowInsets.systemGestures	Phần lồng ghép đại diện cho số lượng phần lồng ghép mà hệ thống sẽ chặn các cử chỉ để điều hướng. Ứng dụng có thể chỉ định theo cách thủ công việc xử lý một số lượng hạn chế các cử chỉ này bằng cách sử dụng Modifier.systemGestureExclusion.
WindowInsets.mandatorySystemGestures	Một tập hợp con của các cử chỉ hệ thống sẽ luôn được hệ thống xử lý và không thể chọn không sử dụng bằng cách sử dụng Modifier.systemGestureExclusion.
WindowInsets.displayCutout	Phần lồng ghép đại diện cho khoảng cách cần thiết để tránh chồng chéo với vết cắt trên màn hình (tai thỏ hoặc lỗ kim).
WindowInsets.waterfall	Phần lồng ghép đại diện cho các khu vực cong của màn hình thác nước. Màn hình thác nước có các khu vực cong dọc theo các cạnh của màn hình, nơi màn hình bắt đầu bao quanh các cạnh của thiết bị.

Các loại này được tóm tắt theo 3 loại phần lồng ghép "an toàn" giúp đảm bảo nội dung không bị che khuất:

• WindowInsets.safeDrawing
• WindowInsets.safeGestures
• WindowInsets.safeContent

Các loại phần lồng ghép "an toàn" này bảo vệ nội dung theo nhiều cách, dựa trên các phần lồng ghép nền tảng cơ bản:

• Sử dụng WindowInsets.safeDrawing để bảo vệ nội dung không được vẽ bên dưới bất kỳ giao diện người dùng hệ thống nào. Đây là cách sử dụng phần lồng ghép phổ biến nhất: để ngăn vẽ nội dung bị giao diện người dùng hệ thống che khuất (một phần hoặc hoàn toàn).
• Sử dụng WindowInsets.safeGestures để bảo vệ nội dung bằng cử chỉ. Điều này giúp tránh các cử chỉ hệ thống xung đột với cử chỉ ứng dụng (chẳng hạn như cử chỉ cho trang tính ở dưới cùng, băng chuyền hoặc trong trò chơi).
• Sử dụng WindowInsets.safeContent làm sự kết hợp của WindowInsets.safeDrawing và WindowInsets.safeGestures để đảm bảo nội dung không bị chồng chéo về mặt hình ảnh và không bị chồng chéo về cử chỉ.