Skip to content
New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

Sign up for GitHub

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Jump to bottom

update SectionList page, extract ViewToken, add labels #2191

Merged
merged 2 commits into from
Sep 10, 2020
Merged

update SectionList page, extract ViewToken, add labels #2191

Show file tree
Hide file tree
Changes from all commits
Commits
Show all changes
2 commits
Select commit Hold shift + click to select a range
600063f
update SectionList page, extract ViewToken, add labels
Simek Sep 1, 2020
ea40877
text tweak
Simek Sep 1, 2020
File filter

Filter by extension

Filter by extension
Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
13 changes: 3 additions & 10 deletions docs/flatlist.md
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -447,18 +447,11 @@ If provided, a standard RefreshControl will be added for "Pull to Refresh" funct

### `onViewableItemsChanged`

```jsx
(info: {
viewableItems: array,
changed: array,
}) => void
```

Called when the viewability of rows changes, as defined by the `viewabilityConfig` prop.

| Type | Required |
| -------- | -------- |
| function | No |
| Type |
| ------------------------------------------------------------------------------------------------------------------ |
| (callback: { changed: array of [ViewToken](viewtoken)s, viewableItems: array of [ViewToken](viewtoken)s }) => void |

---

Expand Down
201 changes: 91 additions & 110 deletions docs/sectionlist.md
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -204,13 +204,13 @@ Inherits [ScrollView Props](scrollview.md#props).

---

### `renderItem`
### <div class="label required basic">Required</div>**`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 |
| Type |
| -------- |
| function |

The render function will be passed an object with the following keys:

Expand All @@ -226,236 +226,205 @@ The render function will be passed an object with the following keys:

---

### `sections`
### <div class="label required basic">Required</div>**`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 |
| Type |
| ------------------------------------------- |
| array of [Section](sectionlist.md#section)s |

---

### `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 |
| Type |
| ---- |
| any |

---

### `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 |
| Type | Default |
| ------ | ------- |
| number | `10` |

---

### `inverted`

Reverses the direction of scroll. Uses scale transforms of -1.

| Type | Required |
| --------- | -------- |
| [boolean] | No |
| Type | Default |
| ------- | ------- |
| boolean | `false` |

---

### `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 |
| ---------------------------- |
| component, element, function |

---

### `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 |
| --------------------------------------- |
| (item: object, index: number) => string |

---

### `ListEmptyComponent`

Rendered when the list is empty. Can be a React Component Class, a render function, or a rendered element.

| Type | Required |
| ------------------------------ | -------- |
| [component, function, element] | No |
| Type |
| ---------------------------- |
| component, element, function |

---

### `ListFooterComponent`

Rendered at the very end of the list. Can be a React Component Class, a render function, or a rendered element.

| Type | Required |
| ------------------------------ | -------- |
| [component, function, element] | No |
| Type |
| ---------------------------- |
| component, element, function |

---

### `ListHeaderComponent`

Rendered at the very beginning of the list. Can be a React Component Class, a render function, or a rendered element.

| Type | Required |
| ---------------------------- | -------- |
| component, function, element | No |
| Type |
| ---------------------------- |
| component, element, function |

---

### `onEndReached`

Called once when the scroll position gets within `onEndReachedThreshold` of the rendered content.

| Type | Required |
| ------------------------------------------- | -------- |
| [(info: {distanceFromEnd: number}) => void] | No |
| Type |
| ------------------------------------------- |
| (info: { distanceFromEnd: number }) => void |

---

### `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 |
| Type | Default |
| ------ | ------- |
| number | `2` |

---

### `onRefresh`

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}`.

| Type | Required |
| ------------ | -------- |
| [() => void] | No |
| Type |
| -------- |
| function |

---

### `onViewableItemsChanged`

Called when the viewability of rows changes, as defined by the `viewabilityConfig` prop.

| Type | Required |
| -------- | -------- |
| function | No |

The function will be passed an object with the following keys:

- 'viewableItems' (array of `ViewToken`s)
- 'changed' (array of `ViewToken`s)

The `ViewToken` type is exported by `ViewabilityHelper.js`:

| Name | Type | Required |
| ---------- | ------- | -------- |
| item | any | Yes |
| key | string | Yes |
| index | number | No |
| isViewable | boolean | Yes |
| section | any | No |
| Type |
| ------------------------------------------------------------------------------------------------------------------ |
| (callback: { changed: array of [ViewToken](viewtoken)s, viewableItems: array of [ViewToken](viewtoken)s }) => void |

---

### `refreshing`

Set this true while waiting for new data from a refresh.

| Type | Required |
| --------- | -------- |
| [boolean] | No |
| Type | Default |
| ------- | ------- |
| boolean | `false` |

---

### `removeClippedSubviews`

Note: may have bugs (missing content) in some circumstances - use at your own risk.
> Note: may have bugs (missing content) in some circumstances - use at your own risk.

This may improve scroll performance for large lists.

| Type | Required |
| ------- | -------- |
| boolean | No |
| Type | Default |
| ------- | ------- |
| boolean | `false` |

---

### `renderSectionFooter`

Rendered at the bottom of each section.

| Type | Required |
| ------------------------------------------------------ | -------- |
| `[(info: {section: SectionT}) => ?React.Element<any>]` | No |
| Type |
| ---------------------------------------------------------------------- |
| (info: { section: [Section](sectionlist#section) }) => element, `null` |

---

### `renderSectionHeader`

Rendered at the top of each section. These stick to the top of the `ScrollView` by default on iOS. See `stickySectionHeadersEnabled`.

| Type | Required |
| ------------------------------------------------------ | -------- |
| `[(info: {section: SectionT}) => ?React.Element<any>]` | No |
| Type |
| ---------------------------------------------------------------------- |
| (info: { section: [Section](sectionlist#section) }) => element, `null` |

---

### `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`.

| Type | Required |
| ------------------- | -------- |
| `[ReactClass<any>]` | No |
| Type |
| ---------------------------- |
| component, element, function |

---

### `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 |
| Type | Default |
| ------- | ------- |
| boolean | `false` |

## Methods

### `scrollToLocation()`
### `flashScrollIndicators()` <div class="label ios">iOS</div>

```jsx
scrollToLocation(params);
flashScrollIndicators();
```

Scrolls to the item at the specified `sectionIndex` and `itemIndex` (within the section) positioned in the viewable area such that `viewPosition` 0 places it at the top (and may be covered by a sticky header), 1 at the bottom, and 0.5 centered in the middle.

> Note: Cannot scroll to locations outside the render window without specifying the `getItemLayout` or `onScrollToIndexFailed` prop.

**Parameters:**

| 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.
Displays the scroll indicators momentarily.

---

Expand All @@ -469,17 +438,29 @@ Tells the list an interaction has occurred, which should trigger viewability cal

---

### `flashScrollIndicators()`
### `scrollToLocation()`

```jsx
flashScrollIndicators();
scrollToLocation(params);
```

Displays the scroll indicators momentarily.
Scrolls to the item at the specified `sectionIndex` and `itemIndex` (within the section) positioned in the viewable area such that `viewPosition` 0 places it at the top (and may be covered by a sticky header), 1 at the bottom, and 0.5 centered in the middle.

| Platform |
| -------- |
| iOS |
> Note: Cannot scroll to locations outside the render window without specifying the `getItemLayout` or `onScrollToIndexFailed` prop.

**Parameters:**

| Name | Type |
| ------------------------------------------------------- | ------ |
| params <div class="label basic required">Required</div> | object |

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.

## Type Definitions

Expand All @@ -493,10 +474,10 @@ An object that identifies the data to be rendered for a given section.

**Properties:**

| 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 | Description |
| ----------------------------------------------------- | ---------------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| data <div class="label basic required">Required</div> | array | The data for rendering items in this section. Array of objects, much like [`FlatList`'s data prop](flatlist#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#renderitem) for the list. |
| ItemSeparatorComponent | component, function, element | Optionally define an arbitrary item separator for this section, overriding the default [`ItemSeparatorComponent`](sectionlist#itemseparatorcomponent) for the list. |
| keyExtractor | function | Optionally define an arbitrary key extractor for this section, overriding the default [`keyExtractor`](sectionlist#keyextractor). |
Loading