도움말

도움말을 사용하여 버튼이나 기타 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"
            )
        }
    }
}

코드에 관한 핵심 사항

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

결과

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

하트 아이콘 위에 표시된 '즐겨찾기에 추가'라는 텍스트가 포함된 한 줄 도움말 도움말은 마우스를 가져가거나 길게 누르면 표시됩니다.
그림 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"
            )
        }
    }
}

코드에 관한 핵심 사항

  • TooltipBox은 사용자 상호작용의 이벤트 리스너를 처리하고 이에 따라 TooltipState을 업데이트합니다. TooltipState가 도움말을 표시해야 함을 나타내면 도움말 람다가 실행되고 TooltipBox이 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)
                        }
                    }
                },
            ) {
                Text(richTooltipText)
            }
        },
        state = tooltipState
    ) {
        IconButton(onClick = {
            coroutineScope.launch {
                tooltipState.show()
            }
        }) {
            Icon(
                imageVector = Icons.Filled.Camera,
                contentDescription = "Open camera"
            )
        }
    }
}

코드에 관한 핵심 사항

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

결과

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

'맞춤 리치 툴팁'이라는 제목과 닫기 버튼이 있는 여러 줄 툴팁 도움말이 카메라 아이콘에 고정되어 있습니다.
그림 4. 카메라 아이콘에 고정된 닫기 작업이 있는 맞춤 리치 툴팁

추가 리소스