create-react-native-app深度链接处理：路由跳转与参数解析
项目地址: https://gitcode.com/gh_mirrors/cr/create-react-native-app 为什么需要深度链接（Deep Link）？
你是否遇到过这样的场景：用户点击短信中的链接却无法直达App内相关页面，只能先打开App再手动导航？深度链接（Deep Link）技术通过自定义URL Scheme（如yourapp://）或通用链接（Universal Links）解决了这一痛点，让用户体验从"打开App→寻找内容"的多步操作简化为一步直达。本文将基于create-react-native-app框架，详解如何从零实现深度链接的配置、路由跳转与参数解析。
实现流程概览
一、基础配置：URL Scheme与原生工程
1.1 配置URL Scheme
create-react-native-app项目需在app.json中声明URL Scheme：
{
"expo": {
"scheme": "myapp", // 自定义URL Scheme，如"myapp://"
"name": "MyApp",
"slug": "my-app"
}
}
1.2 原生工程配置
iOS配置
需修改ios/MyApp/AppDelegate.m文件，添加URL处理代码：
#import <React/RCTLinkingManager.h>
- (BOOL)application:(UIApplication *)application
openURL:(NSURL *)url
options:(NSDictionary<UIApplicationOpenURLOptionsKey, id> *)options {
return [RCTLinkingManager application:application openURL:url options:options];
}
// 支持Universal Links
- (BOOL)application:(UIApplication *)application
continueUserActivity:(NSUserActivity *)userActivity
restorationHandler:(void (^)(NSArray<id<UIUserActivityRestoring>> * _Nullable))restorationHandler {
return [RCTLinkingManager application:application continueUserActivity:userActivity restorationHandler:restorationHandler];
}
Android配置
修改android/app/src/main/AndroidManifest.xml，在MainActivity添加intent-filter：
<activity
android:name=".MainActivity"
android:launchMode="singleTask">
<!-- 原有配置 -->
<intent-filter>
<action android:name="android.intent.action.MAIN" />
<category android:name="android.intent.category.LAUNCHER" />
</intent-filter>
<!-- 深度链接配置 -->
<intent-filter>
<action android:name="android.intent.action.VIEW" />
<category android:name="android.intent.category.DEFAULT" />
<category android:name="android.intent.category.BROWSABLE" />
<data android:scheme="myapp" /> <!-- 与app.json中scheme一致 -->
</intent-filter>
</activity>
二、路由集成：React Navigation
2.1 安装依赖
npm install @react-navigation/native @react-navigation/stack
expo install react-native-screens react-native-safe-area-context
2.2 配置路由表
创建src/navigation/AppNavigator.tsx：
import { createStackNavigator } from '@react-navigation/stack';
import HomeScreen from '../screens/HomeScreen';
import DetailScreen from '../screens/DetailScreen';
import { LinkingOptions } from '@react-navigation/native';
const Stack = createStackNavigator();
// 路由配置
export const linking: LinkingOptions = {
prefixes: ['myapp://', 'https://myapp.com'], // 支持的链接前缀
config: {
screens: {
Home: 'home',
Detail: {
path: 'detail/:id', // 带参数的路由，如/detail/123
parse: {
id: (id) => Number(id), // 参数类型转换
},
},
},
},
};
export default function AppNavigator() {
return (
<Stack.Navigator initialRouteName="Home">
<Stack.Screen name="Home" component={HomeScreen} />
<Stack.Screen name="Detail" component={DetailScreen} />
</Stack.Navigator>
);
}
三、参数解析与路由处理
3.1 初始化链接处理
在App.tsx中集成导航容器与深度链接：
import { NavigationContainer } from '@react-navigation/native';
import AppNavigator, { linking } from './navigation/AppNavigator';
import * as Linking from 'expo-linking';
export default function App() {
return (
<NavigationContainer linking={linking} fallback={<Text>Loading...</Text>}>
<AppNavigator />
</NavigationContainer>
);
}
3.2 解析链接参数
在目标页面DetailScreen.tsx中获取参数：
import { useRoute } from '@react-navigation/native';
export default function DetailScreen() {
const route = useRoute();
const { id } = route.params; // 获取路由参数
return (
<View>
<Text>Detail ID: {id}</Text>
</View>
);
}
3.3 处理应用状态
区分应用冷启动与热启动两种场景：
// 冷启动时获取初始链接
const initialUrl = await Linking.getInitialURL();
if (initialUrl) {
handleDeepLink(initialUrl);
}
// 热启动时监听链接事件
const linkingSubscription = Linking.addEventListener('url', ({ url }) => {
handleDeepLink(url);
});
// 清理监听器
return () => linkingSubscription.remove();
四、高级应用：复杂参数与路由守卫
4.1 解析查询参数
对于myapp://detail/123?name=test&type=info格式链接，解析方法：
import queryString from 'query-string';
function handleDeepLink(url: string) {
const parsed = Linking.parse(url);
const { path, queryParams } = parsed;
// path: '/detail/123'
// queryParams: { name: 'test', type: 'info' }
}
4.2 路由守卫实现
const linking = {
prefixes: ['myapp://'],
async getInitialURL() {
const url = await Linking.getInitialURL();
if (url && isAuthenticated()) {
return url;
}
return '/login'; // 未登录重定向到登录页
},
};
五、测试验证
5.1 使用命令行测试
# iOS模拟器
xcrun simctl openurl booted "myapp://detail/123?name=test"
# Android模拟器
adb shell am start -W -a android.intent.action.VIEW \
-d "myapp://detail/123?name=test" com.myapp
5.2 使用Expo Linking API测试
// 在App中添加测试按钮
<Button
title="Open Deep Link"
onPress={() => Linking.openURL('myapp://detail/456?name=example')}
/>
常见问题解决
| 问题 | 解决方案 |
|---|---|
| 链接点击无响应 | 检查URL Scheme是否匹配，原生配置是否正确 |
| 参数解析错误 | 使用query-string库处理复杂参数，避免手动解析 |
| 应用重启问题 | Android需设置launchMode="singleTask" |
| Universal Links不生效 | 检查apple-app-site-association文件配置 |
总结与扩展
本文基于create-react-native-app框架，通过6个步骤实现了深度链接的完整流程：从URL Scheme配置、原生工程改造，到路由集成与参数解析。实际开发中，还可结合expo-notifications实现推送消息与深度链接的联动，或通过react-native-branch等第三方库实现更高级的归因分析功能。
完整示例代码可参考官方文档。
下期预告
下一篇将介绍"React Native性能优化实战：从启动速度到列表渲染"，敬请关注！如果本文对你有帮助，欢迎点赞、收藏、关注三连支持！
创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考
