React Native iOS上下文菜单库全解析：react-native-ios-context-menu

React Native iOS上下文菜单库全解析：react-native-ios-context-menu

在原生 iOS 应用中，从 iOS 13 开始，系统提供了类似于 macOS “右键菜单”的 Context Menu（上下文菜单）功能，用户长按控件即可弹出菜单，支持预览（Preview）与弹出（Pop）交互，大大提升了交互体验。对于 React Native 开发者而言，react-native-ios-context-menu 库提供了一个方便的桥接层，让我们可以在 RN 中轻松调用 iOS 原生的 Context Menu。本篇教程将从以下几个方面进行全方位剖析，帮助你快速掌握该库的安装、用法与高级定制，配有详尽的代码示例与图解，便于快速上手。

背景与概述
库安装与原生配置
基本用法示例
API 详解与常用属性
自定义菜单项与图标
预览（Preview）与弹出（Pop）交互
与 React Native 组件结合的最佳实践
常见问题排查与优化建议

一、背景与概述

1.1 iOS 原生 Context Menu 简介

Context Menu 是 iOS 13 推出的特性，长按某个视图（UIView）时，会弹出一个浮层菜单，包含菜单项以及预览内容。
其核心原生 API 基于 UIContextMenuInteraction，可以实现：
1. Preview（预览）：用户轻触并按住时，下方会弹出一个“小预览窗口”（如照片、文档预览等）。
2. Pop（弹出）：当用户从 Preview 向上滑动或重按时，进入“Pop”状态，打开全屏或自定义视图。
开发者需实现 UIContextMenuInteractionDelegate 的回调，创建菜单项 (UIAction、UIMenu 等)，并提供一个 PreviewProvider（返回一个 UIViewController）以显示预览。

1.2 React Native 下的需求

在 React Native 中，默认并没有对 iOS Context Menu 提供封装。传统的长按交互往往仅用于触发 onLongPress 事件，缺少原生的预览与弹出能力。react-native-ios-context-menu 库弥补了这一空缺，让我们能在 RN 层优雅地使用 Context Menu，主要特点：

零侵入式：通过一个高阶组件（HOC）或 ContextMenuView 包裹任意 RN 组件，即可让其支持原生 Context Menu。
自定义灵活：支持设置菜单标题、Icon、菜单项子标题、自定义颜色等，还可自定义预览组件。
完美契合 iOS 设计语言：弹出的菜单风格与系统原生保持一致，用户体验更佳。
可以在 macOS Catalyst 下使用，对支持 iOS 13+ 的平台通用。

二、库安装与原生配置

下面以 React Native 0.64+ 项目为例，介绍如何安装与配置 react-native-ios-context-menu。

2.1 安装依赖

在项目根目录运行：

# 使用 npm
npm install react-native-ios-context-menu

# 或者使用 yarn
yarn add react-native-ios-context-menu

该库基于 CocoaPods 进行 iOS 原生依赖管理，安装后需要在 iOS 目录执行：

cd ios
pod install --repo-update

注意：如未安装 CocoaPods，请先参考 CocoaPods 官方安装文档完成安装。

2.2 iOS 原生配置

打开 Xcode 项目
执行 pod install 后，会在 ios 目录生成 .xcworkspace，请从此文件打开 Xcode：
```
open ios/YourApp.xcworkspace
```
自动链接
在 RN 0.60 及以上版本，react-native-ios-context-menu 已支持自动链接（Autolinking），无需手动修改 AppDelegate.m 或其他文件。
最低 iOS 版本要求
该库基于 Context Menu API，仅需将 target iOS 版本设置为 iOS 13.0+。在 Xcode 左侧选中项目 → TARGETS → General → Deployment Info → 将 iOS Deployment Target 设置为 13.0 或以上。
Swift 支持
如果你的项目使用 Objective-C 编写，也无需任何额外配置。若想在 Swift 代码中使用，可在 Bridging-Header.h 中引入：
```
#import <react_native_ios_context_menu/ContextMenuView-Swift.h>
```
然后就可以在 Swift 文件中使用 ContextMenuView。通常对 RN 应用而言，这一步可忽略，使用 JavaScript 层即可。

三、基本用法示例

安装配置完成后，在 RN 层可以通过两种方式使用该库：

高阶组件（HOC）：使用 withContextMenu 包裹任意组件。
专用组件：使用 ContextMenuView 作为容器，包裹内部子组件。

