Skip to content

Commit 1559147

Browse files
mmalerbammalerba
authored
docs(cdk/scrolling): Docs for new virtual scroll features added in #24394 (#25043)
1 parent 176213d commit 1559147

12 files changed

+114
-22
lines changed

‎src/cdk/scrolling/scrolling.md

Lines changed: 18 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -128,3 +128,21 @@ to the list as the user scrolls without removing rendered views. The `appendOnly
128128
views that are already rendered persist in the DOM after they scroll out of view.
129129

130130
<!-- example(cdk-virtual-scroll-append-only) -->
131+
132+
### Separate viewport and scrolling element
133+
The virtual scroll viewport itself acts as the scrolling element by default. However, there may be
134+
some cases where you want to have the viewport scroll one of its parent elements. For example,
135+
if you want to have some non-virtualized content that the user can scroll through before or after
136+
the virtualized content.
137+
138+
To configure a `cdk-vritual-scroll-viewport` to use one of its parent elements as the scrolling
139+
element, apply `cdkVirtualScrollingElement` to the scrolling parent element.
140+
141+
<!-- example(cdk-virtual-scroll-parent-scrolling) -->
142+
143+
Another common scenario is using the window itself as the scrolling element. This often a better
144+
user experience on mobile devices, as it allows the browser chrome to scroll away. To use the
145+
window as the scrolling element, add the `scrollWindow` attribute to the
146+
`cdk-virtual-scroll-viewport`.
147+
148+
<!-- example(cdk-virtual-scroll-window-scrolling) -->

‎src/components-examples/cdk/scrolling/cdk-virtual-scroll-parent-scrolling/cdk-virtual-scroll-parent-scrolling-example.css

Lines changed: 16 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,16 @@
1+
.example-viewport {
2+
flex: 1;
3+
width: 200px;
4+
min-height: 200px;
5+
border: 1px solid black;
6+
}
7+
8+
.example-item {
9+
height: 50px;
10+
}
11+
12+
.example-header,
13+
.example-footer {
14+
height: 100px;
15+
background: lightgray;
16+
}

‎src/components-examples/cdk/scrolling/cdk-virtual-scroll-parent-scrolling/cdk-virtual-scroll-parent-scrolling-example.html

Lines changed: 7 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,7 @@
1+
<div class="example-viewport" cdkVirtualScrollingElement>
2+
<div class="example-header">Content before</div>
3+
<cdk-virtual-scroll-viewport itemSize="50">
4+
<div *cdkVirtualFor="let item of items" class="example-item">{{item}}</div>
5+
</cdk-virtual-scroll-viewport>
6+
<div class="example-footer">Content after</div>
7+
</div>

‎src/components-examples/cdk/scrolling/cdk-virtual-scroll-parent-scrolling/cdk-virtual-scroll-parent-scrolling-example.ts

Lines changed: 12 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,12 @@
1+
import {ChangeDetectionStrategy, Component} from '@angular/core';
2+
3+
/** @title Virtual scrolling viewport parent element */
4+
@Component({
5+
selector: 'cdk-virtual-scroll-parent-scrolling-example',
6+
styleUrls: ['cdk-virtual-scroll-parent-scrolling-example.css'],
7+
templateUrl: 'cdk-virtual-scroll-parent-scrolling-example.html',
8+
changeDetection: ChangeDetectionStrategy.OnPush,
9+
})
10+
export class CdkVirtualScrollParentScrollingExample {
11+
items = Array.from({length: 100000}).map((_, i) => `Item #${i}`);
12+
}

‎src/components-examples/cdk/scrolling/cdk-virtual-scroll-window-scrolling/cdk-virtual-scroll-window-scrolling-example.css

Lines changed: 9 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,9 @@
1+
.example-item {
2+
height: 50px;
3+
}
4+
5+
.example-header,
6+
.example-footer {
7+
height: 100px;
8+
background: lightgray;
9+
}

‎src/components-examples/cdk/scrolling/cdk-virtual-scroll-window-scrolling/cdk-virtual-scroll-window-scrolling-example.html

Lines changed: 9 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,9 @@
1+
<ng-container *ngIf="shouldRun">
2+
<div class="example-header">Content before</div>
3+
<cdk-virtual-scroll-viewport scrollWindow itemSize="50">
4+
<div *cdkVirtualFor="let item of items" class="example-item">{{item}}</div>
5+
</cdk-virtual-scroll-viewport>
6+
<div class="example-footer">Content after</div>
7+
</ng-container>
8+
9+
<div *ngIf="!shouldRun">Please open on StackBlitz to see result</div>

‎src/components-examples/cdk/scrolling/cdk-virtual-scroll-window-scrolling/cdk-virtual-scroll-window-scrolling-example.ts

Lines changed: 14 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,14 @@
1+
import {ChangeDetectionStrategy, Component, Input} from '@angular/core';
2+
3+
/** @title Virtual scrolling window */
4+
@Component({
5+
selector: 'cdk-virtual-scroll-window-scrolling-example',
6+
styleUrls: ['cdk-virtual-scroll-window-scrolling-example.css'],
7+
templateUrl: 'cdk-virtual-scroll-window-scrolling-example.html',
8+
changeDetection: ChangeDetectionStrategy.OnPush,
9+
})
10+
export class CdkVirtualScrollWindowScrollingExample {
11+
@Input() shouldRun = /(^|.)(stackblitz|webcontainer).(io|com)$/.test(window.location.host);
12+
13+
items = Array.from({length: 100000}).map((_, i) => `Item #${i}`);
14+
}

‎src/components-examples/cdk/scrolling/index.ts

