Skip to content

Commit

Permalink
feat: bring alphabetical order (#664)
Browse files Browse the repository at this point in the history
Added README.md for old implementation of native-stack and made all props follow alphabetical order.
  • Loading branch information
WoLewicki authored Oct 20, 2020
1 parent 0b75dc5 commit 257ab02
Show file tree
Hide file tree
Showing 7 changed files with 455 additions and 253 deletions.
10 changes: 5 additions & 5 deletions README.md
Original file line number Diff line number Diff line change
Expand Up @@ -17,10 +17,10 @@ For most people using an app built from the react-native template, that means ed
You should add this code, which specifically discards any Activity state persisted during the Activity restart process, to avoid inconsistencies that lead to crashes.

```java
@Override
protected void onCreate(Bundle savedInstanceState) {
super.onCreate(null);
}
@Override
protected void onCreate(Bundle savedInstanceState) {
super.onCreate(null);
}
```

For people that must handle cases like this, there is [a more detailed discussion of the difficulties in a series of related comments](https://github.com/software-mansion/react-native-screens/issues/17#issuecomment-424704633).
Expand Down Expand Up @@ -66,7 +66,7 @@ Note that the above code needs to execute before the first render of a navigatio

### Using createNativeStackNavigator with React Navigation

To take advantage of the native stack navigator primitive for React Navigation that leverages `UINavigationController` on iOS and `Fragment` on Android, please refer to the [README in react-native-screens/native-stack](https://github.com/software-mansion/react-native-screens/tree/master/native-stack). Note that this depends on React Navigation v5.
To take advantage of the native stack navigator primitive for React Navigation that leverages `UINavigationController` on iOS and `Fragment` on Android, please refer to the [README in react-native-screens/native-stack](https://github.com/software-mansion/react-native-screens/tree/master/native-stack) for React Navigation v5 and [README in react-native-screens/createNativeStackNavigator](https://github.com/software-mansion/react-native-screens/tree/master/createNativeStackNavigator) for older versions.

## Interop with [react-native-navigation](https://github.com/wix/react-native-navigation)

Expand Down
200 changes: 200 additions & 0 deletions createNativeStackNavigator/README.md
Original file line number Diff line number Diff line change
@@ -0,0 +1,200 @@
# Native Stack Navigator

Provides a way for your app to transition between screens where each new screen is placed on top of a stack.

By default the stack navigator is configured to have the familiar iOS and Android look & feel: new screens slide in from the right on iOS, fade in from the bottom on Android. On iOS, the stack navigator can also be configured to a modal style where screens slide in from the bottom.

This navigator uses native navigation primitives (`UINavigationController` on iOS and `Fragment` on Android) for navigation under the hood. The main difference from React Navigation's JS-based [stack navigator](https://reactnavigation.org/docs/stack-navigator.html) is that the JS-based navigator re-implements animations and gestures while the native stack navigator relies on the platform primitives for animations and gestures. You should use this navigator if you want native feeling and performance for navigation and don't need much customization, as the customization options of this navigator are limited.

```sh
npm install react-native-screens @react-navigation/native
```

Make sure to enable `react-native-screens`. This needs to be done before our app renders. To do it, add the following code in your entry file (e.g. `App.js`):

```js
import { enableScreens } from 'react-native-screens';

enableScreens();
```

## API Definition

To use this navigator, import it from `react-native-screens/createNativeStackNavigator`:

```js
import createNativeStackNavigator from 'react-native-screens/createNativeStackNavigator';

const RootStack = createNativeStackNavigator(
{
Home: HomeScreen,
Details: DetailsScreen,
},
{
initialRouteName: 'Home',
}
);
```

### `navigationOptions` for screens inside of the navigator

#### `backButtonInCustomView`

Boolean indicating whether to hide the back button while using `headerLeft` function.

#### `direction`

String that applies `rtl` or `ltr` form to the stack. On Android, you have to add `android:supportsRtl="true"` in the manifest of your app to enable `rtl`. On Android, if you set the above flag in the manifest, the orientation changes without the need to do it programmatically if the phone has `rtl` direction enabled. On iOS, the direction defaults to `ltr`, and only way to change it is via this prop.

#### `gestureEnabled`

Whether you can use gestures to dismiss this screen. Defaults to `true`,

Gestures are only supported on iOS. They can be disabled only when `stackPresentation` is `push`.

#### `headerBackTitle`

Title string used by the back button on iOS. Defaults to the previous scene's `headerTitle`.

#### `headerBackTitleStyle`

Style object for header back title. Supported properties:

- `fontFamily`
- `fontSize`

#### `headerBackTitleVisible`

Whether the back button title should be visible or not. Defaults to `true`. Only supported on iOS.

#### `headerLeft`

Function which returns a React Element to display on the left side of the header. For now, on Android, using it will cause the title to also disappear.

#### `headerRight`

Function which returns a React Element to display on the right side of the header.

#### `headerHideBackButton`

Boolean indicating whether to hide the back button in the header. Only supported on Android.

#### `headerStyle`

Style object for the header. Supported properties:

- `backgroundColor`
- `blurEffect` (iOS only). Possible values can be checked in `index.d.ts` file.

#### `headerTintColor`

Tint color for the header. Changes the color of the back button and title.

#### `headerTitle`

String to be used by the header as title string. Defaults to scene `title`.

#### `headerTitleStyle`

Style object for header title. Supported properties:

- `fontFamily`
- `fontSize`
- `color`

#### `headerTopInsetEnabled`

A Boolean to that lets you opt out of insetting the header. You may want to * set this to `false` if you use an opaque status bar. Defaults to `true`. Insets are always applied on iOS because the header cannot be opaque. Only supported on Android.

#### `hideShadow`

Boolean indicating whether to hide the elevation shadow on the header.

#### `largeTitle`

Boolean used to set a native property to prefer a large title header (like in iOS setting).

For the large title to collapse on scroll, the content of the screen should be wrapped in a scrollable view such as `ScrollView` or `FlatList`. If the scrollable area doesn't fill the screen, the large title won't collapse on scroll.

Only supported on iOS.

#### `stackAnimation`

How the given screen should appear/disappear when pushed or popped at the top of the stack. Possible values:

- `default` - Uses a platform default animation.
- `fade` - Fades screen in or out.
- `flip` – Flips the screen, requires stackPresentation: `modal` (iOS only).
- `none` - The screen appears/disappears without an animation.

Defaults to `default`.

#### `stackPresentation`

How the screen should be presented. Possible values:

- `push` - The new screen will be pushed onto a stack. The default animation on iOS is to slide from the side. The animation on Android may vary depending on the OS version and theme.
- `modal` - The new screen will be presented modally. In addition, this allows for a nested stack to be rendered inside such screens.
- `transparentModal` - The new screen will be presented modally. In addition, the second to last screen will remain attached to the stack container such that if the top screen is translucent, the content below can still be seen. If `"modal"` is used instead, the below screen gets removed as soon as the transition ends.
- `containedModal` – will use "UIModalPresentationCurrentContext" modal style on iOS and will fallback to `"modal"` on Android.
- `containedTransparentModal` – will use "UIModalPresentationOverCurrentContext" modal style on iOS and will fallback to `"transparentModal"` on Android.
- `fullScreenModal` – will use "UIModalPresentationFullScreen" modal style on iOS and will fallback to `"modal"` on Android.
- `formSheet` – will use "UIModalPresentationFormSheet" modal style on iOS and will fallback to `"modal"` on Android.

Defaults to `push`.

#### `title`

A string that can be used as a fallback for `headerTitle`.

#### `translucent`

Boolean indicating whether the navigation bar is translucent.

### Helpers

The stack navigator adds the following methods to the navigation prop:

#### `push`

Pushes a new screen to the top of the stack and navigate to it. The method accepts the following arguments:

- `name` - _string_ - Name of the route to push onto the stack.
- `params` - _object_ - Screen params to merge into the destination route (found in the pushed screen through `route.params`).

```js
navigation.push('Profile', { name: 'Wojtek' });
```

#### `pop`

Pops the current screen from the stack and navigates back to the previous screen. It takes one optional argument (`count`), which allows you to specify how many screens to pop back by.

```js
navigation.pop();
```

#### `popToTop`

Pops all of the screens in the stack except the first one and navigates to it.

```js
navigation.popToTop();
```

## Additional options

### Measuring header's height on iOS

Using translucent header on iOS can result in the need of measuring your header's height. In order to do it, you can use `react-native-safe-area-context`. It can be measured like this:
```js
import { useSafeAreaInsets } from 'react-native-safe-area-context';

...

const statusBarInset = useSafeAreaInsets().top; // inset of the status bar
const smallHeaderInset = statusBarInset + 44; // inset to use for a small header since it's frame is equal to 44 + the frame of status bar
const largeHeaderInset = statusBarInset + 96; // inset to use for a large header since it's frame is equal to 96 + the frame of status bar
```

You can also see an example of using these values with a `ScrollView` here: https://snack.expo.io/@wolewicki/ios-header-height.
97 changes: 49 additions & 48 deletions native-stack/README.md
Original file line number Diff line number Diff line change
Expand Up @@ -55,57 +55,50 @@ Default options to use for the screens in the navigator.

The `options` prop can be used to configure individual screens inside the navigator. Supported options are:

#### `title`

A string that can be used as a fallback for `headerTitle`.

#### `headerShown`

Whether to show or hide the header for the screen. The header is shown by default. Setting this to `false` hides the header.
#### `backButtonInCustomView`

#### `headerHideBackButton`
Boolean indicating whether to hide the back button while using `headerLeft` function.

Boolean indicating whether to hide the back button in the header. Only supported on Android.
#### `contentStyle`

#### `backButtonInCustomView`
Style object for the scene content.

Boolean indicating whether to hide the back button while using `headerLeft` function.
#### `direction`

#### `headerHideShadow`
String that applies `rtl` or `ltr` form to the stack. On Android, you have to add `android:supportsRtl="true"` in the manifest of your app to enable `rtl`. On Android, if you set the above flag in the manifest, the orientation changes without the need to do it programmatically if the phone has `rtl` direction enabled. On iOS, the direction defaults to `ltr`, and only way to change it is via this prop.

Boolean indicating whether to hide the elevation shadow on the header.
#### `gestureEnabled`

#### `headerTitle`
Whether you can use gestures to dismiss this screen. Defaults to `true`,

String to be used by the header as title string. Defaults to scene `title`.
Gestures are only supported on iOS. They can be disabled only when `stackPresentation` is `push`.

#### `headerBackTitle`

Title string used by the back button on iOS. Defaults to the previous scene's `headerTitle`.

#### `headerBackTitleVisible`

Whether the back button title should be visible or not. Defaults to `true`. Only supported on iOS.
#### `headerBackTitleStyle`

#### `headerRight`
Style object for header back title. Supported properties:

Function which returns a React Element to display on the right side of the header.
- `fontFamily`
- `fontSize`

#### `headerLeft`
#### `headerBackTitleVisible`

Function which returns a React Element to display on the left side of the header. For now, on Android, using it will cause the title to also disappear.
Whether the back button title should be visible or not. Defaults to `true`. Only supported on iOS.

#### `headerCenter`

Function which returns a React Element to display in the center of the header.

#### `headerTranslucent`
#### `headerHideBackButton`

Boolean indicating whether the navigation bar is translucent.
Boolean indicating whether to hide the back button in the header. Only supported on Android.

#### `headerTopInsetEnabled`
#### `headerHideShadow`

A Boolean to that lets you opt out of insetting the header. You may want to * set this to `false` if you use an opaque status bar. Defaults to `true`. Insets are always applied on iOS because the header cannot be opaque. Only supported on Android.
Boolean indicating whether to hide the elevation shadow on the header.

#### `headerLargeTitle`

Expand All @@ -115,19 +108,32 @@ For the large title to collapse on scroll, the content of the screen should be w

Only supported on iOS.

#### `direction`
#### `headerLeft`

String that applies `rtl` or `ltr` form to the stack. On Android, you have to add `android:supportsRtl="true"` in the manifest of your app to enable `rtl`. On Android, if you set the above flag in the manifest, the orientation changes without the need to do it programmatically if the phone has `rtl` direction enabled. On iOS, the direction defaults to `ltr`, and only way to change it is via this prop.
Function which returns a React Element to display on the left side of the header. For now, on Android, using it will cause the title to also disappear.

#### `headerTintColor`
#### `headerRight`

Tint color for the header. Changes the color of the back button and title.
Function which returns a React Element to display on the right side of the header.

#### `headerShown`

Whether to show or hide the header for the screen. The header is shown by default. Setting this to `false` hides the header.

#### `headerStyle`

Style object for the header. Supported properties:

- `backgroundColor`
- `blurEffect` (iOS only). Possible values can be checked in `index.d.ts` file.

#### `headerTintColor`

Tint color for the header. Changes the color of the back button and title.

#### `headerTitle`

String to be used by the header as title string. Defaults to scene `title`.

#### `headerTitleStyle`

Expand All @@ -137,22 +143,24 @@ Style object for header title. Supported properties:
- `fontSize`
- `color`

#### `headerBackTitleStyle`
#### `headerTopInsetEnabled`

Style object for header back title. Supported properties:
A Boolean to that lets you opt out of insetting the header. You may want to * set this to `false` if you use an opaque status bar. Defaults to `true`. Insets are always applied on iOS because the header cannot be opaque. Only supported on Android.

- `fontFamily`
- `fontSize`
#### `headerTranslucent`

#### `contentStyle`
Boolean indicating whether the navigation bar is translucent.

Style object for the scene content.
#### `stackAnimation`

#### `gestureEnabled`
How the given screen should appear/disappear when pushed or popped at the top of the stack. Possible values:

Whether you can use gestures to dismiss this screen. Defaults to `true`,
- `default` - Uses a platform default animation.
- `fade` - Fades screen in or out.
- `flip` – Flips the screen, requires stackPresentation: `modal` (iOS only).
- `none` - The screen appears/disappears without an animation.

Gestures are only supported on iOS. They can be disabled only when `stackPresentation` is `push`.
Defaults to `default`.

#### `stackPresentation`

Expand All @@ -168,16 +176,9 @@ How the screen should be presented. Possible values:

Defaults to `push`.

#### `stackAnimation`

How the given screen should appear/disappear when pushed or popped at the top of the stack. Possible values:

- `default` - Uses a platform default animation.
- `fade` - Fades screen in or out.
- `flip` – Flips the screen, requires stackPresentation: `modal` (iOS only).
- `none` - The screen appears/disappears without an animation.
#### `title`

Defaults to `default`.
A string that can be used as a fallback for `headerTitle`.

### Events

Expand Down
Loading

0 comments on commit 257ab02

Please sign in to comment.