Merge pull request #1663 from brentvatne/navigator-vs-navigator-ios

[Docs] First draft of Navigator vs NavigatorIOS docs
This commit is contained in:
Brent Vatne 2015-06-17 18:32:49 -07:00
commit 7733c777bf
2 changed files with 49 additions and 1 deletions

View File

@ -4,7 +4,7 @@ title: JavaScript Environment
layout: docs
category: Guides
permalink: docs/javascript-environment.html
next: activityindicatorios
next: navigator-comparison
---
## JavaScript Runtime

View File

@ -0,0 +1,48 @@
---
id: navigator-comparison
title: Navigator Comparison
layout: docs
category: Guides
permalink: docs/navigator-comparison.html
next: activityindicatorios
---
The differences between [Navigator](/react-native/docs/navigator.html)
and [NavigatorIOS](/react-native/docs/navigatorios.html) are a common
source of confusion for newcomers.
Both `Navigator` and `NavigatorIOS` are components that allow you to
manage the navigation in your app between various "scenes" (another word
for screens). They manage a route stack and allow you to pop, push, and
replace states. In this way, [they are similar to the html5 history
API](https://developer.mozilla.org/en-US/docs/Web/Guide/API/DOM/Manipulating_the_browser_history).
The primary distinction between the two is that `NavigatorIOS` leverages
the iOS
[UINavigationController](https://developer.apple.com/library/ios/documentation/UIKit/Reference/UINavigationController_Class/)
class, and `Navigator` re-implements that functionality entirely in
JavaScript as a React component. A corollary of this is that `Navigator`
will be compatible with Android and iOS, whereas `NavigatorIOS` will
only work on the one platform. Below is an itemized list of differences
between the two.
## Navigator
- Extensive API makes it completely customizable from JavaScript.
- Under active development from the React Native team.
- Written in JavaScript.
- Works on iOS and Android.
- Includes a simple navigation bar component similar to the default `NavigatorIOS` bar: `Navigator.NavigationBar`, and another with breadcrumbs called `Navigator.BreadcrumbNavigationBar`. See the UIExplorer demo to try them out and see how to use them.
- Currently animations are good and improving, but they are still less refined than Apple's, which you get from `NavigatorIOS`.
- You can provide your own navigation bar by passing it through the `navigationBar` prop.
## NavigatorIOS
- Small, limited API makes it much less customizable than `Navigator` in its current form.
- Development belongs to open-source community - not used by the React Native team on their apps.
- A result of this is that there is currently a backlog of unresolved bugs, nobody who uses this has stepped up to take ownership for it yet.
- Wraps UIKit, so it works exactly the same as it would on another native app. Lives in Objective-C and JavaScript.
- Consequently, you get the animations and behaviour that Apple has developed.
- iOS only.
- Includes a navigation bar by default; this navigation bar is not a React Native view component and the style can only be slightly modified.
For most non-trivial apps, you will want to use `Navigator` - it won't be long before you run into issues when trying to do anything complex with `NavigatorIOS`.