diff --git a/docs/angular/virtual-scroll.md b/docs/angular/virtual-scroll.md index 0150d810162..634821b18f6 100644 --- a/docs/angular/virtual-scroll.md +++ b/docs/angular/virtual-scroll.md @@ -1,8 +1,12 @@ # Virtual Scroll -In the past, we have provided an `ion-virtual-scroll` component in Ionic Framework to help with list virtualization. At the time this was not available in Angular, but recently Angular has provided its own solution via the `@angular/cdk` package. +:::caution Looking for `ion-virtual-scroll`? -## Setup +`ion-virtual-scroll` was deprecated in v6.0.0 and removed in v7.0.0. We recommend using the `@angular/cdk` package detailed below. + +::: + +## Installation To setup the CDK Scroller, first install `@angular/cdk`: diff --git a/docs/api/virtual-scroll.md b/docs/api/virtual-scroll.md deleted file mode 100644 index 102220df3fb..00000000000 --- a/docs/api/virtual-scroll.md +++ /dev/null @@ -1,303 +0,0 @@ ---- -title: "ion-virtual-scroll" -hide_table_of_contents: true ---- -import Tabs from '@theme/Tabs'; -import TabItem from '@theme/TabItem'; - -import Props from '@site/static/auto-generated/virtual-scroll/props.md'; -import Events from '@site/static/auto-generated/virtual-scroll/events.md'; -import Methods from '@site/static/auto-generated/virtual-scroll/methods.md'; -import Parts from '@site/static/auto-generated/virtual-scroll/parts.md'; -import CustomProps from '@site/static/auto-generated/virtual-scroll/custom-props.md'; -import Slots from '@site/static/auto-generated/virtual-scroll/slots.md'; - - - ion-virtual-scroll | Angular Virtual Scroll List for Ionic Apps - - - -import EncapsulationPill from '@components/page/api/EncapsulationPill'; -import APITOCInline from '@components/page/api/APITOCInline'; - - - -

Contents