下面分别演示这两种方式的简单入门示例。

3.1 使用 `ContextMenuView` 包裹组件

ContextMenuView 是库提供的核心组件，用于包裹任意 RN 组件并赋予其 Context Menu 能力。

// App.js
import React from 'react';
import { View, Text, Image, StyleSheet } from 'react-native';
import { ContextMenuView } from 'react-native-ios-context-menu';

export default function App() {
  return (
    <View style={styles.container}>
      <ContextMenuView
        style={styles.menuButton}
        menuConfig={{
          menuTitle: '操作选项',
          menuItems: [
            {
              actionKey: 'key-like',
              actionTitle: '👍 点赞',
            },
            {
              actionKey: 'key-share',
              actionTitle: '🔗 分享',
            },
            {
              actionKey: 'key-delete',
              actionTitle: '🗑️ 删除',
              actionSubtitle: '永久删除该项目',
              menuAttributes: ['destructive'], // 红色高亮
            },
          ],
        }}
        onPressMenuItem={({ nativeEvent }) => {
          const { actionKey } = nativeEvent;
          console.log('Selected action:', actionKey);
          // 根据 actionKey 执行对应操作
        }}
      >
        {/* 被包裹的内容，将会响应长按弹出上下文菜单 */}
        <View style={styles.content}>
          <Image
            source={{ uri: 'https://via.placeholder.com/150' }}
            style={styles.image}
          />
          <Text>长按我弹出菜单</Text>
        </View>
      </ContextMenuView>
    </View>
  );
}

const styles = StyleSheet.create({
  container: { flex: 1, justifyContent: 'center', alignItems: 'center' },
  menuButton: {
    // 必须设置宽高，否则菜单不会正确定位
    width: 200,
    height: 200,
  },
  content: {
    flex: 1,
    justifyContent: 'center',
    alignItems: 'center',
  },
  image: { width: 150, height: 150, marginBottom: 8 },
});

关键点说明

menuConfig
- menuTitle：菜单顶部标题，可选。
- menuItems：一个数组，每个元素表示一个菜单项。
  - actionKey（必填）：该项的唯一标识，点击后会随 nativeEvent 传回。
  - actionTitle（必填）：展示给用户的文本，可内嵌 Emoji。
  - actionSubtitle（可选）：菜单项下方的二级描述文本。
  - menuAttributes（可选）：一个字符串数组，可传入系统支持的属性，如：
    - "destructive"：红色高亮，用于删除等危险操作；
    - "disabled"：禁用该菜单项，变灰且无法点击；
    - "hidden"：隐藏该菜单项。
  - icon（可选）：可传入一个系统或自定义 Icon（后面章节详解）。
onPressMenuItem
- 监听回调，当用户点击任意菜单项时触发，并返回 nativeEvent.actionKey。可在此回调中结合业务逻辑执行操作（如跳转、分享等）。
被包裹的组件
- 任何 RN 组件都可以作为 ContextMenuView 的子组件。
- 必须给 ContextMenuView 设置宽高，否则长按区域无法正确捕获触摸事件，菜单无法弹出。

3.2 使用 HOC `withContextMenu`

如果你不想在 JSX 中显式使用 ContextMenuView，可以使用高阶组件（HOC）方式，将菜单能力注入到一个已有组件中。

// MyButton.js
import React from 'react';
import { TouchableOpacity, Text, StyleSheet } from 'react-native';
import { withContextMenu } from 'react-native-ios-context-menu';

// 普通按钮组件
const Button = ({ title, onPress }) => (
  <TouchableOpacity style={styles.btn} onPress={onPress}>
    <Text style={styles.btnText}>{title}</Text>
  </TouchableOpacity>
);

// 包裹 HOC，注入上下文菜单能力
const ButtonWithMenu = withContextMenu(Button);

// App.js
import React from 'react';
import { View } from 'react-native';
import ButtonWithMenu from './MyButton';

export default function App() {
  return (
    <View style={{ flex: 1, justifyContent: 'center', alignItems: 'center' }}>
      <ButtonWithMenu
        title="长按我有菜单"
        menuConfig={{
          menuTitle: '按钮菜单',
          menuItems: [
            { actionKey: 'edit', actionTitle: '✏️ 编辑' },
            { actionKey: 'close', actionTitle: '❌ 关闭' },
          ],
        }}
        onPressMenuItem={({ nativeEvent }) => {
          console.log('按钮菜单项被选中：', nativeEvent.actionKey);
        }}
        onPress={() => {
          console.log('按钮点击事件');
        }}
      />
    </View>
  );
}

