This is documentation for the next SDK version. For up-to-date documentation, see the latest version (SDK 57).

工具提示

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

Android

Included in Expo Go

GitHub

npm

更新日志

Expo UI 提示框与官方 Jetpack Compose 提示框 API 保持一致。TooltipBox 包裹锚点内容并显示提示框。提示框内容通过 TooltipBox.PlainTooltip 或 TooltipBox.RichTooltip 组合组件提供，分别对应 PlainTooltip 和 RichTooltip。提示框可以通过长按触发，或通过 ref 以编程方式显示。

安装

Terminal

- npx expo install @expo/ui

- yarn expo install @expo/ui

- pnpm expo install @expo/ui

- bun expo install @expo/ui

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

用法

简单提示框

长按锚点内容以显示提示框。

PlainTooltipExample.tsx

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

export default function PlainTooltipExample() {
  return (
    <Host matchContents>
      <TooltipBox>
        <TooltipBox.PlainTooltip>
          <Text>添加到收藏</Text>
        </TooltipBox.PlainTooltip>
        <Button onClick={() => {}}>
          <Text>收藏</Text>
        </Button>
      </TooltipBox>
    </Host>
  );
}

带标题和正文的富提示框

使用 TooltipBox.RichTooltip 与 Title 和 Text 组合组件模式，以提供更详细的上下文信息。

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>相机</Text>
          </TooltipBox.RichTooltip.Title>
          <TooltipBox.RichTooltip.Text>
            <Text>
              使用设备相机拍摄照片和录制视频。
            </Text>
          </TooltipBox.RichTooltip.Text>
        </TooltipBox.RichTooltip>
        <Button onClick={() => {}}>
          <Text>打开相机</Text>
        </Button>
      </TooltipBox>
    </Host>
  );
}

带操作的富提示框

使用 TooltipBox.RichTooltip.Action 添加一个可交互操作。使用 isPersistent 让提示框保持可见，方便用户点击。只要存在操作槽位，hasAction 就会自动推导。

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>需要权限</Text>
          </TooltipBox.RichTooltip.Title>
          <TooltipBox.RichTooltip.Text>
            <Text>
              此功能需要访问相机和麦克风。
            </Text>
          </TooltipBox.RichTooltip.Text>
          <TooltipBox.RichTooltip.Action>
            <TextButton onClick={() => {}}>
              <Text>了解更多</Text>
            </TextButton>
          </TooltipBox.RichTooltip.Action>
        </TooltipBox.RichTooltip>
        <Button onClick={() => {}}>
          <Text>录制视频</Text>
        </Button>
      </TooltipBox>
    </Host>
  );
}

以编程方式显示和关闭

使用 ref 可以不依赖长按，直接命令式调用 show() 或 dismiss() 来控制提示框。

ProgrammaticTooltipExample.tsx

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

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

  return (
    <Host matchContents>
      <Column verticalArrangement={{ spacedBy: 8 }}>
        <TooltipBox ref={tooltipRef} isPersistent>
          <TooltipBox.PlainTooltip>
            <Text>以编程方式显示！</Text>
          </TooltipBox.PlainTooltip>
          <Button onClick={() => {}}>
            <Text>锚点</Text>
          </Button>
        </TooltipBox>
        <Row horizontalArrangement={{ spacedBy: 8 }}>
          <Button onClick={() => tooltipRef.current?.show()}>
            <Text>显示</Text>
          </Button>
          <Button onClick={() => tooltipRef.current?.dismiss()}>
            <Text>关闭</Text>
          </Button>
        </Row>
      </Column>
    </Host>
  );
}

API

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

Component

`TooltipBox`

Android

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`

Android

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`

Android

Optional • Type: boolean • Default: true

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

`focusable`

Android

Optional • Type: boolean • Default: false

Whether the tooltip popup is focusable.

`hasAction`

Android

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`

Android

Optional • Type: boolean • Default: false

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

`modifiers`

Android

Optional • Type: ModifierConfig[]

Modifiers for the component.

`ref`

Android

Optional • Type: Ref<TooltipBoxRef>

Ref to imperatively show/dismiss the tooltip.

Types

`TooltipBoxRef`

Android

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