Chú giải công cụ

Sử dụng chú giải công cụ để thêm bối cảnh vào một nút hoặc phần tử trên giao diện người dùng. Có 2 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 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 thức (2).

Bề mặt 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 có thể kiểm soát giao diện TooltipBox bằng các tham số chính sau:

• positionProvider: Đặt chú giải công cụ liên quan đến nội dung neo. Bạn thường dùng nhà cung cấp vị trí mặc định từ TooltipDefaults hoặc bạn có thể cung cấp nhà cung cấp vị trí riêng 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ụ. Bạn thường 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 (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ú 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 neo vào.

Hiện chú giải công cụ đơn giản

Sử dụng chú giải công cụ đơ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 cho thấy một chú giải công cụ đơn giản ở trên cùng của nút biểu tượng có nhãn "Thêm vào mục ưa 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ụ có văn bản "Thêm vào mục ưa 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 PlainTooltip thành phần kết hợp.
  • Text(plainTooltipText) cho thấy 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 vào bằng biểu tượng.
  • Icon(...) cho thấy biểu tượng trái tim trong nút.
  • Khi người dùng tương tác với IconButton, TooltipBox sẽ cho thấy chú giải công cụ có văn bản "Thêm vào mục ưa 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 những cách sau:
  • Di chuột qua biểu tượng bằng con trỏ
  • 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 cùng của biểu tượng:

Hình 2. 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ú 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 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 chú giải công cụ đa dạng thức nhiều dòng có tiêu đề được neo vào 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 rằng chú giải công cụ sẽ xuất hiện, hàm lambda chú giải công cụ sẽ thực thi và TooltipBox sẽ cho thấy RichTooltip. 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à thành phần IconButton, cung cấp hành vi hành động có thể nhấn. 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ỳ đâu trong nội dung của TooltipBox, chú giải công cụ sẽ xuất hiện để cho thấy 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 văn bản. TooltipDefaults.rememberRichTooltipPositionProvider() cung cấp thông tin định vị cho chú giải công cụ đa dạng thức.

Kết quả

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

Hình 3. Chú giải công cụ đa dạng thức có tiêu đề và 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 cho thấy một chú giải công cụ đa dạng thức có tiêu đề, hành động tuỳ chỉnh và dấu mũ (mũi tên) tuỳ chỉnh xuất hiện ở trên cùng của 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(
                imageVector = Icons.Filled.Camera,
                contentDescription = "Open camera"
            )
        }
    }
}
Tooltips.kt

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

• RichTooltip cho thấy một chú giải công cụ 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ú giải công cụ sẽ xuất hiện 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 nơi khác trên màn hình hoặc sử dụng nút hành động đóng.
• Khi hành động đóng thực thi, hệ thống sẽ khởi chạy một coroutine để gọi tooltipState.dismiss. Điều này xác minh rằng việc thực thi hành động không bị chặn trong khi chú giải công cụ xuất hiện.
• onClick = coroutineScope.launch { tooltipState.show() } } khởi chạy một coroutine để cho thấy 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ư nút.
• Tham số caretSize sửa đổi kích thước mũi tên của chú giải công cụ.

Kết quả

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

Hình 4. Chú giải công cụ đa dạng thức tuỳ chỉnh có hành động đóng được neo vào biểu tượng máy ảnh.

Tài nguyên khác

• Material Design: Chú giải công cụ