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

工具提示

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

Android

GitHub

npm

更新日志

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

安装

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.

用法

简单提示框

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

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, 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>已通过编程方式显示！</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>
    </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: React.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.