菜单

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

Android

iOS

Included in Expo Go

GitHub

npm

更新日志

Recommended version:

~57.0.18

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

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

Android: Jetpack Compose 下拉菜单锚定到内部的 Pressable 触发器。
iOS: SwiftUI 菜单用于点击触发，以及 SwiftUI 上下文菜单用于长按触发。

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

安装

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 上该调用是 no-op（并会在开发环境中提示一次警告）。
以下来自 @react-native-menu/menu 的 props 不受支持：themeVariant、hitSlop、isAnchoredToRight、subtitle、keepsMenuPresented、preferredElementSize，以及 state: 'mixed'。

基本用法

将任意视图作为触发器传入。MenuView 会自动附加其自身的点击或长按处理。

MenuExample.tsx

import { Icon } from '@expo/ui';
import { MenuView } from '@expo/ui/community/menu';
import { Text, useColorScheme, View } 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() {
  const colorScheme = useColorScheme();
  return (
    <MenuView
      actions={[
        { id: 'edit', title: '编辑', image: editIcon },
        { id: 'delete', title: '删除', image: deleteIcon, attributes: { destructive: true } },
      ]}
      onPressAction={e => console.log(e.nativeEvent.event)}>
      <View>
        <Text style={{ color: colorScheme === 'dark' ? '#FFFFFF' : '#000000' }}>打开菜单</Text>
      </View>
    </MenuView>
  );
}

长按（上下文菜单）

将 shouldOpenOnLongPress 设置为 true，以以上下文菜单形式渲染。在 Android 上，同一个受控的 DropdownMenu 会在长按触发器时打开，而不是轻触。在 iOS 上，这使用了 SwiftUI 的 ContextMenu，并将触发器显示为模糊预览。

LongPressMenuExample.tsx

import { Icon } from '@expo/ui';
import { MenuView } from '@expo/ui/community/menu';
import { Text, useColorScheme, View } 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() {
  const colorScheme = useColorScheme();
  return (
    <MenuView
      shouldOpenOnLongPress
      actions={[
        { id: 'copy', title: '复制', image: copyIcon },
        { id: 'share', title: '分享', image: shareIcon },
      ]}
      onPressAction={e => console.log(e.nativeEvent.event)}>
      <View style={{ padding: 8 }}>
        <Text style={{ color: colorScheme === 'dark' ? '#FFFFFF' : '#000000' }}>长按我</Text>
      </View>
    </MenuView>
  );
}

子菜单和内联分组

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

SubmenuExample.tsx

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

export default function SubmenuExample() {
  const colorScheme = useColorScheme();
  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: '隔空投送' },
            { id: 'share-message', title: '信息' },
          ],
        },
      ]}
      onPressAction={e => console.log(e.nativeEvent.event)}>
      <View>
        <Text style={{ color: colorScheme === 'dark' ? '#FFFFFF' : '#000000' }}>打开菜单</Text>
      </View>
    </MenuView>
  );
}

带勾选标记的切换项

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

ToggleMenuExample.tsx

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

export default function ToggleMenuExample() {
  const colorScheme = useColorScheme();
  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);
      }}>
      <View>
        <Text style={{ color: colorScheme === 'dark' ? '#FFFFFF' : '#000000' }}>
          {pinned ? '已置顶' : '未置顶'}
        </Text>
      </View>
    </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`