diff --git a/resources/views/docs/mobile/4/edge-components/list.md b/resources/views/docs/mobile/4/edge-components/list.md index 09722a47..287fa62f 100644 --- a/resources/views/docs/mobile/4/edge-components/list.md +++ b/resources/views/docs/mobile/4/edge-components/list.md @@ -37,6 +37,8 @@ Pair with [``](#list-item) for Material3 list rows, or use any - `on-refresh` - Component method called on pull-to-refresh (optional, string) [iOS] - `on-end-reached` - Component method called when the user nears the end of the list (optional, string) - `end-reached-buffer` - Number of items from the end at which `on-end-reached` is triggered (optional, integer, default: `3`) +- `auto-scroll-to` - Index of the row to open the list at, + counting from `0`. Negative values turn it off. See [Opening at a row](#opening-at-a-row) (optional, integer) ## Children @@ -317,6 +319,35 @@ here just gives the demo enough rows to scroll before the end-reached trigger fi A buffer of `5` triggers `loadMore()` when the list is within five items of the end. When omitted, the buffer defaults to `3`. @endverbatim +### Opening at a row + + + +Use `auto-scroll-to` to open a list with a given row at the top. It's useful for a deep link to a record, a screen +restored after a relaunch, or a row the user has just added. + +@verbatim +```blade static + + @foreach ($posts as $post) + + @endforeach + +``` +@endverbatim + +Rows count from `0` in the order they're written. In a list with [sections](#list-section), the rows count straight +through the sections, and section headers and footers don't count. + +The list jumps to the row when it's created, and scrolls to it again, animated, only when the index changes. A +re-render that keeps the same index leaves the list where the user scrolled it. If the row hasn't loaded yet, for +example while `on-end-reached` fetches the next page, the list scrolls to it when it arrives. + +Content changes on their own don't apply the index again. To scroll to the same row a second time, render once with a +negative index, then set the row again in a later render. + +To open a [virtual list](virtual-list#opening-at-a-row) at a row, its window has to hold that row as well. + ## Testing a list In a [component test](../testing/introduction), target a row's callbacks by the expression you wrote in the template. @@ -359,6 +390,7 @@ NativeList::make( - `onRefresh(string $method)` - Pull-to-refresh handler - `onEndReached(string $method)` - End-reached handler - `endReachedBuffer(int $items)` - Number of items from the end at which the end-reached handler is triggered (default: `3`) +- `autoScrollTo(int $index)` - Open the list at row `$index`. See [Opening at a row](#opening-at-a-row) ### `ListItem` methods diff --git a/resources/views/docs/mobile/4/edge-components/virtual-list.md b/resources/views/docs/mobile/4/edge-components/virtual-list.md index 7d8a6bdc..e34f38cd 100644 --- a/resources/views/docs/mobile/4/edge-components/virtual-list.md +++ b/resources/views/docs/mobile/4/edge-components/virtual-list.md @@ -33,6 +33,8 @@ scrolls, and the next render emits the new slice. - `estimated-row-height` - Estimated row height in dp, used to size the scroll extent before rows measure (optional, float, default: `56`). - `overscan` - Extra rows built beyond the visible window to smooth fast scrolling (optional, int, default: `30`). +- `auto-scroll-to` - Absolute index of the row to open the + list at. Negative values turn it off. See [Opening at a row](#opening-at-a-row) (optional, int). `` is self-closing — the `item` view is the row template, not slot content. @@ -43,7 +45,7 @@ state (defaulting to a `0–79` first-paint window) and the `setVirtualWindow()` at: ```php -use Native\Mobile\Edge\Traits\HasVirtualListWindow; +use Native\Mobile\Edge\Concerns\HasVirtualListWindow; class ContactsScreen extends NativeComponent { @@ -69,6 +71,41 @@ The row view renders one item by absolute index: ``` @endverbatim +## Opening at a row + + + +A virtual list draws only the rows inside its window, so to open it at a row, the window has to hold that row. Call +`scrollVirtualListTo()` from the trait, for example in `mount()`, and pass `$virtualScrollTo` to the list's +`auto-scroll-to`: + +```php +public function mount(int $contact): void +{ + $this->scrollVirtualListTo($contact); +} +``` + +@verbatim +```blade static + +``` +@endverbatim + +`scrollVirtualListTo(int $index)` moves the window to start a quarter of its size above the row, keeps its size, and +sets `$virtualScrollTo` to the row. `$virtualScrollTo` is `null` until you call it. The row is in the same render +that scrolls to it, so the list opens on the row itself rather than a placeholder. + +`auto-scroll-to` behaves as it does on [``](list#opening-at-a-row): the list scrolls when it's created +and again when the index changes, and a re-render that keeps the same index leaves the list where the user scrolled +it. +