工具提示

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

Android

Included in Expo Go

GitHub

npm

更新日志

Recommended version:

~57.0.0

Expo UI Tooltip 与官方的 Jetpack Compose Tooltip API 保持一致。TooltipBox 包裹锚点内容并显示提示。提示内容通过 TooltipBox.PlainTooltip 或 TooltipBox.RichTooltip 复合组件提供，它们分别对应 PlainTooltip 和 RichTooltip。Tooltip 可以通过长按触发，也可以通过 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`

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.