expo-share-intent 与 React Navigation v6 集成进阶:ShareIntentProvider 与自定义 linking 配置完整详解
expo-share-intent 与 React Navigation v6 集成进阶:ShareIntentProvider 与自定义 linking 配置完整详解
expo-share-intent 是一款用于 React Native 的 Expo 原生模块,可在 iOS 和 Android 上接收其他应用分享过来的文本、链接、图片、视频和文件。本文以仓库自带的示例工程为例,讲解如何把 expo-share-intent 集成到多页面应用中:用 ShareIntentProvider 全局管理分享状态,再配合自定义 linking 配置,完整覆盖冷启动、应用处于后台等进阶场景。
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,其
linkingAPI 与 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 方法,手动订阅三类事件:
- iOS 的
Linkingurl 事件:收到包含getShareExtensionKey()的 URL 时,调用listener触发跳转; - Android 的
onStateChange事件:状态变为pending时通知导航跳转; - 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,冷启动还是后台分享,你的应用都能可靠地接住每一次分享意图。
