菜单

与 @react-native-menu/menu 兼容的菜单。

Android

iOS

Included in Expo Go

GitHub

npm

更新日志

Recommended version:

~56.0.26

一个与 @react-native-menu/menu 兼容 API 的 MenuView 组件。支持单击（默认）和长按（shouldOpenOnLongPress）两种触发方式。

在内部，这个组件封装了平台特定的 @expo/ui 原语：

Android：锚定到 Pressable 触发器的 Jetpack Compose DropdownMenu。
iOS：用于点击触发器的 SwiftUI Menu，以及用于长按触发器的 SwiftUI ContextMenu。

如果你需要更底层的控制，请直接使用这些原语。

安装

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.

从 `@react-native-menu/menu` 迁移

将导入从 import { MenuView } from '@react-native-menu/menu' 更新为 import { MenuView } from '@expo/ui/community/menu'。
Android 上的 action.image 与上游不同。@react-native-menu/menu 期望的是一个 drawable 资源名字符串（例如 'ic_menu_add'），并会在 android/app/src/main/res/drawable/ 中解析该资源。这个即插即用版本不会解析 drawable 资源名——请改为传入 ImageSourcePropType（例如，require('@expo/material-symbols/edit.xml')）。在 iOS 上，字符串值会作为 SF Symbol 名称被接受。使用 Icon.select 可以分别为两个平台定义图标，这样未使用的一侧会按平台被 tree-shake 掉。
title 只会在 iOS 上作为分组标题渲染；Android 的 Material DropdownMenu 没有标题插槽。
在 Android 上，MenuView 会将触发器包裹在自己的 Pressable 中以打开菜单，因此你传入作为 children 的 Pressable 上绑定的 onPress/onLongPress 处理器不会触发——外层包装器会抢占该手势。请把该处理器移到你的 onPressAction 分支判断中；如果你需要在触发器上保留独立的点击和长按行为，请直接使用更底层的 DropdownMenu 原语。
命令式的 ref.show() API 仅适用于 Android。SwiftUI 的 Menu/ContextMenu 没有程序化打开 API，因此在 iOS 上该调用不会生效（并会在开发环境中显示一次性警告）。
以下来自 @react-native-menu/menu 的属性不受支持：themeVariant、hitSlop、isAnchoredToRight、subtitle、keepsMenuPresented、preferredElementSize，以及 state: 'mixed'。

基本用法

MenuExample.tsx

import { Icon } from '@expo/ui';
import { MenuView } from '@expo/ui/community/menu';
import { Pressable, Text } from 'react-native';

const editIcon = Icon.select({
  ios: 'pencil',
  android: import('@expo/material-symbols/edit.xml'),
});

const deleteIcon = Icon.select({
  ios: 'trash',
  android: import('@expo/material-symbols/delete.xml'),
});

export default function MenuExample() {
  return (
    <MenuView
      actions={[
        { id: 'edit', title: '编辑', image: editIcon },
        { id: 'delete', title: '删除', image: deleteIcon, attributes: { destructive: true } },
      ]}
      onPressAction={e => console.log(e.nativeEvent.event)}>
      <Pressable>
        <Text>打开菜单</Text>
      </Pressable>
    </MenuView>
  );
}

长按（上下文菜单）

设置 shouldOpenOnLongPress 可将其渲染为上下文菜单。在 Android 上，同一个受控的 DropdownMenu 会通过 Pressable 的 onLongPress 而不是 onPress 打开。在 iOS 上，这会使用 SwiftUI 的 ContextMenu，并将触发器以模糊预览的形式显示出来。

LongPressMenuExample.tsx

import { Icon } from '@expo/ui';
import { MenuView } from '@expo/ui/community/menu';
import { Pressable, Text } from 'react-native';

const copyIcon = Icon.select({
  ios: 'doc.on.doc',
  android: import('@expo/material-symbols/content_copy.xml'),
});

const shareIcon = Icon.select({
  ios: 'square.and.arrow.up',
  android: import('@expo/material-symbols/share.xml'),
});

