Chú giải công cụ

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

  • 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 tuỳ chọn.
Chú thích văn bản thuần tuý một dòng được gắn nhãn (1) và chú thích đa dòng có tiêu đề và khối thông tin được gắn nhãn (2).
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. Thông thường, bạn 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ử dụng thành phần kết hợp PlainTooltip hoặc RichTooltip.
    • Sử dụng PlainTooltip để mô tả các thành phần 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 thành phần kết hợp mà chú giải công cụ được neo vào.

Hiển thị 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 hiển thị một chú giải công cụ đơn giản ở trên cùng của một 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ú thích 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) 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 có 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ú 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 ra một chú giải công cụ đơn giản ở trên cùng của một biểu tượng:

Thành phần chú thích một dòng chứa văn bản
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 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 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 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(
                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ẽ hiển thị, lambda chú giải công cụ sẽ thực thi và TooltipBox sẽ hiển thị 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à một 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ẽ hiển thị để 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 tiêu đề và văn bản nội dung. 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 ra một chú giải công cụ đa dạng thức có tiêu đề được đính kèm vào một biểu tượng thông tin:

Chú thích nhiều dòng có tiêu đề
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 hiển thị một thành phần chú thích đa dạng thức có tiêu đề, thao tác tuỳ chỉnh và dấu mũ (mũi tên) tuỳ chỉnh hiển thị ở trên cùng của một 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 hiển thị 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ẽ 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 một 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 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ụ đang 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 thành phần 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 chú giải công cụ.

Kết quả

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

Chú thích nhiều dòng có tiêu đề
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 một biểu tượng máy ảnh.

Tài nguyên khác