diff --git a/docs/sectionlist.md b/docs/sectionlist.md index 9cdc3b0c8d7..f0749610965 100644 --- a/docs/sectionlist.md +++ b/docs/sectionlist.md @@ -16,24 +16,24 @@ A performant interface for rendering sectioned lists, supporting the most handy - Pull to Refresh. - Scroll loading. -If you don't need section support and want a simpler interface, use [``](flatlist.md). +If you don't need section support and want a simpler interface, use [``](flatlist). ## Example
-
    - - -
-
- - - -```SnackPlayer name=SectionList%20Example +
    + + +
+ + + + +```SnackPlayer name=SectionList%20Function%20Component%20Example import React from "react"; import { StyleSheet, @@ -105,9 +105,9 @@ const styles = StyleSheet.create({ export default App; ``` - + -```SnackPlayer name=SectionList%20Example +```SnackPlayer name=SectionList%20Class%20Component%20Example import React, { Component } from "react"; import { StyleSheet, @@ -183,12 +183,12 @@ const styles = StyleSheet.create({ export default App; ``` - + -This is a convenience wrapper around [``](virtualizedlist.md), and thus inherits its props (as well as those of [``](scrollview.md) that aren't explicitly listed here, along with the following caveats: +This is a convenience wrapper around [``](virtualizedlist), and thus inherits its props (as well as those of [``](scrollview)) that aren't explicitly listed here, along with the following caveats: - Internal state is not preserved when content scrolls out of the render window. Make sure all your data is captured in the item data or external stores like Flux, Redux, or Relay. -- This is a `PureComponent` which means that it will not re-render if `props` remain shallow-equal. Make sure that everything your `renderItem` function depends on is passed as a prop (e.g. `extraData`) that is not `===` after updates, otherwise your UI may not update on changes. This includes the `data` prop and parent component state. +- This is a `PureComponent` which means that it will not re-render if `props` remain shallow- equal. Make sure that everything your `renderItem` function depends on is passed as a prop (e.g. `extraData`) that is not `===` after updates, otherwise your UI may not update on changes. This includes the `data` prop and parent component state. - In order to constrain memory and enable smooth scrolling, content is rendered asynchronously offscreen. This means it's possible to scroll faster than the fill rate and momentarily see blank content. This is a tradeoff that can be adjusted to suit the needs of each application, and we are working on improving it behind the scenes. - By default, the list looks for a `key` prop on each item and uses that for the React key. Alternatively, you can provide a custom `keyExtractor` prop. @@ -198,117 +198,53 @@ This is a convenience wrapper around [``](virtualizedlist.md), ## Props -Inherits [ScrollView Props](scrollview.md#props). - -### `renderItem` - -Default renderer for every item in every section. Can be over-ridden on a per-section basis. Should return a React element. - -| Type | Required | -| -------- | -------- | -| function | Yes | - -The render function will be passed an object with the following keys: - -- 'item' (object) - the item object as specified in this section's `data` key -- 'index' (number) - Item's index within the section. -- 'section' (object) - The full section object as specified in `sections`. -- 'separators' (object) - An object with the following keys: - - 'highlight' (function) - `() => void` - - 'unhighlight' (function) - `() => void` - - 'updateProps' (function) - `(select, newProps) => void` - - 'select' (enum) - possible values are 'leading', 'trailing' - - 'newProps' (object) - ---- - -### `sections` - -The actual data to render, akin to the `data` prop in [`FlatList`](flatlist.md). - -| Type | Required | -| ------------------------------------------- | -------- | -| array of [Section](sectionlist.md#section)s | Yes | - ---- - -### `extraData` - -A marker property for telling the list to re-render (since it implements `PureComponent`). If any of your `renderItem`, Header, Footer, etc. functions depend on anything outside of the `data` prop, stick it here and treat it immutably. - -| Type | Required | -| ---- | -------- | -| any | No | - ---- - -### `initialNumToRender` +###
Required
`initialNumToRender` How many items to render in the initial batch. This should be enough to fill the screen but not much more. Note these items will never be unmounted as part of the windowed rendering in order to improve perceived performance of scroll-to-top actions. -| Type | Required | -| ------ | -------- | -| number | No | - ---- - -### `inverted` - -Reverses the direction of scroll. Uses scale transforms of -1. - -| Type | Required | -| --------- | -------- | -| [boolean] | No | - ---- - -### `ItemSeparatorComponent` - -Rendered in between each item, but not at the top or bottom. By default, `highlighted`, `section`, and `[leading/trailing][Item/Section]` props are provided. `renderItem` provides `separators.highlight`/`unhighlight` which will update the `highlighted` prop, but you can also add custom props with `separators.updateProps`. - -| Type | Required | -| ------------------------------ | -------- | -| [component, function, element] | No | +| Type | +| ------ | +| number | --- -### `keyExtractor` +###
Required
`keyExtractor` Used to extract a unique key for a given item at the specified index. Key is used for caching and as the React key to track item re-ordering. The default extractor checks `item.key`, then falls back to using the index, like React does. Note that this sets keys for each item, but each overall section still needs its own key. -| Type | Required | -| ------------------------------------- | -------- | -| (item: Item, index: number) => string | Yes | +| Type | +| -------- | +| function | --- -### `ListEmptyComponent` +###
Required
`sections` -Rendered when the list is empty. Can be a React Component Class, a render function, or a rendered element. +The actual data to render, akin to the `data` prop in [``](flatlist). -| Type | Required | -| ------------------------------ | -------- | -| [component, function, element] | No | +| Type | +| --------------------------------------- | +| array of [Section](sectionlist#section) | --- -### `ListFooterComponent` +### `extraData` -Rendered at the very end of the list. Can be a React Component Class, a render function, or a rendered element. +A marker property for telling the list to re-render (since it implements `PureComponent`). If any of your `renderItem`, Header, Footer, etc. functions depend on anything outside of the `data` prop, stick it here and treat it immutably. -| Type | Required | -| ------------------------------ | -------- | -| [component, function, element] | No | +| Type | +| ---- | +| any | --- -### `ListHeaderComponent` +### `inverted` -Rendered at the very beginning of the list. Can be a React Component Class, a render function, or a rendered element. +Reverses the direction of scroll. Uses scale transforms of -1. -| Type | Required | -| ---------------------------- | -------- | -| component, function, element | No | +| Type | +| ---- | +| bool | --- @@ -316,119 +252,80 @@ Rendered at the very beginning of the list. Can be a React Component Class, a re Called once when the scroll position gets within `onEndReachedThreshold` of the rendered content. -| Type | Required | -| ------------------------------------------- | -------- | -| [(info: {distanceFromEnd: number}) => void] | No | +| Type | +| -------- | +| function | --- -### `onEndReachedThreshold` - -How far from the end (in units of visible length of the list) the bottom edge of the list must be from the end of the content to trigger the `onEndReached` callback. Thus a value of 0.5 will trigger `onEndReached` when the end of the content is within half the visible length of the list. - -| Type | Required | -| -------- | -------- | -| [number] | No | - ---- +### `removeClippedSubviews` -### `onRefresh` +Note: may have bugs (missing content) in some circumstances - use at your own risk. -If provided, a standard RefreshControl will be added for "Pull to Refresh" functionality. Make sure to also set the `refreshing` prop correctly. To offset the RefreshControl from the top (e.g. by 100 pts), use `progressViewOffset={100}`. +This may improve scroll performance for large lists. -| Type | Required | -| ------------ | -------- | -| [() => void] | No | +| Type | +| ---- | +| bool | --- -### `onViewableItemsChanged` - -Called when the viewability of rows changes, as defined by the `viewabilityConfig` prop. - -| Type | Required | -| -------- | -------- | -| function | No | +### `renderItem` -The function will be passed an object with the following keys: +Default renderer for every item in every section. Can be over-ridden on a per-section basis. -- 'viewableItems' (array of `ViewToken`s) -- 'changed' (array of `ViewToken`s) +The render function will be passed an object with the following keys: -The `ViewToken` type is exported by `ViewabilityHelper.js`: +- 'item' (object) - the item object as specified in this section's `data` key +- 'index' (number) - Item's index within the section. +- 'section' (object) - The full section object as specified in `sections`. +- 'separators' (object) - An object with the following keys: + - 'highlight' (function) - `() => void` + - 'unhighlight' (function) - `() => void` + - 'updateProps' (function) - `(select, newProps) => void` + - 'select' (enum) - possible values are 'leading', 'trailing' + - 'newProps' (object) -| Name | Type | Required | -| ---------- | ------- | -------- | -| item | any | Yes | -| key | string | Yes | -| index | number | No | -| isViewable | boolean | Yes | -| section | any | No | +| Type | +| -------- | +| function | --- -### `refreshing` - -Set this true while waiting for new data from a refresh. - -| Type | Required | -| --------- | -------- | -| [boolean] | No | +### `stickySectionHeadersEnabled` ---- +| Type | Default | +| ---- | ----------------------- | +| | `Platform.OS === 'ios'` | -### `removeClippedSubviews` +## Methods -Note: may have bugs (missing content) in some circumstances - use at your own risk. +### `flashScrollIndicators()`
iOS
-This may improve scroll performance for large lists. +Displays the scroll indicators momentarily. -| Type | Required | -| ------- | -------- | -| boolean | No | +```jsx +flashScrollIndicators(); +``` --- -### `renderSectionFooter` - -Rendered at the bottom of each section. - -| Type | Required | -| ---------------------------------------------------- | -------- | -| [(info: {section: SectionT}) => ?React.Element] | No | +### `getScrollableNode()` --- -### `renderSectionHeader` - -Rendered at the top of each section. These stick to the top of the `ScrollView` by default on iOS. See `stickySectionHeadersEnabled`. +### `getScrollResponder()` -| Type | Required | -| ---------------------------------------------------- | -------- | -| [(info: {section: SectionT}) => ?React.Element] | No | +Provides a handle to the underlying scroll responder. --- -### `SectionSeparatorComponent` - -Rendered at the top and bottom of each section (note this is different from `ItemSeparatorComponent` which is only rendered between items). These are intended to separate sections from the headers above and below and typically have the same highlight response as `ItemSeparatorComponent`. Also receives `highlighted`, `[leading/trailing][Item/Section]`, and any custom props from `separators.updateProps`. +### `recordInteraction()` -| Type | Required | -| ----------------- | -------- | -| [ReactClass] | No | +Tells the list an interaction has occurred, which should trigger viewability calculations, e.g. if `waitForInteractions` is true and the user has not scrolled. This is typically called by taps on items or by navigation actions. --- -### `stickySectionHeadersEnabled` - -Makes section headers stick to the top of the screen until the next one pushes it off. Only enabled by default on iOS because that is the platform standard there. - -| Type | Required | -| ------- | -------- | -| boolean | No | - -## Methods - ### `scrollToLocation()` ```jsx @@ -443,56 +340,14 @@ Scrolls to the item at the specified `sectionIndex` and `itemIndex` (within the | Name | Type | Required | Description | | ------ | ------ | -------- | ----------- | -| params | object | Yes | See below. | - -Valid `params` keys are: - -- 'animated' (boolean) - Whether the list should do an animation while scrolling. Defaults to `true`. -- 'itemIndex' (number) - Index within section for the item to scroll to. Required. -- 'sectionIndex' (number) - Index for section that contains the item to scroll to. Required. -- 'viewOffset' (number) - A fixed number of pixels to offset the final target position, e.g. to compensate for sticky headers. -- 'viewPosition' (number) - A value of `0` places the item specified by index at the top, `1` at the bottom, and `0.5` centered in the middle. - ---- - -### `recordInteraction()` - -```jsx -recordInteraction(); -``` - -Tells the list an interaction has occurred, which should trigger viewability calculations, e.g. if `waitForInteractions` is true and the user has not scrolled. This is typically called by taps on items or by navigation actions. +| params | object | Yes | See below | --- -### `flashScrollIndicators()` +### `setNativeProps()` -```jsx -flashScrollIndicators(); -``` - -Displays the scroll indicators momentarily. - -| Platform | -| -------- | -| iOS | - -## Type Definitions - -### Section - -An object that identifies the data to be rendered for a given section. - -| Type | -| ---- | -| any | - -**Properties:** +**Parameters:** -| Name | Type | Description | -| ------------------------ | ---------------------------- | ---------------------------------------------------------------------------------------------------------------------------------------------------------------------- | -| data | array | The data for rendering items in this section. Array of objects, much like [`FlatList`'s data prop](flatlist.md#data). | -| [key] | string | Optional key to keep track of section re-ordering. If you don't plan on re-ordering sections, the array index will be used by default. | -| [renderItem] | function | Optionally define an arbitrary item renderer for this section, overriding the default [`renderItem`](sectionlist.md#renderitem) for the list. | -| [ItemSeparatorComponent] | component, function, element | Optionally define an arbitrary item separator for this section, overriding the default [`ItemSeparatorComponent`](sectionlist.md#itemseparatorcomponent) for the list. | -| [keyExtractor] | function | Optionally define an arbitrary key extractor for this section, overriding the default [`keyExtractor`](sectionlist.md#keyextractor). | +| Name | Type | Required | +| ----- | ------ | -------- | +| props | Object | Yes | diff --git a/docs/statusbar.md b/docs/statusbar.md index 770bdfaa873..75ee8c7ac39 100644 --- a/docs/statusbar.md +++ b/docs/statusbar.md @@ -9,47 +9,76 @@ Component to control the app status bar. It is possible to have multiple `StatusBar` components mounted at the same time. The props will be merged in the order the `StatusBar` components were mounted. -```SnackPlayer name=StatusBar%20Android%20and%20iOS%20Component%20Example&supportedPlatforms=android,ios -import React, { useState } from "react"; -import { Button, Text, StyleSheet, StatusBar, View } from "react-native"; +## Example -import Constants from "expo-constants"; +```SnackPlayer name=StatusBar%20Component%20Example&supportedPlatforms=android,ios +import React, { useState } from 'react'; +import { Button, Platform, SafeAreaView, StatusBar, StyleSheet, Text, View } from 'react-native'; -const App = () => { - const styleTypes = ['default','dark-content', 'light-content']; - const [visibleStatusBar, setVisibleStatusBar] = useState(false); - const [styleStatusBar, setStyleStatusBar] = useState(styleTypes[0]); +const STYLES = ['default', 'dark-content', 'light-content']; +const TRANSITIONS = ['fade', 'slide', 'none']; - const changeVisibilityStatusBar = () => { - setVisibleStatusBar(!visibleStatusBar); +const App = () => { + const [hidden, setHidden] = useState(false); + const [statusBarStyle, setStatusBarStyle] = useState(STYLES[0]); + const [statusBarTransition, setStatusBarTransition] = useState(TRANSITIONS[0]); + + const changeStatusBarVisibility = () => setHidden(!hidden); + + const changeStatusBarStyle = () => { + const styleId = STYLES.indexOf(statusBarStyle) + 1; + if (styleId === STYLES.length) { + setStatusBarStyle(STYLES[0]); + } else { + setStatusBarStyle(STYLES[styleId]); + } }; - const changeStyleStatusBar = () => { - const styleId = styleTypes.indexOf(styleStatusBar) + 1; - - if(styleId === styleTypes.length){ - return setStyleStatusBar(styleTypes[0]); + const changeStatusBarTransition = () => { + const transition = TRANSITIONS.indexOf(statusBarTransition) + 1; + if (transition === TRANSITIONS.length) { + setStatusBarTransition(TRANSITIONS[0]); + } else { + setStatusBarTransition(TRANSITIONS[transition]); } - return setStyleStatusBar(styleTypes[styleId]); }; return ( - - - StatusBar Style: {styleStatusBar} - StatusBar Visibility: {!visibleStatusBar ? 'Visible': 'Hidden'} - - - - - -