export default function LongPressMenuExample() {
  return (
    <MenuView
      shouldOpenOnLongPress
      actions={[
        { id: 'copy', title: '复制', image: copyIcon },
        { id: 'share', title: '分享', image: shareIcon },
      ]}
      onPressAction={e => console.log(e.nativeEvent.event)}>
      <Pressable>
        <Text>长按我</Text>
      </Pressable>
    </MenuView>
  );
}

子菜单和内联分组

默认情况下，subactions 会将嵌套操作渲染为子菜单。将父项的 displayInline: true 设置为内联分组，而不是子菜单，这对于分组很有用。在 Android 上，只会显示分隔线（Material 的 DropdownMenu 没有分组原语）。在 iOS 上，父项的 title 会成为分组标题。

SubmenuExample.tsx

import { MenuView } from '@expo/ui/community/menu';
import { Pressable, Text } from 'react-native';

export default function SubmenuExample() {
  return (
    <MenuView
      actions={[
        { id: 'rename', title: '重命名' },
        {
          id: 'sort',
          title: '排序方式',
          subactions: [
            { id: 'sort-name', title: '名称' },
            { id: 'sort-date', title: '日期' },
            { id: 'sort-size', title: '大小' },
          ],
        },
        {
          id: 'share-section',
          title: '分享',
          displayInline: true,
          subactions: [
            { id: 'share-airdrop', title: 'AirDrop' },
            { id: 'share-message', title: '信息' },
          ],
        },
      ]}
      onPressAction={e => console.log(e.nativeEvent.event)}>
      <Pressable>
        <Text>打开菜单</Text>
      </Pressable>
    </MenuView>
  );
}

带勾选标记的切换项

将 state 设为 'on' 或 'off'，可将操作渲染为可切换项；开启时会显示前置勾选标记。选择该操作会触发 onPressAction，调用方负责更新状态。

ToggleMenuExample.tsx

import { MenuView } from '@expo/ui/community/menu';
import { useState } from 'react';
import { Pressable, Text } from 'react-native';

export default function ToggleMenuExample() {
  const [pinned, setPinned] = useState(false);
  return (
    <MenuView
      actions={[{ id: 'pin', title: '置顶', state: pinned ? 'on' : 'off' }]}
      onPressAction={e => {
        if (e.nativeEvent.event === 'pin') setPinned(p => !p);
      }}>
      <Pressable>
        <Text>{pinned ? '已置顶' : '未置顶'}</Text>
      </Pressable>
    </MenuView>
  );
}

API

import { MenuView } from '@expo/ui/community/menu';

Component

`MenuView`

Android

iOS

Type: React.Element<MenuComponentProps & { ref: Ref<MenuComponentRef> }>

A drop-in replacement for @react-native-menu/menu's MenuView. Wrap any trigger view; long-pressing or tapping (per shouldOpenOnLongPress) shows a popup menu built from the actions tree.

On Android, renders via Compose's DropdownMenu anchored to a Pressable.
On iOS, renders via SwiftUI's Menu (tap) or ContextMenu (long-press).
On web, the trigger renders the trigger but actions do not fire; a one-time console.warn is emitted.

Props

`actions`

Android

iOS

Type: MenuAction[]

The actions to display in the menu.

`children`

Android

iOS

Optional • Type: ReactNode

Trigger view. Long-pressing or tapping (per shouldOpenOnLongPress) opens the menu.

`onCloseMenu`

Android

Optional • Type: () => void

Callback invoked when the menu closes (either via dismissal or after an action fires).

On Android, fires from the controlled DropdownMenu's dismiss path. On iOS, SwiftUI Menu/ContextMenu do not expose a close hook in a way we can forward, so this is not fired there.

`onOpenMenu`

Android

Optional • Type: () => void

Callback invoked when the menu opens.

On Android, fires when the trigger's tap/long-press flips expanded to true. On iOS, SwiftUI Menu/ContextMenu do not expose an open hook, so this is not fired there.

`onPressAction`

Android

iOS

Optional • Type: (event: NativeActionEvent) => void

Callback invoked when a menu action is selected.

`shouldOpenOnLongPress`