Lines changed: 8 additions & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -8,7 +8,10 @@ import {CdkVirtualScrollDlExample} from './cdk-virtual-scroll-dl/cdk-virtual-scr
88
import {CdkVirtualScrollFixedBufferExample} from './cdk-virtual-scroll-fixed-buffer/cdk-virtual-scroll-fixed-buffer-example';
99
import {CdkVirtualScrollHorizontalExample} from './cdk-virtual-scroll-horizontal/cdk-virtual-scroll-horizontal-example';
1010
import {CdkVirtualScrollOverviewExample} from './cdk-virtual-scroll-overview/cdk-virtual-scroll-overview-example';
11+
import {CdkVirtualScrollParentScrollingExample} from './cdk-virtual-scroll-parent-scrolling/cdk-virtual-scroll-parent-scrolling-example';
1112
import {CdkVirtualScrollTemplateCacheExample} from './cdk-virtual-scroll-template-cache/cdk-virtual-scroll-template-cache-example';
13+
import {CdkVirtualScrollWindowScrollingExample} from './cdk-virtual-scroll-window-scrolling/cdk-virtual-scroll-window-scrolling-example';
14+
import {CommonModule} from '@angular/common';
1215

1316
export {
1417
CdkVirtualScrollAppendOnlyExample,
@@ -20,6 +23,8 @@ export {
2023
CdkVirtualScrollHorizontalExample,
2124
CdkVirtualScrollOverviewExample,
2225
CdkVirtualScrollTemplateCacheExample,
26+
CdkVirtualScrollParentScrollingExample,
27+
CdkVirtualScrollWindowScrollingExample,
2328
};
2429

2530
const EXAMPLES = [
@@ -32,10 +37,12 @@ const EXAMPLES = [
3237
CdkVirtualScrollHorizontalExample,
3338
CdkVirtualScrollOverviewExample,
3439
CdkVirtualScrollTemplateCacheExample,
40+
CdkVirtualScrollParentScrollingExample,
41+
CdkVirtualScrollWindowScrollingExample,
3542
];
3643

3744
@NgModule({
38-
imports: [ScrollingModule],
45+
imports: [CommonModule, ScrollingModule],
3946
declarations: EXAMPLES,
4047
exports: EXAMPLES,
4148
})

‎src/dev-app/virtual-scroll/BUILD.bazel

Lines changed: 1 addition & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -12,6 +12,7 @@ ng_module(
1212
deps = [
1313
"//src/cdk-experimental/scrolling",
1414
"//src/cdk/scrolling",
15+
"//src/components-examples/cdk/scrolling",
1516
"//src/material/button",
1617
"//src/material/form-field",
1718
"//src/material/input",

‎src/dev-app/virtual-scroll/virtual-scroll-demo.html

Lines changed: 7 additions & 21 deletions
Original file line numberDiff line numberDiff line change
@@ -179,24 +179,10 @@ <h2>Append only</h2>
179179
</div>
180180
</cdk-virtual-scroll-viewport>
181181

182-
<h2>Custom virtual scroller</h2>
183-
184-
<div class="demo-viewport" cdkVirtualScrollingElement>
185-
<p>Content before virtual scrolling items</p>
186-
<cdk-virtual-scroll-viewport itemSize="50">
187-
<div *cdkVirtualFor="let size of fixedSizeData; let i = index" class="demo-item"
188-
[style.height.px]="size">
189-
Item #{{i}} - ({{size}}px)
190-
</div>
191-
</cdk-virtual-scroll-viewport>
192-
<p>Content after virtual scrolling items</p>
193-
</div>
194-
195-
<h2>Window virtual scroller</h2>
196-
197-
<cdk-virtual-scroll-viewport scrollWindow itemSize="50">
198-
<div *cdkVirtualFor="let size of fixedSizeData; let i = index" class="demo-item"
199-
[style.height.px]="size">
200-
Item #{{i}} - ({{size}}px)
201-
</div>
202-
</cdk-virtual-scroll-viewport>
182+
<h2>Virtual scroller with scrolling parent</h2>
183+
<cdk-virtual-scroll-parent-scrolling-example class="demo-resize-example">
184+
</cdk-virtual-scroll-parent-scrolling-example>
185+
186+
<h2>Virtual scroller with scrolling window</h2>
187+
<cdk-virtual-scroll-window-scrolling-example [shouldRun]="true">
188+
</cdk-virtual-scroll-window-scrolling-example>

‎src/dev-app/virtual-scroll/virtual-scroll-demo.scss

Lines changed: 11 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -53,3 +53,14 @@
5353
.demo-td {
5454
border: 1px solid gray;
5555
}
56+
57+
.demo-resize-example {
58+
display: flex;
59+
width: 500px;
60+
height: 500px;
61+
}
62+
63+
cdk-virtual-scroll-window-scrolling-example {
64+
display: block;
65+
width: 500px;
66+
}

‎src/dev-app/virtual-scroll/virtual-scroll-demo.ts

Lines changed: 2 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -16,6 +16,7 @@ import {MatFormFieldModule} from '@angular/material/form-field';
1616
import {MatInputModule} from '@angular/material/input';
1717
import {MatSelectModule} from '@angular/material/select';
1818
import {BehaviorSubject} from 'rxjs';
19+
import {CdkScrollingExamplesModule} from '@angular/components-examples/cdk/scrolling';
1920

2021
type State = {
2122
name: string;
@@ -38,6 +39,7 @@ type State = {
3839
MatInputModule,
3940
MatSelectModule,
4041
ScrollingModule,
42+
CdkScrollingExamplesModule,
4143
],
4244
})
4345
export class VirtualScrollDemo implements OnDestroy {

0 commit comments

Comments
 (0)