const styles = StyleSheet.create({
  btn: {
    paddingHorizontal: 24,
    paddingVertical: 12,
    backgroundColor: '#007AFF',
    borderRadius: 8,
  },
  btnText: {
    color: '#fff',
    fontSize: 16,
  },
});

HOC 方式说明

withContextMenu(Component)
- 返回一个新的组件，该组件会在内部用 ContextMenuView 包裹原组件。
- 保留原组件的所有 props，并额外支持 menuConfig、onPressMenuItem 等新属性。
使用场景
- 当你希望给已有组件（如按钮、列表项等）快速添加上下文菜单功能，无需代码侵入，只需 HOC 包裹。

四、API 详解与常用属性

下面对 ContextMenuView 和 withContextMenu 提供的所有 Props 进行逐项讲解，帮助你更好地掌握该库的灵活配置能力。

4.1 `ContextMenuView` 所有 Props

属性名称	类型	说明	默认值
`menuConfig`	`ContextMenuConfig` 对象	必需。定义菜单的标题与菜单项数组。	无默认，需要传入
`onPressMenuItem`	`(event) => void`	用户点击某个菜单项后的回调，`event.nativeEvent.actionKey` 即菜单项 key。	`undefined`
`onMenuDidShow`	`() => void`	当菜单成功弹出时触发。	可选，`undefined`
`onMenuWillShow`	`() => void`	当菜单即将弹出时触发。	`undefined`
`onMenuDidClose`	`() => void`	当菜单关闭后触发，用于统计或做页面刷新等。	`undefined`
`onMenuWillClose`	`() => void`	当菜单即将关闭时触发。	`undefined`
`disabled`	`boolean`	如果为 `true`，则禁用上下文菜单（长按时不会弹出）。	`false`
`previewConfig`	`PreviewConfig` 对象（可选）	定义“预览”视图，包括一个 React 组件，用于 Preview（Peek）阶段。	`undefined`
`style`	`ViewStyle`	控制外层 `View` 样式，必须设置宽高，否则看不到菜单。	无默认，需要传入
`...其他 ViewProps`	`ViewProps`	继承自 React Native 的 `View`，如 `testID`、`accessible` 等。	—

4.1.1 `ContextMenuConfig` 详情

type ContextMenuConfig = {
  menuTitle?: string;            // 可选：菜单顶部大标题
  menuItems: ContextMenuItem[];  // 必需：菜单项数组，至少一项
  menuOptions?: {
    // iOS 14+ 特性：可定义菜单风格等，
    // 例如, {'preserveMenuPosition': true} 保持弹出位置。
    preserveMenuPosition?: boolean;
    tintColor?: string;           // 整体菜单的基调色
  };
};

4.1.2 `ContextMenuItem` 详情

type ContextMenuItem = {
  actionKey: string;            // 必需：唯一标识
  actionTitle: string;          // 必需：显示文本
  actionSubtitle?: string;      // 可选：副标题（小字）
  menuAttributes?: ('destructive' | 'disabled' | 'hidden')[];  
  // 可选：一个数组，可包含'menuAttributes'枚举值，实现红色高亮、禁用或隐藏
  icon?: ContextMenuIcon;       // 可选：菜单项图标（系统或自定义资源）
  discoverabilityTitle?: string; // 可选：VoiceOver 朗读提示
};

menuAttributes
- 'destructive'：菜单项文字变红，提示危险操作，如“删除”。
- 'disabled'：菜单项禁用，文字变灰，无法点击。
- 'hidden'：完全隐藏该菜单项，不在菜单中显示（可用于动态控制显示逻辑）。
discoverabilityTitle
- 为无障碍（VoiceOver）提供额外提示文本，在无障碍模式下会朗读这个字段。

4.1.3 `ContextMenuIcon` 详情

type ContextMenuIcon =
  | { type: 'system'; systemName: string; } // 使用 SF Symbols 系统图标，例如 'trash', 'square.and.arrow.up'
  | { type: 'custom'; uri: string; width?: number; height?: number; }; 
  // 自定义图标，可使用本地或网络图片。width/height 可选，默认为 24*24。

