工具提示

Jetpack Compose 工具提示组件，用于在长按时显示上下文信息。

Android

Included in Expo Go

Recommended version:

~57.0.3

Expo UI Tooltip 与官方 Jetpack Compose Tooltip API 相匹配。TooltipBox 封装锚点内容并显示工具提示。工具提示内容通过 TooltipBox.PlainTooltip 或 TooltipBox.RichTooltip 复合组件提供，它们分别对应 PlainTooltip 和 RichTooltip。工具提示可以通过长按触发，或通过 ref 编程方式显示。

🌐 Expo UI Tooltip matches the official Jetpack Compose Tooltip API. TooltipBox wraps anchor content and displays a tooltip. The tooltip content is provided via the TooltipBox.PlainTooltip or TooltipBox.RichTooltip compound components, which match PlainTooltip and RichTooltip respectively. Tooltips can be triggered by long-press or shown programmatically via ref.

Material 3 rich tooltip with title, body, learn more action, and anchor button

安装

🌐 Installation

Terminal

- npx expo install @expo/ui

If you are installing this in an existing React Native app, make sure to install expo in your project.

用法

🌐 Usage

普通工具提示

🌐 Plain tooltip

长按锚点内容以显示工具提示。

🌐 Long-press the anchor content to display the tooltip.

PlainTooltipExample.tsx

import { Host, TooltipBox, Button, Text } from '@expo/ui/jetpack-compose';

export default function PlainTooltipExample() {
  return (
    <Host matchContents>
      <TooltipBox>
        <TooltipBox.PlainTooltip>
          <Text>Add to favorites</Text>
        </TooltipBox.PlainTooltip>
        <Button onClick={() => {}}>
          <Text>Favorite</Text>
        </Button>
      </TooltipBox>
    </Host>
  );
}

带标题和正文的丰富工具提示

🌐 Rich tooltip with title and body

使用 TooltipBox.RichTooltip 配合 Title 和 Text 复合组件模式以获取更详细的上下文信息。

🌐 Use TooltipBox.RichTooltip with Title and Text compound component pattern for more detailed contextual information.

RichTooltipExample.tsx

import { Host, TooltipBox, Button, Text } from '@expo/ui/jetpack-compose';

export default function RichTooltipExample() {
  return (
    <Host matchContents>
      <TooltipBox>
        <TooltipBox.RichTooltip>
          <TooltipBox.RichTooltip.Title>
            <Text>Camera</Text>
          </TooltipBox.RichTooltip.Title>
          <TooltipBox.RichTooltip.Text>
            <Text>Take photos and record videos with your device camera.</Text>
          </TooltipBox.RichTooltip.Text>
        </TooltipBox.RichTooltip>
        <Button onClick={() => {}}>
          <Text>Open Camera</Text>
        </Button>
      </TooltipBox>
    </Host>
  );
}

带操作的丰富工具提示

🌐 Rich tooltip with action

使用 TooltipBox.RichTooltip.Action 添加一个交互操作。使用 isPersistent 以便提示工具保持可见，供用户点击。存在操作槽时，hasAction 会自动派生。

🌐 Add an interactive action with TooltipBox.RichTooltip.Action. Use isPersistent so the tooltip stays visible for the user to tap it. hasAction is automatically derived when an action slot is present.

RichTooltipActionExample.tsx

import { Host, TooltipBox, Button, TextButton, Text } from '@expo/ui/jetpack-compose';

export default function RichTooltipActionExample() {
  return (
    <Host matchContents>
      <TooltipBox isPersistent>
        <TooltipBox.RichTooltip>
          <TooltipBox.RichTooltip.Title>
            <Text>Permissions Required</Text>
          </TooltipBox.RichTooltip.Title>
          <TooltipBox.RichTooltip.Text>
            <Text>This feature requires camera and microphone access.</Text>
          </TooltipBox.RichTooltip.Text>
          <TooltipBox.RichTooltip.Action>
            <TextButton onClick={() => {}}>
              <Text>Learn More</Text>
            </TextButton>
          </TooltipBox.RichTooltip.Action>
        </TooltipBox.RichTooltip>
        <Button onClick={() => {}}>
          <Text>Record Video</Text>
        </Button>
      </TooltipBox>
    </Host>
  );
}

编程方式显示和消失

🌐 Programmatic show and dismiss

使用 ref 可以命令性地 show() 或 dismiss() 工具提示，而无需长按。

🌐 Use a ref to imperatively show() or dismiss() the tooltip without requiring a long-press.

ProgrammaticTooltipExample.tsx

import { useRef } from 'react';
import { Host, TooltipBox, type TooltipBoxRef, Button, Text, Row } from '@expo/ui/jetpack-compose';

export default function ProgrammaticTooltipExample() {
  const tooltipRef = useRef<TooltipBoxRef>(null);

  return (
    <Host matchContents>
      <TooltipBox ref={tooltipRef} isPersistent>
        <TooltipBox.PlainTooltip>
          <Text>Shown programmatically!</Text>
        </TooltipBox.PlainTooltip>
        <Button onClick={() => {}}>
          <Text>Anchor</Text>
        </Button>
      </TooltipBox>
      <Row horizontalArrangement={{ spacedBy: 8 }}>
        <Button onClick={() => tooltipRef.current?.show()}>
          <Text>Show</Text>
        </Button>
        <Button onClick={() => tooltipRef.current?.dismiss()}>
          <Text>Dismiss</Text>
        </Button>
      </Row>
    </Host>
  );
}

应用接口

🌐 API

import { TooltipBox } from '@expo/ui/jetpack-compose';

Component

`TooltipBox`

Type: React.Element<TooltipBoxProps>

A container that wraps anchor content and shows a tooltip on long-press. Provide the tooltip content via TooltipBox.PlainTooltip or TooltipBox.RichTooltip. All other children are the anchor/trigger.

Use ref to imperatively show() or dismiss() the tooltip.

TooltipBoxProps

`children`

Type: ReactNode

Children containing a TooltipBox.PlainTooltip or TooltipBox.RichTooltip slot and the anchor/trigger content. The anchor content triggers the tooltip on long-press.

`enableUserInput`

Optional • Type: boolean • Default: true

Whether user input (long-press, hover) triggers the tooltip.

`focusable`

Optional • Type: boolean • Default: false

Whether the tooltip popup is focusable.

`hasAction`

Optional • Type: boolean

Whether the tooltip contains an action. Affects accessibility and dismiss behavior. When not specified, this is automatically derived from the presence of a RichTooltip.Action slot.

`isPersistent`

Optional • Type: boolean • Default: false

Whether the tooltip persists instead of auto-dismissing after a short timeout.

`modifiers`

Optional • Type: ModifierConfig[]

Modifiers for the component.

`ref`

Optional • Type: Ref<TooltipBoxRef>

Ref to imperatively show/dismiss the tooltip.

Types

`TooltipBoxRef`

Property	Type	Description
dismiss	`() => Promise<void>`	Programmatically dismisses the tooltip.
show	`() => Promise<void>`	Programmatically shows the tooltip.