Android

iOS

Optional • Type: boolean • Default: false

When true, the menu opens on long-press of the trigger instead of a single tap.

`style`

Android

iOS

Optional • Type: StyleProp<ViewStyle>

Style applied to the trigger wrapper.

`testID`

Android

iOS

Optional • Type: string

Test identifier passed through to the trigger view.

`title`

iOS

Optional • Type: string

Menu title shown at the top of the menu.

Types

`MenuAction`

Android

iOS

A single action inside a MenuView. Compatible with @react-native-menu/menu.

Property	Type	Description
attributes(optional)	`MenuAttributes`	Visual/behavioral flags.
displayInline(optional)	`boolean`	When `true` and `subactions` is present, renders the children as an inline section inside the parent menu (with this action's `title` as the section header on iOS).
id(optional)	`string`	Identifier passed back via `onPressAction.nativeEvent.event` when this action is selected. Defaults to `title` if omitted.
image(optional)	`SFSymbol \| ImageSourcePropType`	Icon to render beside the action label. When an `SFSymbol` name (e.g. `'trash'`), rendered on iOS only. Not rendered on Android — pass an `ImageSourcePropType` instead to show an icon there. When an `ImageSourcePropType` (e.g. `require('./trash.xml')` or `{ uri: '...' }`), rendered on Android via Compose `Icon`. Ignored on iOS; SwiftUI menus only accept SF Symbol names for built-in `Menu`/`Button` labels.
imageColor(optional)	`ColorValue`	Tint color applied to the action's icon. Visually applied on Android via the leading `Icon`'s tint. On iOS, the value is accepted but may not render: SwiftUI's `Menu`/`ContextMenu` draw their items via the system menu UI, which ignores per-item color modifiers.
state(optional)	`MenuState`	Selection state. When `'on'`, the action renders a checkmark.
subactions(optional)	`MenuAction[]`	Nested actions. Without `displayInline`, renders as a submenu; with `displayInline: true`, renders as an inline section.
title	`string`	Action label shown in the menu.
titleColor(optional)	`ColorValue`	Only for: Android Text color of the action label.

`MenuAttributes`

Android

iOS

Visual and behavioral attributes of a menu action. Compatible with @react-native-menu/menu.

Property	Type	Description
destructive(optional)	`boolean`	Renders the action with a destructive style (red text/icon).
disabled(optional)	`boolean`	Disables the action so it can't be activated.
hidden(optional)	`boolean`	Hides the action from the menu.

`MenuComponentRef`

Android

iOS

Imperative handle exposed by MenuView via ref. Compatible with @react-native-menu/menu's ref.show() API.

Property	Type	Description
show	`() => void`	Only for: Android Programmatically open the menu. On Android, opens the anchored `DropdownMenu` (equivalent to the user tapping the trigger). On iOS this is a no-op — SwiftUI `Menu`/`ContextMenu` have no programmatic open API; a one-time `console.warn` is emitted in development.

`MenuState`

Android

iOS

Literal type: string

Selection state for a menu action. 'on' renders a checkmark; 'off' doesn't.

Acceptable values are: 'on' | 'off'

`NativeActionEvent`

Android

iOS

Event payload delivered to onPressAction when an action is selected. Compatible with @react-native-menu/menu.

Property	Type	Description
nativeEvent	`{ event: string }`	-

菜单

安装

从 @react-native-menu/menu 迁移

基本用法

长按（上下文菜单）

子菜单和内联分组

带勾选标记的切换项

API

Component

MenuView

Props

actions

children

onCloseMenu

onOpenMenu

onPressAction

shouldOpenOnLongPress

style

testID

title

Types

MenuAction

MenuAttributes

MenuComponentRef

MenuState

NativeActionEvent

从 `@react-native-menu/menu` 迁移

`MenuView`

`actions`

`children`

`onCloseMenu`

`onOpenMenu`

`onPressAction`

`shouldOpenOnLongPress`

`style`

`testID`

`title`

`MenuAction`

`MenuAttributes`

`MenuComponentRef`

`MenuState`

`NativeActionEvent`