系统图标
- iOS 原生的 SF Symbols 图标，使用 systemName 指定图标名称，例如：
  - 'trash' → 垃圾桶图标
  - 'square.and.arrow.up' → 分享图标
  - 'heart.fill' → 实心爱心
- 系统图标会跟随 iOS 主题（浅色/深色）显示。
自定义图标
- 定义 type: 'custom'，uri 可以是网络 URL 或 RN 中 require('./icon.png') 本地资源引用，支持远程资源。
- 建议指定 width、height，否则默认为 24×24。

4.1.4 `PreviewConfig` 详情

type PreviewConfig = {
  previewType?: 'CUSTOM' | 'ICON' | 'TITLE';  
  // iOS 16+ 支持：'CUSTOM' 自定义组件；'ICON' 图标预览；'TITLE' 文本预览
  previewSize?: 'SMALL' | 'MEDIUM' | 'LARGE'; // 预览尺寸
  previewBackgroundColor?: string;            // 预览背景色
  renderPreview: () => React.ReactNode;       // **必需**：返回一个 React 组件，用于 “Preview” 阶段
};

renderPreview
- 返回一个 React 元素，库会将其渲染为一个原生 UIView 并嵌入 Preview 中。
- 这个组件内部可以是任意 RN 组件，例如 Image、Text、自定义布局等。
previewSize
- 'SMALL'：预览尺寸较小；
- 'MEDIUM'：中等；
- 'LARGE'：大尺寸，适合图片或地图等。
previewType（iOS 16+ 新增）
- 可选：对于仅需展示图标或纯文本预览，可用 'ICON' 或 'TITLE'。
- 若需要复杂布局，设置为 'CUSTOM' 并实现 renderPreview。

完整水合 Props 示例：

<ContextMenuView
  style={{ width: 120, height: 120 }}
  menuConfig={{
    menuTitle: '操作',
    menuItems: [ /*…*/ ],
    menuOptions: {
      preserveMenuPosition: true,
      tintColor: '#007AFF',
    },
  }}
  previewConfig={{
    previewType: 'CUSTOM',
    previewSize: 'MEDIUM',
    previewBackgroundColor: '#FFF',
    renderPreview: () => (
      <View style={{
        width: 200,
        height: 150,
        backgroundColor: '#FFF',
        borderRadius: 12,
        overflow: 'hidden',
      }}>
        <Image
          source={{ uri: 'https://via.placeholder.com/200x150' }}
          style={{ width: '100%', height: '100%' }}
          resizeMode="cover"
        />
      </View>
    ),
  }}
  onPressMenuItem={({ nativeEvent }) => console.log(nativeEvent.actionKey)}
  onMenuWillShow={() => console.log('菜单即将弹出')}
  onMenuDidShow={() => console.log('菜单已弹出')}
  onMenuWillClose={() => console.log('菜单即将关闭')}
  onMenuDidClose={() => console.log('菜单已关闭')}
  disabled={false}
>
  <Image
    source={{ uri: 'https://via.placeholder.com/120' }}
    style={{ width: 120, height: 120, borderRadius: 8 }}
  />
</ContextMenuView>

4.2 `withContextMenu` 所有 Props

withContextMenu HOC 接受与 ContextMenuView 相同的 Props，只不过需要将它们以属性传递给包裹组件。示例：

const ButtonWithMenu = withContextMenu(Button);

// 使用时：
<ButtonWithMenu
  title="菜单按钮"
  menuConfig={…}
  onPressMenuItem={…}
  style={{ width: 100, height: 40 }}
/>

HOC 会自动将 menuConfig 等新增 Props 转给内部的 ContextMenuView。

五、自定义菜单项与图标

菜单美观度与用户体验很大程度依赖于图标及文字细节。下面详细介绍如何配置并定制菜单项的图标、子标题、颜色等，使得 Context Menu 既原生又有辨识度。

5.1 系统 SF Symbols 图标

iOS 内置丰富的 SF Symbols 图标，可在菜单项中直接使用。示例：

const menuItems = [
  {
    actionKey: 'key-favourite',
    actionTitle: '❤️ 收藏',
    icon: { type: 'system', systemName: 'heart.fill' }, // 实心爱心
  },
  {
    actionKey: 'key-share',
    actionTitle: '🔗 分享',
    icon: { type: 'system', systemName: 'square.and.arrow.up' },
  },
  {
    actionKey: 'key-delete',
    actionTitle: '删除',
    icon: { type: 'system', systemName: 'trash' },
    menuAttributes: ['destructive'], // 红色高亮
  },
];

