react-native-navigation的迁移库

docs-stack.mdx 7.7KB

123456789101112131415161718192021222324252627282930313233343536373839404142434445464748495051525354555657585960616263646566676869707172737475767778798081828384858687888990919293949596979899100101102103104105106107108109110111112113114115116117118119120121122123124125126127128129130131132133134135136137138139140141142143144145146147148149150151152153154155156157158159160161162163164165166167168169170171172173174175176177178179180181182183184185186187188189190191192193194195196197198199200201202203204205206207208209210211212213214215216217218219220221222223224225226227228229230231232233234235236237238239240241242243244245246247248249250251252253254255256257258
  1. ---
  2. id: stack
  3. title: Stack
  4. sidebar_label: Stack
  5. ---
  6. import Tabs from '@theme/Tabs';
  7. import TabItem from '@theme/TabItem';
  8. A stack is a container layout promoting a hierarchical navigation. It is used for navigating between screens at consecutive levels of hierarchy, steps in a flow or across an app.
  9. The first child in the stack (represented by the `children` array) is the root and is displayed at the bottom of the stack. The last child in the children array is the child currently being displayed.
  10. In this layout, only a single child screen is visible at any given time and consecutive screen can be added to the top of the stack using the `Navigation.push` command. Tapping the back button will pop the stack and remove the top most screen.
  11. The stack manages the TopBar at the top of the stack. The TopBar displays the current screens' title and buttons. It can be hidden with the `topBar: { visible: false }` option. By default, screens are rendered below the TopBar. This behavior can be changed by setting `topBar: { drawBehind: true }` in the current screens' options.
  12. # Layout Examples
  13. <Tabs
  14. defaultValue="single"
  15. values={[
  16. { label: 'Single child', value: 'single', },
  17. { label: 'Multiple Children', value: 'multiple', }
  18. ]
  19. }>
  20. <TabItem value="single">
  21. A stack declared with a single child.
  22. ```js
  23. const stack = {
  24. children: [
  25. {
  26. component: {
  27. name: 'MyComponent'
  28. }
  29. }
  30. ]
  31. }
  32. ```
  33. </TabItem>
  34. <TabItem value="multiple">
  35. A stack can be initialized with more than one child, in which case the last child will be the currently displayed child and the first child will be hidden. In this case the back button will be visible automatically, clicking it will go back in the stack revealing the first (previous) child.
  36. Once the root child becomes visible, the back button is hidden.
  37. ```js
  38. const stack = {
  39. children: [
  40. {
  41. component: {
  42. name: 'RootComponent'
  43. }
  44. },
  45. {
  46. component: {
  47. name: 'SecondComponent'
  48. }
  49. }
  50. ]
  51. }
  52. ```
  53. </TabItem>
  54. </Tabs>
  55. ## TopBar Buttons
  56. Buttons can be added to the [right](#rightButtons) and [left](#leftButtons) areas of the TopBar. Buttons can have either an icon or a text. They are declared in the the options object and, as with any other option, can be updated dynamically with the `Navigation.mergeOptions` command.
  57. :::tip Always assign titles to buttons!
  58. When using an icon button on **Android**, you should always pass a title as well. The title is used when the button is collapsed to the overflow menu and as a tooltip when the button is long pressed.
  59. :::
  60. ### Overflow menu
  61. It's common practice to group less important actions in a menu or an action sheet.
  62. To do so on iOS, include a button with a menu icon and open an [ActionSheet](https://facebook.github.io/react-native/docs/actionsheetios) with the relevant actions when the button is clicked.
  63. On Android, use the [showAsAction](#showasaction) options to control when the button should appear in the menu.
  64. ### Left button
  65. Left buttons behave like right buttons with two caveats on Android:
  66. * Only a single left button is allowed
  67. * Textual left button isn't supported
  68. ### Using a react component in a button
  69. :::caution
  70. At the moment, custom buttons in `leftButtons` are supported only on iOS.
  71. :::
  72. Sometimes we require more from our buttons. In order to support every product need React Components can be used as custom views of buttons.
  73. To do so, you'll first need to register the view with Navigation, just like you register your components used as screens:
  74. ```js
  75. Navigation.registerComponent('ButtonComponent', () => require('./ButtonComponent'));
  76. ```
  77. Now you can create buttons which use the component registered with `'ButtonComponent'` as their custom view:
  78. ```js
  79. topBar: {
  80. rightButtons: [
  81. {
  82. component: 'ButtonComponent',
  83. passProps: {
  84. // Pass initial props to the button here
  85. }
  86. }
  87. ]
  88. }
  89. ```
  90. ### Updating props of custom buttons
  91. To update props of a mounted component used as a button, you'll first need to assign it a unique id, then call the `Navigation.updateProps()` command with the id.
  92. Calling the updateProps command will trigger Reacts component lifecycle methods related to [props update](https://reactjs.org/docs/react-component.html#updating)
  93. ```js
  94. // Declare the button and assign it a unique id
  95. topBar: {
  96. rightButtons: [
  97. {
  98. id: 'SomeUniqueId',
  99. component: 'ButtonComponent',
  100. passProps: {
  101. count: 0
  102. }
  103. }
  104. ]
  105. }
  106. // Update props
  107. Navigation.updateProps('SomeUniqueId', {
  108. count: 1
  109. });
  110. ```
  111. ### Changing buttons dynamically
  112. As buttons are part of a screen's options, they can be modified like any other styling option using the [mergeOptions]() command.
  113. #### Setting buttons
  114. The following command will set the screen's right buttons. If the screen already has Right Buttons declared - they will be overridden.
  115. ```js
  116. Navigation.mergeOptions(this.props.componentId, {
  117. topBar: {
  118. rightButtons: [
  119. {
  120. id: 'myDynamicButton',
  121. text: 'My Button'
  122. }
  123. ]
  124. }
  125. });
  126. ```
  127. #### Removing buttons
  128. Buttons can be removed by setting zero buttons, as shown in the snippet below.
  129. ```js
  130. Navigation.mergeOptions(this.props.componentId, {
  131. topBar: {
  132. rightButtons: []
  133. }
  134. });
  135. ```
  136. ## Back Button
  137. The back button is added automatically when two or more screens are pushed into the stack.
  138. ### Styling the back button
  139. The back button's style can be customized by declaring a backButton options object. This configuration can be part of a screen's static options, or default options.
  140. ```js
  141. backButton: {
  142. color: 'red',
  143. icon: require('../../img/customChevron.png')
  144. }
  145. ```
  146. ### Controlling visibility
  147. The back buttons visibility can be controlled with the visible property.
  148. ```js
  149. backButton: {
  150. visible: false
  151. }
  152. ```
  153. ### Changing visibility programmatically
  154. Back button visibility can be changed dynamically using the mergeOptions command. When using a screen's componentId, the change will affect only that specific screen. But when using the stack's id, the change will affect all screens pushed into the stack.
  155. ```js
  156. Navigation.mergeOptions(this.props.componentId, {
  157. backButton: {
  158. visible: false
  159. }
  160. });
  161. ```
  162. ### Handling the back button
  163. Handling the back button is not possible. However, you can set a left button with a chevron and handle it like you'd handle any other button and calling `Navigation.pop` when desired.
  164. ## Interacting programmatically
  165. The Navigation object provides ways to programmatically manipulate the stack.
  166. ### Interact with the Stack by componentId
  167. Each layout pushed into the stack has an id. When in the context of a component, The component's `componentId` can be used to interact with a parent stack.
  168. When using a component's componentId, the native implementation knows to perform the command on the parent Stack of this component.
  169. In this example, we push a screen onto the component's parent stack.
  170. ```jsx
  171. const React = require('react');
  172. const Navigation = require('react-native-navigation');
  173. class MyComponent extends React.Component {
  174. onButtonClick = () => {
  175. Navigation.push(this.props.componentId, {
  176. component: {
  177. name: 'PUSHED_SCREEN'
  178. }
  179. });
  180. }
  181. }
  182. ```
  183. ### Interact with the Stack by a predefined id
  184. Sometimes we're required to interact with a specific stack not from the context of a component pushed into it. To do so, assign the stack a predefined `id` and use it when invoking any stack command.
  185. ```js
  186. Navigation.setRoot({
  187. root: {
  188. stack: {
  189. id: 'MyStack', // This is the id we're going to use when interacting with the stack
  190. children: [
  191. {
  192. component: {
  193. name: 'SomeComponent'
  194. }
  195. }
  196. ]
  197. }
  198. }
  199. });
  200. function push() {
  201. Navigation.push('MyStack', {
  202. component: {
  203. name: 'PushedScreen'
  204. }
  205. });
  206. }
  207. ```
  208. ## Disabling back navigation
  209. ## Handling back navigation