도움말

툴팁을 사용하여 버튼이나 기타 UI 요소에 컨텍스트를 추가합니다. 도움말에는 두 가지 유형이 있습니다.

  • 일반 도움말: 아이콘 버튼의 요소 또는 작업을 설명합니다.
  • 리치 도움말: 지형지물의 값을 설명하는 등 더 많은 세부정보를 제공합니다. 제목, 링크, 버튼(선택사항)을 포함할 수도 있습니다.
라벨이 지정된 단일 줄 일반 도움말 팁 (1)과 라벨이 지정된 제목 및 정보 블록이 있는 여러 줄의 리치 도움말 팁 (2)
그림 1. 일반 도움말 (1)과 풍부한 도움말 (2)

API 노출 영역

TooltipBox 컴포저블을 사용하여 앱에 도움말을 구현할 수 있습니다. 다음과 같은 기본 매개변수를 사용하여 TooltipBox 모양을 제어합니다.

  • positionProvider: 앵커 콘텐츠를 기준으로 툴팁을 배치합니다. 일반적으로 TooltipDefaults의 기본 위치 제공업체를 사용하거나 맞춤 위치 지정 로직이 필요한 경우 자체 제공업체를 제공할 수 있습니다.
  • tooltip: 도움말의 콘텐츠가 포함된 컴포저블입니다. 일반적으로 PlainTooltip 또는 RichTooltip 컴포저블을 사용합니다.
    • PlainTooltip를 사용하여 아이콘 버튼의 요소 또는 작업을 설명합니다.
    • RichTooltip를 사용하여 기능의 값을 설명하는 등 추가 세부정보를 제공합니다. 리치 도움말에는 제목, 링크, 버튼(선택사항)이 포함될 수 있습니다.
  • state: 이 도움말의 UI 로직과 요소 상태를 포함하는 상태 홀더입니다.
  • content: 도움말이 고정된 컴포저블 콘텐츠입니다.

일반 도움말 표시

일반 도움말을 사용하여 UI 요소를 간단히 설명합니다. 이 코드 스니펫은 아이콘 버튼 위에 '즐겨찾기에 추가'라는 라벨이 지정된 일반 도움말을 표시합니다.

@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

코드 관련 핵심 사항

  • TooltipBox는 '즐겨찾기에 추가'라는 텍스트가 포함된 간단한 도움말을 생성합니다.
  • IconButton는 아이콘이 있는 클릭 가능한 버튼을 만듭니다.
    • Icon(...)은 버튼 내에 하트 아이콘을 표시합니다.
    • 사용자가 IconButton와 상호작용할 때 '즐겨찾기에 추가'라는 텍스트와 함께 도움말이 표시됩니다. 기기에 따라 사용자는 다음과 같은 방법으로 도움말을 트리거할 수 있습니다.
    • 커서를 아이콘 위로 가져가기
    • 휴대기기에서 아이콘을 길게 누르기

결과

이 예에서는 아이콘 위에 일반 도움말을 표시합니다.

텍스트가 포함된 단일 행 도움말
그림 2. 사용자가 하트 아이콘 위로 마우스를 가져가거나 길게 누르면 표시되는 일반 도움말입니다.

리치 도움말 표시

리치 도움말을 사용하여 UI 요소에 관한 추가 컨텍스트를 제공합니다. 이 예에서는 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

코드 관련 핵심 사항

  • TooltipBox는 사용자 상호작용의 이벤트 리스너를 처리하고 그에 따라 TooltipState를 업데이트합니다. TooltipState가 도움말을 표시해야 한다고 나타내면 도움말 람다가 실행되고 RichTooltip가 표시됩니다. TooltipBox는 콘텐츠와 도움말 모두의 앵커 및 컨테이너 역할을 합니다.
    • 이 경우 콘텐츠는 탭 가능한 작업 동작을 제공하는 IconButton 구성요소입니다. TooltipBox의 콘텐츠에서 길게 누르거나(터치 기기) 마우스 포인터로 마우스를 가져가면 도움말이 표시되어 자세한 정보를 보여줍니다.
  • RichTooltip 컴포저블은 제목과 본문 텍스트를 비롯한 도움말의 콘텐츠를 정의합니다. TooltipDefaults.rememberRichTooltipPositionProvider()는 풍부한 도움말의 배치 정보를 제공합니다.

결과

이 예에서는 정보 아이콘에 제목이 첨부된 리치 도움말을 생성합니다.

제목이 포함된 여러 줄의 도움말 팁
그림 3. 제목과 정보 아이콘이 있는 리치 도움말

리치 도움말 맞춤설정

이 코드 스니펫은 카메라 아이콘 버튼 위에 제목, 맞춤 작업, 맞춤 캐럿 (화살표)이 포함된 풍부한 도움말을 표시합니다.

@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

코드 관련 핵심 사항

  • RichToolTip는 제목과 닫기 작업이 포함된 도움말을 표시합니다.
  • 길게 누르거나 마우스 포인터로 ToolTipBox 콘텐츠 위로 마우스를 가져가 활성화하면 도움말이 약 1초 동안 표시됩니다. 화면의 다른 곳을 탭하거나 닫기 작업 버튼을 사용하여 이 도움말을 닫을 수 있습니다.
  • 닫기 작업이 실행되면 코루틴이 실행되어 tooltipState.dismiss를 호출합니다. 이렇게 하면 도움말이 표시되는 동안 작업 실행이 차단되지 않습니다.
  • onClick = coroutineScope.launch { tooltipState.show() } }는 tooltipState.show를 사용하여 도움말을 수동으로 표시하는 코루틴을 실행합니다.
  • action 매개변수를 사용하면 버튼과 같은 상호작용 요소를 도움말에 추가할 수 있습니다.
  • caretSize 매개변수는 도움말의 화살표 크기를 수정합니다.

결과

이 예에서는 다음을 생성합니다.

제목이 포함된 여러 줄 팁
그림 4. 카메라 아이콘에 고정된 닫기 작업이 있는 맞춤 리치 도움말입니다.

추가 리소스