systemName
- 字符串即 SF Symbols 名称，可从 SF Symbols Gallery 中查找。
自动适配深色模式
- 系统图标会根据 iOS 主题自动变色，无需额外设置。

5.2 自定义图片图标

如果想使用自定义图标（如项目 logo、品牌 icon），可以使用 type: 'custom'，并以 RN require 本地资源或网络 URL 作为 uri：

const menuItems = [
  {
    actionKey: 'key-profile',
    actionTitle: '查看个人主页',
    icon: {
      type: 'custom',
      uri: require('./assets/profile-icon.png'),
      width: 28,
      height: 28,
    },
  },
  {
    actionKey: 'key-settings',
    actionTitle: '设置',
    icon: {
      type: 'custom',
      uri: { uri: 'https://example.com/icons/settings.png' },
      width: 24,
      height: 24,
    },
  },
];

width / height
- 建议与原图像同宽高保持一致，或根据菜单项高度（约 32px）进行缩放，一般不超过 32px，否则会挤压文字布局。
网络 URL
- 可以将 uri 设为网络 URL，但注意网络请求与加载时间。如果图标未及时加载，可能出现空白或延迟显示。
- 推荐在 App 启动时预先下载或使用本地资源以保证流畅体验。

5.3 子标题与属性组合

通过 actionSubtitle 可以在菜单项下方显示一行较小字体的描述。例如：

{
  actionKey: 'key-move',
  actionTitle: '移动到...',
  actionSubtitle: '选择一个收藏夹', // 二级描述
  icon: { type: 'system', systemName: 'folder' },
}

menuAttributes 示例：

{
  actionKey: 'key-logout',
  actionTitle: '退出登陆',
  icon: { type: 'system', systemName: 'power' },
  menuAttributes: ['destructive'], // 红色高亮表示危险操作
}

完整示例

<ContextMenuView
  style={{ width: 200, height: 50 }}
  menuConfig={{
    menuTitle: '示例菜单',
    menuItems: [
      {
        actionKey: 'key-favourite',
        actionTitle: '❤️ 收藏',
        actionSubtitle: '添加到收藏列表',
        icon: { type: 'system', systemName: 'heart' },
      },
      {
        actionKey: 'key-share',
        actionTitle: '🔗 分享',
        actionSubtitle: '分享到其他平台',
        icon: { type: 'system', systemName: 'square.and.arrow.up' },
      },
      {
        actionKey: 'key-settings',
        actionTitle: '⚙️ 设置',
        icon: {
          type: 'custom',
          uri: require('./assets/settings.png'),
          width: 24,
          height: 24,
        },
      },
      {
        actionKey: 'key-logout',
        actionTitle: '退出登陆',
        menuAttributes: ['destructive'],
        icon: { type: 'system', systemName: 'power' },
      },
    ],
    menuOptions: {
      tintColor: '#4B0082', // 紫色基调
    },
  }}
  onPressMenuItem={({ nativeEvent }) =>
    console.log('选择了菜单项：', nativeEvent.actionKey)
  }
>
  <View
    style={{
      flex: 1,
      justifyContent: 'center',
      alignItems: 'center',
      backgroundColor: '#EEE',
      borderRadius: 8,
    }}
  >
    <Text>长按区域打开菜单</Text>
  </View>
</ContextMenuView>

图解：菜单最终效果

┌──────────────────────────────────────────┐
│                  示例菜单               │  ← menuTitle
├──────────────────────────────────────────┤
│ ❤️ 收藏            添加到收藏列表          │  ← 带 SF Symbols 图标 + 子标题
│                                          │
│ 🔗 分享            分享到其他平台          │
│                                          │
│ ⚙️  设置                             │  ← 自定义本地资源图标
│                                          │
│ ❗  退出登陆       (红色高亮 destructive)    │
└──────────────────────────────────────────┘

菜单顶部显示 “示例菜单” 作为大标题。
每项左侧显示 Icon，右侧显示 actionTitle，下方为 actionSubtitle（如果有）。
“退出登陆” 项显示红色高亮，提示危险操作。

六、预览（Preview）与弹出（Pop）交互

