工具提示

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

Android

Included in Expo Go

GitHub

npm

更新日志

Recommended version:

~57.0.18

Expo UI Tooltip 与官方的 Jetpack Compose Tooltip API 保持一致。TooltipBox 包裹锚点内容并显示提示。提示内容通过 TooltipBox.PlainTooltip 或 TooltipBox.RichTooltip 复合组件提供，它们分别对应 PlainTooltip 和 RichTooltip。Tooltip 可以通过长按触发，也可以通过 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>
              Take photos and record videos with your device camera.
            </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>
              This feature requires camera and microphone access.
            </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>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>
      </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.