- - - - - -Virtual Scroll displays a virtual, "infinite" list. An array of records -is passed to the virtual scroll containing the data to create templates -for. The template created for each record, referred to as a cell, can -consist of items, headers, and footers. For performance reasons, not every record -in the list is rendered at once; instead a small subset of records (enough to fill the viewport) -are rendered and reused as the user scrolls. - -This guide will go over the recommended virtual scrolling packages for each framework integration as well as documentation for the deprecated `ion-virtual-scroll` component for Ionic Angular. We recommend using the framework-specific solutions listed below, but the `ion-virtual-scroll` documentation is available below for developers who are still using that component. - -## Angular - -For virtual scrolling options in Ionic Angular, please see [Angular Virtual Scroll Guide](../angular/virtual-scroll.md). - -## React - -For virtual scrolling options in Ionic React, please see [React Virtual Scroll Guide](../react/virtual-scroll.md). - -## Vue - -For virtual scrolling options in Ionic Vue, please see [Vue Virtual Scroll Guide](../vue/virtual-scroll.md). - ------- - -The following documentation applies to the `ion-virtual-scroll` component. - -## Approximate Widths and Heights - -If the height of items in the virtual scroll are not close to the -default size of `40px`, it is extremely important to provide a value for -the `approxItemHeight` property. An exact pixel-perfect size is not necessary, -but without an estimate the virtual scroll will not render correctly. - -The approximate width and height of each template is used to help -determine how many cells should be created, and to help calculate -the height of the scrollable area. Note that the actual rendered size -of each cell comes from the app's CSS, whereas this approximation -is only used to help calculate initial dimensions. - -It's also important to know that Ionic's default item sizes have -slightly different heights between platforms, which is perfectly fine. - -## Images Within Virtual Scroll - -HTTP requests, image decoding, and image rendering can cause jank while -scrolling. In order to better control images, Ionic provides `` -to manage HTTP requests and image rendering. While scrolling through items -quickly, `` knows when and when not to make requests, when and -when not to render images, and only loads the images that are viewable -after scrolling. [Read more about `ion-img`.](img.md) - -It's also important for app developers to ensure image sizes are locked in, -and after images have fully loaded they do not change size and affect any -other element sizes. Simply put, to ensure rendering bugs are not introduced, -it's vital that elements within a virtual item does not dynamically change. - -For virtual scrolling, the natural effects of the `` are not desirable -features. We recommend using the `` component over the native -`` element because when an `` element is added to the DOM, it -immediately makes a HTTP request for the image file. Additionally, `` -renders whenever it wants which could be while the user is scrolling. However, -`` is governed by the containing `ion-content` and does not render -images while scrolling quickly. - - -## Virtual Scroll Performance Tips - -### iOS Cordova WKWebView - -When deploying to iOS with Cordova, it's highly recommended to use the -[WKWebView plugin](https://blog.ionicframework.com/cordova-ios-performance-improvements-drop-in-speed-with-wkwebview/) -in order to take advantage of iOS's higher performing webview. Additionally, -WKWebView is superior at scrolling efficiently in comparison to the older -UIWebView. - -### Lock in element dimensions and locations - -In order for virtual scroll to efficiently size and locate every item, it's -very important every element within each virtual item does not dynamically -change its dimensions or location. The best way to ensure size and location -does not change, it's recommended each virtual item has locked in its size -via CSS. - -### Use `ion-img` for images - -When including images within Virtual Scroll, be sure to use -[`ion-img`](img.md) rather than the standard `` HTML element. -With `ion-img`, images are lazy loaded so only the viewable ones are -rendered, and HTTP requests are efficiently controlled while scrolling. - -### Set Approximate Widths and Heights - -As mentioned above, all elements should lock in their dimensions. However, -virtual scroll isn't aware of the dimensions until after they have been -rendered. For the initial render, virtual scroll still needs to set -how many items should be built. With "approx" property inputs, such as -`approxItemHeight`, we're able to give virtual scroll an approximate size, -therefore allowing virtual scroll to decide how many items should be -created. - -### Changing dataset should use `trackBy` - -It is possible for the identities of elements in the iterator to change -while the data does not. This can happen, for example, if the iterator -produced from an RPC to the server, and that RPC is re-run. Even if the -"data" hasn't changed, the second response will produce objects with -different identities, and Ionic will tear down the entire DOM and rebuild -it. This is an expensive operation and should be avoided if possible. - -### Efficient headers and footer functions -Each virtual item must stay extremely efficient, but one way to really -kill its performance is to perform any DOM operations within section header -and footer functions. These functions are called for every record in the -dataset, so please make sure they're performant. - - - -## Usage - -```html - - - -
- -
- - {{ item.name }} - - {{ item.content }} - - - -``` - -```typescript -export class VirtualScrollPageComponent { - items: any[] = []; - - constructor() { - for (let i = 0; i < 1000; i++) { - this.items.push({ - name: i + ' - ' + images[rotateImg], - imgSrc: getImgSrc(), - avatarSrc: getImgSrc(), - imgHeight: Math.floor(Math.random() * 50 + 150), - content: lorem.substring(0, Math.random() * (lorem.length - 100) + 100) - }); - - rotateImg++; - if (rotateImg === images.length) { - rotateImg = 0; - } - } - } -} - -const lorem = 'Lorem ipsum dolor sit amet, consectetur adipiscing elit, seddo eiusmod tempor incididunt ut labore et dolore magna aliqua. Ut enim ad minim veniam, quis nostrud exercitation ullamco laboris nisi ut aliquip ex ea commodo consequat. Duis aute irure dolor in reprehenderit in voluptate velit esse cillum dolore eu fugiat nulla pariatur. Excepteur sint occaecat cupidatat non proident, sunt in culpa qui officia deserunt mollit anim id est laborum.'; - -const images = [ - 'bandit', - 'batmobile', - 'blues-brothers', - 'bueller', - 'delorean', - 'eleanor', - 'general-lee', - 'ghostbusters', - 'knight-rider', - 'mirth-mobile' -]; - -function getImgSrc() { - const src = 'https://dummyimage.com/600x400/${Math.round( Math.random() * 99999)}/fff.png'; - rotateImg++; - if (rotateImg === images.length) { - rotateImg = 0; - } - return src; -} - -let rotateImg = 0; -``` - -### Basic - -The array of records should be passed to the `items` property on the `ion-virtual-scroll` element. -The data given to the `items` property must be an array. An item template with the `*virtualItem` property is required in the `ion-virtual-scroll`. The `*virtualItem` property can be added to any element. - -```html - - - {{ item }} - - -``` - -### Section Headers and Footers - -Section headers and footers are optional. They can be dynamically created -from developer-defined functions. For example, a large list of contacts -usually has a divider for each letter in the alphabet. Developers provide -their own custom function to be called on each record. The logic in the -custom function should determine whether to create the section template -and what data to provide to the template. The custom function should -return `null` if a template shouldn't be created. - -```html - - - {{ header }} - - - Item: {{ item }} - - -``` - -Below is an example of a custom function called on every record. It -gets passed the individual record, the record's index number, -and the entire array of records. In this example, after every 20 -records a header will be inserted. So between the 19th and 20th records, -between the 39th and 40th, and so on, a `` will -be created and the template's data will come from the function's -returned data. - -```ts -myHeaderFn(record, recordIndex, records) { - if (recordIndex % 20 === 0) { - return 'Header ' + recordIndex; - } - return null; -} -``` - - -### Custom Components - -If a custom component is going to be used within Virtual Scroll, it's best -to wrap it with a `
` to ensure the component is rendered correctly. Since -each custom component's implementation and internals can be quite different, wrapping -within a `
` is a safe way to make sure dimensions are measured correctly. - -```html - -
- - {{ item }} - -
- -``` - -## Properties - - -## Events - - -## Methods - - -## CSS Shadow Parts - - -## CSS Custom Properties - - -## Slots - \ No newline at end of file diff --git a/docs/react/virtual-scroll.md b/docs/react/virtual-scroll.md index de6aa30a9d1..b77bf341b69 100644 --- a/docs/react/virtual-scroll.md +++ b/docs/react/virtual-scroll.md @@ -1,5 +1,11 @@ # Virtual Scroll +:::caution Looking for `ion-virtual-scroll`? + +`ion-virtual-scroll` was deprecated in v6.0.0 and removed in v7.0.0. We recommend using the Virtuoso package detailed below. + +::: + One virtual scrolling solution to consider for your Ionic React app is [Virtuoso](https://virtuoso.dev/). This guide will go over how to install `Virtuoso` into your Ionic React application and use it with other Ionic components. ## Installation @@ -51,12 +57,6 @@ From there, we can use the `itemContent` property to pass a function that will b An important thing to note here is the `div` that wraps our `IonItem` component. When lazy loading Ionic components, there may be a few frames where the component is loaded but the styles have not loaded in. When this happens, the component's dimension will be `0`, and Virtuoso may throw an error. This is because Virtuoso needs distinct positions for each item it renders, and it cannot determine that when a component's dimension is `0`. -## A Note on Ionic Components - -Certain Ionic Framework functionality is currently not compatible with virtual scrolling. Features such as collapsible large titles, `ion-infinite-scroll`, and `ion-refresher` rely on being able to scroll on `ion-content` itself, and as a result will not work when using virtual scrolling. - -We are working to improve compatibility between these components and virtual scrolling solutions. You can follow progress and give feedback here: https://github.com/ionic-team/ionic-framework/issues/23437. - ## Usage with Ionic Components Ionic Framework requires that features such as collapsible large titles, `ion-infinite-scroll`, `ion-refresher`, and `ion-reorder-group` be used within an `ion-content`. To use these experiences with virtual scrolling, you must add the `.ion-content-scroll-host` class to the virtual scroll viewport. @@ -66,9 +66,7 @@ For example: ```tsx - - {/* Your existing content and configurations */} - + {/* Your existing content and configurations */} ``` diff --git a/docs/vue/virtual-scroll.md b/docs/vue/virtual-scroll.md index 47c3ebcf204..24c90d7503b 100644 --- a/docs/vue/virtual-scroll.md +++ b/docs/vue/virtual-scroll.md @@ -1,6 +1,10 @@ # Virtual Scroll -One virtual scrolling solution to consider for your Ionic Vue app is [vue-virtual-scroller](https://github.com/Akryum/vue-virtual-scroller/blob/next/packages/vue-virtual-scroller/README.md). This guide will go over how to install `vue-virtual-scroller` into your Ionic Vue application and use it with other Ionic components. +:::caution Looking for `ion-virtual-scroll`? + +`ion-virtual-scroll` was deprecated in v6.0.0 and removed in v7.0.0. We recommend using a Vue library to accomplish this. We outline one approach using `vue-virtual-scroller` below. + +::: ## Installation diff --git a/sidebars.js b/sidebars.js index e6231ae0a68..37be85167db 100644 --- a/sidebars.js +++ b/sidebars.js @@ -344,7 +344,7 @@ module.exports = { type: 'category', label: 'List', collapsed: false, - items: ['api/list', 'api/list-header', 'api/virtual-scroll'], + items: ['api/list', 'api/list-header'], }, { type: 'category',