Context Menu 最吸引人的功能在于 “Peek & Pop” 交互：即长按时先显示一个小预览视图（Peek），随后用户可以滑动或再按进入详情页面（Pop）。在 react-native-ios-context-menu 中，我们可以通过 previewConfig 属性轻松配置 Preview 视图。

6.1 配置 `previewConfig`

<ContextMenuView
  style={{ width: 200, height: 200 }}
  menuConfig={{ /*…菜单配置*/ }}
  previewConfig={{
    previewType: 'CUSTOM', // 'ICON' 或 'TITLE' 或 'CUSTOM'
    previewSize: 'MEDIUM',  // 'SMALL' | 'MEDIUM' | 'LARGE'
    previewBackgroundColor: '#FFFFFF',
    renderPreview: () => (
      <View
        style={{
          width: 180,
          height: 120,
          backgroundColor: '#333',
          borderRadius: 12,
          overflow: 'hidden',
        }}
      >
        <Image
          source={{ uri: 'https://via.placeholder.com/180x120.png' }}
          style={{ width: '100%', height: '100%' }}
        />
        <Text style={{ color: '#FFF', padding: 8 }}>预览标题</Text>
      </View>
    ),
  }}
  onPressMenuItem={/*…*/}
>
  {/* 被包裹内容 */}
</ContextMenuView>

6.1.1 Preview 交互流程

长按触发 Preview
- 用户长按包裹区域时，会首先出现一个带有阴影的小浮层，这即是“Preview”界面。该浮层显示 renderPreview 返回的内容。
继续按压进入 Pop
- 用户在 Preview 浮层内继续加力（Deep Press 或直接连续长按），则进入“Pop”阶段，此时可根据需要打开一个新页面、导航到详情或者执行某些操作。
松手或滑动取消
- 如果用户在 Peek 阶段松手，则只关闭 Preview 不进入 Pop。
- 若在 Peek 时直接向上滑动到某个菜单项，则会选中该菜单项并触发对应回调，菜单关闭。

6.1.2 `previewType` 含义

'ICON'
- 在 iOS 14+ 将只显示一个默认大小的 SF Symbol 图标，用户无需自定义 renderPreview。
- 例如：
```
previewConfig={{
  previewType: 'ICON',
  previewSize: 'SMALL',
  icon: { type: 'system', systemName: 'photo' },
}}
```

'TITLE'

仅显示一行文本（大标题），不展示图像。

属性：

previewConfig={{
  previewType: 'TITLE',
  previewSize: 'SMALL',
  previewTitle: '预览标题文本',
}}

'CUSTOM'
- 完全自定义预览界面，必须提供 renderPreview。

注意：previewType: 'ICON' / 'TITLE' 目前仅在 iOS 14+ 可用，若需要兼容 iOS 13，请使用 previewType: 'CUSTOM' 自行渲染。

6.1.3 示例：图片 + 文本 Preview

<ContextMenuView
  style={{ width: 200, height: 200, borderRadius: 12, overflow: 'hidden' }}
  menuConfig={/*…*/}
  previewConfig={{
    previewType: 'CUSTOM',
    previewSize: 'LARGE',
    previewBackgroundColor: '#FFF',
    renderPreview: () => (
      <View style={{ flex: 1 }}>
        <Image
          source={{ uri: 'https://via.placeholder.com/200x120' }}
          style={{ width: '100%', height: '60%' }}
          resizeMode="cover"
        />
        <View style={{ padding: 8 }}>
          <Text style={{ fontSize: 16, fontWeight: 'bold' }}>美食预览</Text>
          <Text style={{ marginTop: 4, color: '#666' }}>
            这是一个超棒的餐厅预览描述信息
          </Text>
        </View>
      </View>
    ),
  }}
  onPressMenuItem={({ nativeEvent }) =>
    console.log('Selected:', nativeEvent.actionKey)
  }
>
  <Image
    source={{ uri: 'https://via.placeholder.com/200.png?text=Thumbnail' }}
    style={{ width: 200, height: 200 }}
  />
</ContextMenuView>

用户在 Thumbnail 图像上长按时，会首先弹出一个大预览卡片，包含顶部照片和下方文字。
继续按压会进入“Pop”状态（如果设置了 Pop 视图），否则 Preview 消失。

6.2 Pop 状态处理

