Native Navigation 项目安装与配置完全指南

Native Navigation 项目安装与配置完全指南

native-navigation Native navigation library for React Native applications 项目地址: https://gitcode.com/gh_mirrors/na/native-navigation

前言

Native Navigation 是 Airbnb 开源的一个 React Native 导航解决方案，它采用了原生导航的实现方式，能够提供更流畅的用户体验和更接近原生应用的导航效果。本文将详细介绍如何从零开始配置 Native Navigation 项目，包括 iOS 和 Android 平台的完整安装流程。

为什么安装过程相对复杂？

Native Navigation 的安装过程相比常规 React Native 库确实要复杂一些，这主要源于两个技术原因：

1. 多 Root View 架构：Native Navigation 改变了 React Native 应用的结构，它鼓励使用多个 React "Root View" 而不是单一 Root View。这与 React Native CLI 提供的标准模板有所不同，需要进行相应调整。

2. Swift 实现带来的挑战：iOS 端的 Native Navigation 使用 Swift 编写，而 React Native 项目通常采用静态链接方式。Swift 代码需要动态链接，这带来了额外的配置工作。目前推荐使用 CocoaPods 来管理依赖关系。

新建项目基础配置

1. 创建 React Native 项目

首先使用 React Native CLI 创建一个新项目：

npm install -g react-native-cli
react-native init MyNativeNavigationProject
cd MyNativeNavigationProject

2. 安装 Native Navigation

安装最新版本的 native-navigation：

npm install --save native-navigation

重要提示：不要使用 react-native link 命令来链接 native-navigation，目前不支持这种方式。

JavaScript 项目配置

入口文件改造

Native Navigation 推荐的项目结构与 React Native 标准模板有所不同。我们需要修改入口文件：

1. 在 index.ios.js 和 index.android.js 中（或统一的 index.js 文件），将原有的 AppRegistry.registerComponent 替换为 Native Navigation 的注册方式：

import Navigator from 'native-navigation';

// 替换原有的 AppRegistry.registerComponent
Navigator.registerScreen('Home', () => App);

这样我们就将组件注册为了一个名为 "Home" 的屏幕。

iOS 平台详细配置

1. CocoaPods 环境准备

由于 Native Navigation 使用 Swift 编写，我们需要通过 CocoaPods 来管理依赖：

sudo gem install cocoapods
pod --version  # 确保版本 ≥1.2.0

2. Podfile 配置

在 iOS 目录下创建并编辑 Podfile：

target 'MyNativeNavigationProject' do
  use_frameworks!  # 必须启用，因为使用 Swift
  
  pod 'native-navigation', :path => '../node_modules/native-navigation'
  pod 'Yoga', :path => '../node_modules/react-native/ReactCommon/yoga/Yoga.podspec'
  
  pod 'React', :path => '../node_modules/react-native', :subspecs => [
    'Core',
    'RCTText',
    'RCTNetwork',
    'RCTWebSocket',
    'RCTImage',
    'DevSupport'  # 调试支持
  ]
end

运行 pod install 安装依赖。

3. Xcode 项目调整

1. 打开 MyNativeNavigationProject.xcworkspace（不是 .xcodeproj）
2. 移除 Libraries 文件夹中的所有库引用（右键 → Remove References）
3. 如果提示 Swift 版本更新，选择 "Convert" 更新到最新 Swift 版本

4. AppDelegate 改造

Native Navigation 需要一个共享的 RCTBridge 实例来管理多个 RCTRootView。我们需要修改 AppDelegate：

// AppDelegate.h
#import <React/RCTBridge.h>
@import NativeNavigation;

@interface AppDelegate : UIResponder <UIApplicationDelegate, RCTBridgeDelegate, ReactNavigationCoordinatorDelegate>
@property (nonatomic, strong) UIWindow *window;
@end

// AppDelegate.m
- (BOOL)application:(UIApplication *)application didFinishLaunchingWithOptions:(NSDictionary *)launchOptions {
  RCTBridge *bridge = [[RCTBridge alloc] initWithDelegate:self launchOptions:launchOptions];
  ReactNavigationCoordinator *coordinator = [ReactNavigationCoordinator sharedInstance];
  
  [coordinator setBridge:bridge];
  [coordinator setDelegate:self];
  
  self.window = [[UIWindow alloc] initWithFrame:[UIScreen mainScreen].bounds];
  ReactViewController *mainViewController = [[ReactViewController alloc] initWithModuleName:@"Home"];
  self.window.rootViewController = [[coordinator navigation] makeNavigationControllerWithRootViewController:mainViewController];
  [self.window makeKeyAndVisible];
  return YES;
}

- (NSURL *)sourceURLForBridge:(RCTBridge *)bridge {
  return [[RCTBundleURLProvider sharedSettings] jsBundleURLForBundleRoot:@"index.ios" fallbackResource:nil];
}

- (UIViewController *)rootViewControllerForCoordinator:(ReactNavigationCoordinator *)coordinator {
  return self.window.rootViewController;
}

Android 平台详细配置

1. Gradle 配置

在 android/settings.gradle 中添加：

include ':native-navigation'
project(':native-navigation').projectDir = new File(rootProject.projectDir, '../node_modules/native-navigation/lib/android')

在 android/app/build.gradle 中：

android {
    compileSdkVersion 25
    targetSdkVersion 25
    
    packagingOptions {
        exclude 'META-INF/LICENSE'
        exclude 'META-INF/NOTICE'
        // 其他排除项...
    }
}

dependencies {
    compile 'com.android.support:appcompat-v7:25.2.0'
    compile 'com.android.support:support-annotations:25.2.0'
    compile project(':native-navigation')
}

2. Java 代码调整

在 MainApplication.java 中：

@Override
protected List<ReactPackage> getPackages() {
  return Arrays.<ReactPackage>asList(
      new MainReactPackage(),
      new NativeNavigationPackage()
  );
}

@Override
public void onCreate() {
  super.onCreate();
  ReactNavigationCoordinator coordinator = ReactNavigationCoordinator.sharedInstance;
  coordinator.injectReactInstanceManager(mReactNativeHost.getReactInstanceManager());
  coordinator.start(this);
}

修改 MainActivity.java：

public class MainActivity extends ReactActivity {
    @Override
    protected String getInitialScreenName() {
        return "Home";
    }
}

测试与验证

完成上述配置后，你可以运行项目：

react-native run-ios  # 或 run-android

如果一切配置正确，应用应该能够正常启动并显示你的 "Home" 屏幕。

常见问题解决

1. Swift 兼容性问题：确保 Xcode 项目设置中的 Swift 版本是最新的
2. CocoaPods 依赖冲突：如果遇到依赖问题，尝试 pod deintegrate 后重新 pod install
3. Android 编译错误：检查是否所有排除项都已正确添加到 packagingOptions

结语

Native Navigation 提供了接近原生体验的导航解决方案，虽然初始配置相对复杂，但带来的性能提升和用户体验改善是值得的。完成基础配置后，你可以进一步探索 Native Navigation 提供的高级功能，如自定义转场动画、深度链接支持等。

希望本指南能帮助你顺利完成 Native Navigation 的安装和配置。如果在实施过程中遇到任何问题，可以参考项目的官方文档或社区讨论。

native-navigation Native navigation library for React Native applications 项目地址: https://gitcode.com/gh_mirrors/na/native-navigation