Chú giải công cụ

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

• Chú giải công cụ đơn giản: Mô tả các thành phần hoặc hành động của nút biểu tượng.
• Chú giải công cụ đa dạng thức: 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).

Hình 1. Chú giải công cụ đơn giản (1) và chú giải công cụ đa dạng (2).

Nền tảng API

Bạn có thể sử dụng composable TooltipBox để triển khai chú thích trong ứng dụng. Bạn có thể kiểm soát giao diện của TooltipBox bằng các tham số chính sau:

• positionProvider: Đặt chú thích tương ứng với nội dung neo. Bạn thường sử dụng trình cung cấp vị trí mặc định từ TooltipDefaults hoặc 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: Composable chứa nội dung của chú thích. Bạn thường 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ú thích chi tiết có thể bao gồm tiêu đề, đường liên kết và nút (không bắt buộc).
• 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ú thích này.
• content: Nội dung thành phần kết hợp mà chú thích được liên kết.

Hiển thị chú thích thuần tuý

Sử dụng chú thích đơn giản để mô tả ngắn gọn một phần tử trên giao diện người dùng. Đoạn mã này hiển thị một chú thích đơ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(
                painter = rememberVectorPainter(AppIcons.Favorite),
                contentDescription = "Add to favorites"
            )
        }
    }
}
Tooltips.kt

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

• TooltipBox tạo một chú thích có nội dung "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ú thích 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ú thích.
  • 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 kèm theo 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, TooltipBox sẽ hiển thị chú thích có 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ú thích theo những cách sau:
  • Di chuột lên 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 ra một chú thích đơn giản ở đầu biểu tượng:

Hình 2. Một chú giải công cụ đơn giản xuất hiện khi người dùng di chuột qua hoặc nhấn và giữ biểu tượng trái tim.

Hiện chú thích đa dạng

Sử dụng chú thích đa dạng thức để cung cấp thêm bối cảnh về một phần tử trên giao diện người dùng. Ví dụ này tạo một thành phần chú thích đa dạng thức nhiều dòng có tiêu đề được liên kết với một 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(
                painter = rememberVectorPainter(AppIcons.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 rằng chú thích sẽ xuất hiện, hàm lambda của chú thích sẽ thực thi và TooltipBox sẽ hiển thị RichTooltip. TooltipBox đóng vai trò là điểm neo và vùng chứa cho cả nội dung và chú thích.
  • Trong trường hợp này, nội dung là một thành phần IconButton, cung cấp hành vi hành động có thể nhấn vào. Khi bạn nhấn và giữ (trên thiết bị cảm ứng) hoặc di chuột qua (bằng con trỏ chuột) bất cứ vị trí nào trong nội dung của TooltipBox, chú thích sẽ xuất hiện để hiển thị thêm thông tin.
• Thành phần kết hợp RichTooltip xác định nội dung của chú thích, bao gồm cả tiêu đề và nội dung văn bản. TooltipDefaults.rememberRichTooltipPositionProvider() cung cấp thông tin định vị cho chú thích đa dạng thức.

Kết quả

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

Hình 3. Chú thích chi tiết có tiêu đề và biểu tượng thông tin.

Tuỳ chỉnh chú thích chi tiết

Đoạn mã này hiển thị một chú thích chi tiết có tiêu đề, các thao tác tuỳ chỉnh và một dấu mũ (mũi tên) tuỳ chỉnh hiển thị trên đầu 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)
                        }
                    }
                },
            ) {
                Text(richTooltipText)
            }
        },
        state = tooltipState
    ) {
        IconButton(onClick = {
            coroutineScope.launch {
                tooltipState.show()
            }
        }) {
            Icon(
                painter = rememberVectorPainter(AppIcons.Camera),
                contentDescription = "Open camera"
            )
        }
    }
}
Tooltips.kt

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

• RichTooltip hiển thị chú thích có tiêu đề và hành động đó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 bằng con trỏ chuột), chú thích sẽ xuất hiện trong khoảng một giây. Bạn có thể đóng chú thích 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 hành động đóng được thực thi, hệ thống sẽ khởi chạy một coroutine để gọi tooltipState.dismiss. Thao tác này xác minh rằng quá trình thực thi hành động không bị chặn trong khi chú thích được hiển thị.
• onClick = coroutineScope.launch { tooltipState.show() } } chạy một coroutine để hiện chú thích theo cách thủ công bằng tooltipState.show.
• Tham số action cho phép thêm các thành phần tương tác vào chú thích, chẳng hạn như nút.
• Tham số caretSize sửa đổi kích thước mũi tên của chú thích.

Kết quả

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

Hình 4. Chú thích chi tiết tuỳ chỉnh có thao tác đóng được liên kết với biểu tượng máy ảnh.

Tài nguyên khác

• Material Design: Chú thích