在 react-native-ios-context-menu 中，Pop 状态并不会自动为你打开新的页面。你可以在 onPressMenuItem 回调中检查 nativeEvent.key，当用户选中某个菜单项时，根据需要执行导航。例如：

onPressMenuItem={({ nativeEvent }) => {
  const { actionKey } = nativeEvent;
  if (actionKey === 'key-open') {
    // 例如使用 React Navigation 跳转到详情页
    navigation.navigate('DetailScreen', { id: itemId });
  }
  if (actionKey === 'key-delete') {
    // 执行删除逻辑
    deleteItem(itemId);
  }
}}

如果你想直接在 Pop 阶段自动跳转（无需点击菜单项），可结合 onMenuWillShow / onMenuDidShow 回调，配合某个自定义操作标志。但一般推荐尊重用户意图，先弹出 Preview，让用户显式选择菜单项再 Pop。

七、与 React Native 组件结合的最佳实践

以下几点实践经验，可帮助你在项目中更好地使用 react-native-ios-context-menu：

7.1 包裹列表项时的宽高控制

在 FlatList、SectionList 等列表中，常见需求是在长按某个列表项时弹出上下文菜单。示例：

// ItemRow.js
import React from 'react';
import { View, Text, StyleSheet } from 'react-native';
import { ContextMenuView } from 'react-native-ios-context-menu';

export default function ItemRow({ item, onMenuAction }) {
  return (
    <ContextMenuView
      style={styles.rowContainer}
      menuConfig={{
        menuTitle: '操作',
        menuItems: [
          { actionKey: 'edit', actionTitle: '编辑' },
          { actionKey: 'remove', actionTitle: '删除', menuAttributes: ['destructive'] },
        ],
      }}
      onPressMenuItem={({ nativeEvent }) => {
        onMenuAction(item.id, nativeEvent.actionKey);
      }}
    >
      <View style={styles.rowContent}>
        <Text style={styles.rowText}>{item.title}</Text>
      </View>
    </ContextMenuView>
  );
}

const styles = StyleSheet.create({
  rowContainer: {
    // 宽度建议撑满屏幕或固定宽度，高度至少 44pt（系统交互舒适度）
    width: '100%',
    height: 60,
    backgroundColor: '#FFF',
  },
  rowContent: {
    flex: 1,
    justifyContent: 'center',
    paddingHorizontal: 16,
  },
  rowText: {
    fontSize: 16,
  },
});

宽度 width: '100%' 或指定 Dimensions.get('window').width：
- 确保 ContextMenuView 占据完整行宽，长按时菜单能正确弹出在该行中心。
高度至少 44pt（推荐 50–60pt）：
- 符合 iOS 触控规范，长按区域更容易触发，也可避免菜单弹出区域过小导致交互困难。

7.2 与触摸事件的冲突

如果被 ContextMenuView 包裹的内部组件本身也绑定了 onLongPress 或 onPress，可能会与 Context Menu 的长按手势冲突。推荐做法：

仅在外部使用 ContextMenuView
将所有长按交互交给 Context Menu 处理，内部不再绑定长按事件。

使用条件渲染
如果某些列表项不需要 Context Menu，可通过传入 disabled 属性动态判断禁用，例如：

<ContextMenuView
  style={styles.rowContainer}
  menuConfig={someConfig}
  disabled={!item.canLongPress} // 当为 true 时，长按不会触发 Context Menu
  onPressMenuItem={...}
>
  {/* 列表项内容 */}
</ContextMenuView>

7.3 动态控制菜单项显示逻辑

大多数场景下，不同列表项可能需要不同的菜单项组合，可在渲染时根据数据动态构建 menuConfig。示例：

function getMenuItemsForItem(item) {
  const items = [];
  if (item.canEdit) {
    items.push({ actionKey: 'edit', actionTitle: '✏️ 编辑' });
  }
  if (item.canShare) {
    items.push({ actionKey: 'share', actionTitle: '🔗 分享' });
  }
  if (item.canDelete) {
    items.push({
      actionKey: 'delete',
      actionTitle: '🗑️ 删除',
      menuAttributes: ['destructive'],
    });
  }
  return items;
}

<ItemRow
  item={item}
  onMenuAction={(id, key) => handleAction(id, key)}
  menuConfig={{
    menuTitle: `项目：${item.title}`,
    menuItems: getMenuItemsForItem(item),
  }}
/>

