Chú giải công cụ

Sử dụng bộ sưu tập để sắp xếp ngăn nắp các trang Lưu và phân loại nội dung dựa trên lựa chọn ưu tiên của bạn.

Sử dụng chú giải công cụ để thêm ngữ cảnh vào một nút hoặc thành phần khác trên giao diện người dùng. Có hai loại chú giải công cụ:

• Chú giải công cụ đơn giản: Mô tả các phần tử hoặc hành động của các nút biểu tượng.
• Chú giải công cụ đa dạng: Cung cấp thêm thông tin chi tiết, chẳng hạn như mô tả giá trị của một tính năng. Cũng có thể bao gồm tiêu đề, đường liên kết và nút (không bắt buộc).

Nền tảng API

Bạn có thể sử dụng thành phần kết hợp TooltipBox để triển khai chú giải công cụ trong ứng dụng. Bạn kiểm soát giao diện TooltipBox bằng các thông số chính sau:

• positionProvider: Đặt chú giải công cụ tương ứng với nội dung liên kết. Bạn thường sử dụng trình cung cấp vị trí mặc định từ TooltipDefaults hoặc bạn có thể cung cấp trình cung cấp vị trí của riêng mình nếu cần logic định vị tuỳ chỉnh.
• tooltip: Thành phần kết hợp chứa nội dung của chú giải công cụ. Thông thường, bạn sẽ sử dụng thành phần kết hợp PlainTooltip hoặc RichTooltip.
  • Sử dụng PlainTooltip để mô tả các phần tử hoặc hành động của nút biểu tượng.
  • Sử dụng RichTooltip để cung cấp thêm thông tin chi tiết, chẳng hạn như mô tả giá trị của một tính năng. Chú giải công cụ đa dạng thức có thể bao gồm tiêu đề, đường liên kết và nút tuỳ chọn.
• state: Phần tử giữ trạng thái chứa logic giao diện người dùng và trạng thái phần tử cho chú giải công cụ này.
• content: Nội dung có thể kết hợp mà chú giải công cụ được liên kết.

Hiển thị chú giải công cụ thuần tuý

Sử dụng chú giải công cụ đơn giản để mô tả ngắn gọn một thành phần trên giao diện người dùng. Đoạn mã này hiển thị một chú giải công cụ đơn giản ở đầu nút biểu tượng có nhãn "Thêm vào mục yêu thích":

@Composable
fun PlainTooltipExample(
    modifier: Modifier = Modifier,
    plainTooltipText: String = "Add to favorites"
) {
    TooltipBox(
        modifier = modifier,
        positionProvider = TooltipDefaults.rememberPlainTooltipPositionProvider(),
        tooltip = {
            PlainTooltip { Text(plainTooltipText) }
        },
        state = rememberTooltipState()
    ) {
        IconButton(onClick = { /* Do something... */ }) {
            Icon(
                imageVector = Icons.Filled.Favorite,
                contentDescription = "Add to favorites"
            )
        }
    }
}
Tooltips.kt

Các điểm chính về mã

• TooltipBox tạo một chú giải công cụ đơn giản có văn bản "Thêm vào mục yêu thích".
  • TooltipDefaults.rememberPlainTooltipPositionProvider() cung cấp vị trí mặc định cho chú giải công cụ đơn giản.
  • tooltip là một hàm lambda xác định nội dung của chú giải công cụ bằng cách sử dụng thành phần kết hợp PlainTooltip.
  • Text(plainTooltipText) hiển thị văn bản trong chú giải công cụ.
  • tooltipState kiểm soát trạng thái của chú giải công cụ.
• IconButton tạo một nút có thể nhấp bằng biểu tượng.
  • Icon(...) hiển thị biểu tượng trái tim trong nút.
  • Khi người dùng tương tác với IconButton, chú giải công cụ sẽ hiển thị với văn bản "Thêm vào mục yêu thích". Tuỳ thuộc vào thiết bị, người dùng có thể kích hoạt chú giải công cụ theo các cách sau:
  • Di chuột qua biểu tượng
  • Nhấn và giữ biểu tượng trên thiết bị di động

Kết quả

Ví dụ này tạo một chú giải công cụ đơn giản trên một biểu tượng:

Hiển thị chú giải công cụ đa dạng thức

Sử dụng chú giải công cụ đa dạng thức để cung cấp thêm ngữ cảnh về một thành phần trên giao diện người dùng. Ví dụ này tạo một chú giải công cụ đa dòng có tiêu đề được liên kết với Icon:

@Composable
fun RichTooltipExample(
    modifier: Modifier = Modifier,
    richTooltipSubheadText: String = "Rich Tooltip",
    richTooltipText: String = "Rich tooltips support multiple lines of informational text."
) {
    TooltipBox(
        modifier = modifier,
        positionProvider = TooltipDefaults.rememberRichTooltipPositionProvider(),
        tooltip = {
            RichTooltip(
                title = { Text(richTooltipSubheadText) }
            ) {
                Text(richTooltipText)
            }
        },
        state = rememberTooltipState()
    ) {
        IconButton(onClick = { /* Icon button's click event */ }) {
            Icon(
                imageVector = Icons.Filled.Info,
                contentDescription = "Show more information"
            )
        }
    }
}
Tooltips.kt

Các điểm chính về mã

• TooltipBox xử lý trình nghe sự kiện cho các hoạt động tương tác của người dùng và cập nhật TooltipState cho phù hợp. Khi TooltipState cho biết chú giải công cụ sẽ hiển thị, lambda chú giải công cụ sẽ thực thi và RichTooltip sẽ hiển thị. TooltipBox đóng vai trò là neo và vùng chứa cho cả nội dung và chú giải công cụ.
  • Trong trường hợp này, nội dung là một thành phần IconButton, cung cấp hành vi nhấn được. Khi nhấn và giữ (trên thiết bị cảm ứng) hoặc di chuột qua (như với con trỏ chuột) bất kỳ vị trí nào trong nội dung của TooltipBox, chú giải công cụ sẽ hiển thị để cho biết thêm thông tin.
• Thành phần kết hợp RichTooltip xác định nội dung của chú giải công cụ, bao gồm cả tiêu đề và nội dung. TooltipDefaults.rememberRichTooltipPositionProvider() cung cấp thông tin định vị cho chú giải công cụ đa dạng.

Kết quả

Ví dụ này tạo ra một chú giải công cụ đa dạng thức có tiêu đề đính kèm với biểu tượng thông tin:

Tuỳ chỉnh chú giải công cụ đa dạng thức

Đoạn mã này hiển thị một chú giải công cụ đa dạng với tiêu đề, thao tác tuỳ chỉnh và dấu mũi tên tuỳ chỉnh hiển thị trên nút biểu tượng máy ảnh:

@Composable
fun AdvancedRichTooltipExample(
    modifier: Modifier = Modifier,
    richTooltipSubheadText: String = "Custom Rich Tooltip",
    richTooltipText: String = "Rich tooltips support multiple lines of informational text.",
    richTooltipActionText: String = "Dismiss"
) {
    val tooltipState = rememberTooltipState()
    val coroutineScope = rememberCoroutineScope()

    TooltipBox(
        modifier = modifier,
        positionProvider = TooltipDefaults.rememberRichTooltipPositionProvider(),
        tooltip = {
            RichTooltip(
                title = { Text(richTooltipSubheadText) },
                action = {
                    Row {
                        TextButton(onClick = {
                            coroutineScope.launch {
                                tooltipState.dismiss()
                            }
                        }) {
                            Text(richTooltipActionText)
                        }
                    }
                },
                caretSize = DpSize(32.dp, 16.dp)
            ) {
                Text(richTooltipText)
            }
        },
        state = tooltipState
    ) {
        IconButton(onClick = {
            coroutineScope.launch {
                tooltipState.show()
            }
        }) {
            Icon(
                imageVector = Icons.Filled.Camera,
                contentDescription = "Open camera"
            )
        }
    }
}
Tooltips.kt

Các điểm chính về mã

• RichToolTip hiển thị chú giải công cụ có tiêu đề và thao tác đóng.
• Khi được kích hoạt bằng cách nhấn và giữ hoặc di chuột qua nội dung ToolTipBox, chú giải công cụ sẽ hiển thị trong khoảng một giây. Bạn có thể đóng chú giải công cụ này bằng cách nhấn vào vị trí khác trên màn hình hoặc sử dụng nút hành động đóng.
• Khi thực thi thao tác đóng, một coroutine sẽ được khởi chạy để gọi tooltipState.dismiss. Điều này đảm bảo quá trình thực thi hành động không bị chặn trong khi chú giải công cụ hiển thị.
• onClick = coroutineScope.launch { tooltipState.show() } } khởi chạy một coroutine để hiển thị chú giải công cụ theo cách thủ công bằng tooltipState.show.
• Tham số action cho phép thêm các phần tử tương tác vào chú giải công cụ, chẳng hạn như một nút.
• Tham số caretSize sửa đổi kích thước của mũi tên của chú giải công cụ.

Kết quả

Ví dụ này sẽ tạo ra kết quả sau:

Tài nguyên khác

• Material Design: Cụm từ gợi ý