expo-share-intent 与 React Navigation v6 集成进阶:ShareIntentProvider 与自定义 linking 配置完整详解

原创2026-11-15 13:33:152,001 阅读

expo-share-intent 与 React Navigation v6 集成进阶:ShareIntentProvider 与自定义 linking 配置完整详解

expo-share-intent 是一款用于 React Native 的 Expo 原生模块,可在 iOS 和 Android 上接收其他应用分享过来的文本、链接、图片、视频和文件。本文以仓库自带的示例工程为例,讲解如何把 expo-share-intent 集成到多页面应用中:用 ShareIntentProvider 全局管理分享状态,再配合自定义 linking 配置,完整覆盖冷启动、应用处于后台等进阶场景。

expo-share-intent 与 React Navigation 集成的示例项目启动画面

1. 为什么多页面应用需要 ShareIntentProvider

useShareIntent 这个 Hook 只能在单个组件内使用。如果你的应用有多个页面,且需要在其中任意页面读取分享数据(首页、详情页、处理页),就需要一个全局状态——这正是 ShareIntentProvider 的作用。

它在内部封装了 useShareIntent,并把数据注入 React Context,向所有子组件提供以下字段:

字段 含义
isReady 原生模块是否就绪
hasShareIntent 是否检测到了分享内容
shareIntent 解析后的分享数据(text / webUrl / files / meta)
resetShareIntent 重置并清空分享数据
error 错误信息

Provider 之内的任何页面都可以通过 useShareIntentContext() 一行代码取到数据,无需层层传递 props。实现源码见 src/ShareIntentProvider.tsx。

⚠️ 关键规则:把 Provider 放在 App.tsx 的最外层,位于其他 Provider 之前,保证分享数据在其他组件挂载前就已就绪。

2. 环境准备与 ShareIntentProvider 接入步骤

2.1 安装模块并配置 app.json

安装模块与必需的依赖 expo-linking,并在 app.json 中注册插件、声明 URL scheme:

yarn add expo-share-intent
yarn add expo-linking
{
  "scheme": "my-app",
  "plugins": [
    ["expo-share-intent", { "androidIntentFilters": ["text/*", "image/*"] }]
  ]
}

该模块依赖原生代码,无法在 Expo Go 中测试,必须使用自定义 dev client(expo prebuild 后执行 expo run:ios / expo run:android),详见 README.md 的 Installation 部分。

2.2 在 App.tsx 中包裹 ShareIntentProvider

示例工程入口 example/react-navigation/App.tsx 的写法如下:

export default function App() {
  return (
    <ShareIntentProvider
      options={{
        debug: true,
        onResetShareIntent: () => navigationRef.current?.navigate("Home"),
      }}
    >
      <Navigator />
    </ShareIntentProvider>
  );
}

注意 onResetShareIntent 回调:分享数据被重置时自动跳回首页,这是"处理完就复位"的常见技巧。可选参数完整定义在 src/ExpoShareIntentModule.types.ts:debug、resetOnBackground、disabled、scheme、onResetShareIntent。

3. 自定义 linking 配置详解(核心部分)

这是与 React Navigation 集成的难点:分享意图是通过系统 URL / 深度链接机制送达应用的,所以必须自定义 NavigationContainer 的 linking 参数,在三个关键时机把路由重定向到"分享处理页"。完整实现见 example/react-navigation/app/Navigator.tsx。

说明:示例工程当前依赖 React Navigation v7,其 linking API 与 v6 完全兼容,以下配置在 v6 / v7 中写法一致。

3.1 定义路由映射与 URL 前缀

const linking: LinkingOptions<RootStackParamList> = {
  prefixes: [`${scheme}://`, `${PACKAGE_NAME}://`, PREFIX],
  config: {
    initialRouteName: "Home",
    screens: { Home: "home", ShareIntent: "shareintent" },
  },
};

先在路由表中声明一个专门的 ShareIntent 页面作为"分享数据承接页",并让 prefixes 覆盖应用可能出现的全部 URL 前缀,确保链接能被正确匹配。

3.2 getStateFromPath:iOS 冷启动的关键

iOS 首次接收分享内容时,会用一条携带 dataUrl= 标记的 URL 拉起应用。因此需要在 getStateFromPath 中识别该标记并强制跳向分享页:

getStateFromPath(path, config) {
  if (path.includes(`dataUrl=${getShareExtensionKey()}`)) {
    return { routes: [{ name: "ShareIntent" }] };
  }
  return getStateFromPath(path, config);
}

其中 getShareExtensionKey() 是模块导出的工具函数(定义于 src/utils.ts),用于生成当前应用唯一的分享标识。

3.3 subscribe:覆盖"应用处于后台"的场景

如果用户发起分享时应用已在后台运行,系统不会再冷启动它,需要自定义 subscribe 方法,手动订阅三类事件:

  1. iOS 的 Linking url 事件:收到包含 getShareExtensionKey() 的 URL 时,调用 listener 触发跳转;
  2. Android 的 onStateChange 事件:状态变为 pending 时通知导航跳转;
  3. iOS 的 onChange 事件:数据值更新后重新读取初始 URL 并处理。
const shareIntentStateSubscription = ShareIntentModule?.addListener(
  "onStateChange",
  (event) => {
    if (event.value === "pending") {
      listener(`${getScheme()}://shareintent`);
    }
  },
);

方法最后要返回清理函数,移除全部订阅,避免内存泄漏。

3.4 getInitialURL:Android 冷启动的关键

async getInitialURL() {
  const needRedirect = ShareIntentModule?.hasShareIntent(getShareExtensionKey());
  if (needRedirect) {
    return `${Constants.expoConfig?.scheme}://shareintent`;
  }
  return await Linking.getLinkingURL();
}

若原生模块判定存在未处理的分享数据,就返回自定义的 scheme://shareintent URL,再经由 3.1 的路由映射落到 ShareIntent 页面;否则回落到默认深度链接逻辑。

3.5 一张表看懂三大时机

定制函数 覆盖的时机 平台
getInitialURL 携带分享内容冷启动 Android
getStateFromPath dataUrl 形式 URL 冷启动 iOS
subscribe 应用处于后台时收到分享 iOS / Android

4. 用 useShareIntentContext 消费分享数据

进入 ShareIntent 页面后,一行代码即可全局取数:

const { hasShareIntent, shareIntent, resetShareIntent, error } =
  useShareIntentContext();

示例页面 example/react-navigation/app/ShareIntentScreen.tsx 演示了完整消费方式:渲染 text、webUrl(含 og:image 缩略图与 title 元信息)、文件列表,并在处理完成后调用 resetShareIntent() 清空数据。shareIntent 的数据结构定义见 src/ExpoShareIntentModule.types.ts。

5. 常见坑与排错清单

  • 模块找不到 / 收不到分享:确认使用的是 dev client,Expo Go 不含原生代码,可直接用 useShareIntent({ disabled: true }) 临时禁用模块调试其他功能。
  • iOS 首次启动不跳转:检查 getStateFromPath 是否包含 dataUrl=${getShareExtensionKey()} 判断,以及 app.json 中 scheme 与 prefixes 是否一致。
  • 后台分享无响应:确认 subscribe 中三类订阅全部注册,且返回了清理函数。
  • 分享数据不清空:检查 resetOnBackground(默认 true),并在业务代码中适时调用 resetShareIntent()。
  • 版本不匹配:模块版本必须与 Expo SDK 对应(如 SDK 54 对应 v5+、SDK 55 对应 v6+、SDK 57 对应 v8+),对照 README.md 的版本映射表。
  • 调试技巧:Provider 的 options 传入 debug: true,会打印完整的原生事件流日志,定位问题快人一步。

6. 相关文件速查

文件 说明
example/react-navigation/App.tsx 入口:ShareIntentProvider 包裹与选项配置
example/react-navigation/app/Navigator.tsx 自定义 linking 配置完整示例
example/react-navigation/app/ShareIntentScreen.tsx 分享数据承接页
src/ShareIntentProvider.tsx Provider 与 Context 实现
src/useShareIntent.ts 核心 Hook:事件订阅与状态管理
src/utils.ts getScheme / getShareExtensionKey 工具函数
example/react-navigation/app.json 插件与内容类型(Content Types)配置

按照"Provider 全局包裹 + linking 三处定制"的思路完成配置后,无论 iOS 还是 Android,冷启动还是后台分享,你的应用都能可靠地接住每一次分享意图。

登录后查看全文
expo-share-intent