这样可以确保根据业务状态（如权限、是否已删除、是否已分享等）动态控制菜单项显示。
如果需要临时隐藏某个菜单项，可在 menuItems 中为其添加 menuAttributes: ['hidden']。

八、常见问题排查与优化建议

在集成 react-native-ios-context-menu 过程中，可能会遇到一些常见问题，下面列举并给出解决思路。

8.1 菜单不弹出

没有正确设置宽高
- ContextMenuView 必须有明确的宽度与高度，否则无法捕获触摸区域。
- 确保 style={{ width: ..., height: ... }} 已生效，或者其父组件约束了尺寸。
iOS 版本过低
- Context Menu 仅支持 iOS 13 及以上。请检查设备或模拟器 iOS 版本。
disabled={true}
- 若误将 disabled 设置为 true，长按时会无响应。
其他手势冲突
- 如果在同一个视图层级绑定了原生 onLongPress、PanResponder 等手势处理，可能导致冲突。可以尝试在 ContextMenuView 内部包裹一个无需任何手势的纯 View，然后在内部做进一步布局。

8.2 菜单样式异常

menuOptions.tintColor 无效
- 只有在 iOS 14 及以上，且 ContextMenuConfig.menuOptions 里 tintColor 才会生效。低版本 iOS 无效果。
部分属性仅在高版本生效
- menuOptions.preserveMenuPosition、previewType: 'ICON'、'TITLE' 等在 iOS 14+ 才支持。请根据 iOS 版本条件性渲染或 fallback 到 CUSTOM。

8.3 预览（Preview）无法显示或卡顿

布局过于复杂
- renderPreview 返回的组件若包含太多子组件，或图片过大，会导致预览渲染卡顿。建议预先将图片缓存至本地，保持 renderPreview 组件轻量化。
previewSize 未正确设置
- 若 previewSize 过小，但你渲染了很大的组件，可能出现裁剪或遮挡。请调整 previewSize 与自定义组件尺寸匹配。
使用网络图片加载慢
- 尽量使用本地资源或先行加载图片，避免网络图片影响 Preview 流畅度。

8.4 菜单项点击回调延迟

大型操作阻塞 JS 线程
- 如果在 onPressMenuItem 中执行耗时操作（如大规模数据处理），会阻塞 JS 线程，导致回调后界面卡顿。建议将耗时操作放到异步任务中（如 setTimeout、InteractionManager.runAfterInteractions 等）。
导航跳转未使用异步
- 如果使用 React Navigation，在菜单回调中直接调用 navigation.navigate，可能瞬间触发 UI 变更。可以在回调中先 console.log 验证，再做导航。

九、总结

本文围绕 react-native-ios-context-menu 库，对 iOS 原生 Context Menu 在 React Native 中的集成与使用进行了全面解析，包含：

背景与概述：介绍 iOS 原生 Context Menu 及 RN 下需求。
安装与原生配置：详细说明了库的安装、CocoaPods 配置、最低 iOS 版本要求等。
基本用法示例：分别演示了使用 ContextMenuView 与 HOC withContextMenu 的入门示例。
API 详解与常用属性：逐项解读 ContextMenuView 的所有 Props、ContextMenuConfig、ContextMenuItem、ContextMenuIcon、PreviewConfig 等。
自定义菜单项与图标：演示如何使用 SF Symbols 系统图标与自定义图片图标，并使用子标题、属性组合等进行精细化定制。
预览（Preview）与弹出（Pop）交互：讲解两阶段交互流程及如何使用 previewConfig 自定义预览内容。
最佳实践：包括在列表项中正确设置宽高、避免手势冲突、动态控制菜单项显示逻辑等建议。
常见问题排查与优化：列举并分析了菜单不弹出、样式异常、预览卡顿、回调延迟等常见问题及解决思路。

通过以上内容，你可以快速在 RN 项目中集成 iOS 原生的上下文菜单功能，让你的 App 在长按交互时不仅能弹出原生风格的菜单，还能承载丰富的 Preview 预览互动，带来更佳的用户体验。如果后续需要支持 Android 或者扩展更多自定义动画效果，可以参考 Android 原生的 ContextMenu，并尝试社区提供的跨平台 Context Menu 库（如 react-native-context-menu-view 等），结合原生模块快速实现更多交互。祝你在 React Native 开发中游刃有余，创造出更生动的用户体验！